From e12ac994656e0d30b87c7d12ad6556bf52e4e6ee Mon Sep 17 00:00:00 2001 From: Mathias Date: Sat, 29 Aug 2026 11:27:52 +0200 Subject: [PATCH] docs(review): cross-link the three review skills, drop a false citation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three similarly-named skills cover orthogonal concerns — what to check (code-review), how to commission a reviewer (requesting), how to behave when feedback arrives (receiving) — and none of them mentioned the other two. An agent landing on one had no way to learn the others existed. One line each, placed at the core-principle line where a reader is already oriented. stage-gate-review's gate-prep step now says to run grill-me's Full Grill before bringing an ask: a council's hard questions are cheaper answered in private, and a gap found by grilling is one you close rather than one the gate reports. The bug half: receiving-code-review cited "You're absolutely right!" as an "explicit CLAUDE.md violation". That is obra's upstream convention leaking through the vendored copy — `grep -ci "absolutely right" ~/dev/CLAUDE.md` is 0, and so is AGENT.md. The guidance is right, the citation was inventing authority it did not have; it now says what it actually is, performative agreement rather than evaluation. Closes #16 Bump-Type: patch --- skills/code-review/SKILL.md | 2 ++ skills/stage-gate-review/SKILL.md | 3 +++ skills/superpowers-receiving-code-review/SKILL.md | 4 +++- skills/superpowers-requesting-code-review/SKILL.md | 2 ++ 4 files changed, 10 insertions(+), 1 deletion(-) diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 694ea68..35f8c40 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -14,6 +14,8 @@ Code review is smell detection and principle verification, not style policing. T **This skill is read-only analysis.** When you find issues, document them with specific file:line references and prioritize by architectural impact. For fixes, load the `refactoring` or `clean-code` skill. +Three similarly-named skills cover orthogonal concerns, and landing on one is no reason to miss the others: this one is **what to check**, `superpowers-requesting-code-review` is **how to commission a reviewer**, and `superpowers-receiving-code-review` is **how to behave when the feedback arrives**. + ## When to Use - Pre-merge review of any pull request diff --git a/skills/stage-gate-review/SKILL.md b/skills/stage-gate-review/SKILL.md index 490ccb6..84e50c7 100644 --- a/skills/stage-gate-review/SKILL.md +++ b/skills/stage-gate-review/SKILL.md @@ -74,6 +74,9 @@ legal waived"), never silently dropped. Silent omission is the most common way a 3. Mark every discipline: cleared / waived (with reason) / gap. 4. If any gap is on a discipline that gates the whole bet, **do not bring the ask** — close the gap or bring a feedback-only ask instead. +5. Load `grill-me` (Full Grill) on the ask before bringing it. A council's hard questions are + cheaper to answer in private first, and a gap found by grilling is a gap you close rather + than one the gate reports. **Chairing a review (you are the council):** 1. Ask for the evidence behind each "cleared", not the claim. Claims are theatre. diff --git a/skills/superpowers-receiving-code-review/SKILL.md b/skills/superpowers-receiving-code-review/SKILL.md index d5fd740..e079e7b 100644 --- a/skills/superpowers-receiving-code-review/SKILL.md +++ b/skills/superpowers-receiving-code-review/SKILL.md @@ -14,6 +14,8 @@ Code review requires technical evaluation, not emotional performance. **Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort. +This skill starts where `superpowers-requesting-code-review` ends. The substance of what a reviewer should have checked is `code-review`. + ## The Response Pattern ``` @@ -30,7 +32,7 @@ WHEN receiving code review feedback: ## Forbidden Responses **NEVER:** -- "You're absolutely right!" (explicit CLAUDE.md violation) +- "You're absolutely right!" (performative agreement, not evaluation) - "Great point!" / "Excellent feedback!" (performative) - "Let me implement that now" (before verification) diff --git a/skills/superpowers-requesting-code-review/SKILL.md b/skills/superpowers-requesting-code-review/SKILL.md index f4a5933..f02f306 100644 --- a/skills/superpowers-requesting-code-review/SKILL.md +++ b/skills/superpowers-requesting-code-review/SKILL.md @@ -12,6 +12,8 @@ Dispatch a code reviewer subagent to catch issues before they cascade. The revie **Core principle:** Review early, review often. +This skill is the *commissioning* half. What the reviewer should look for is `code-review`; how to handle what comes back is `superpowers-receiving-code-review`. + ## When to Request Review **Mandatory:**