From f2e9b32a10977db20c9e3490e90f6d9062ed0c6c Mon Sep 17 00:00:00 2001 From: Eric Van Boxsom Date: Tue, 24 Mar 2026 18:29:57 +0100 Subject: [PATCH] feat(review): read `## Review` section from CLAUDE.md as repo-specific context MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /review now checks CLAUDE.md for a `## Review` section before scope drift detection. This gives teams a clean place for repo-specific calibration — high-risk paths, auto-fix boundaries, escalation rules, external consumers — without forking the skill or cramming non-checklist content into checklist.md. Additive only. Skips silently if the section doesn't exist. The mandatory checklist.md remains the source of truth for the rubric and output format. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/skills.md | 8 ++++++++ examples/CLAUDE.md.review.example | 15 +++++++++++++++ review/SKILL.md | 10 ++++++++++ review/SKILL.md.tmpl | 10 ++++++++++ 4 files changed, 43 insertions(+) create mode 100644 examples/CLAUDE.md.review.example diff --git a/docs/skills.md b/docs/skills.md index afbac0d2d..107de805d 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -449,6 +449,14 @@ That is the point of `/review`. I do not want flattery here. I want the model imagining the production incident before it happens. +### Repo-owned review context + +`/review` already uses `.claude/skills/review/checklist.md` for the actual rubric. + +If you need to calibrate `/review` for your specific repo — scope rules, high-risk paths, trust boundaries, auto-fix boundaries, escalation rules, or external consumers — add a `## Review` section to your project's `CLAUDE.md`. + +`/review` reads it before scope drift detection and uses it for risk and scope calibration. Skips silently if the section doesn't exist. + --- ## `/investigate` diff --git a/examples/CLAUDE.md.review.example b/examples/CLAUDE.md.review.example new file mode 100644 index 000000000..57fa897ff --- /dev/null +++ b/examples/CLAUDE.md.review.example @@ -0,0 +1,15 @@ +# Example: `## Review` section for CLAUDE.md + +Add this section to your project's `CLAUDE.md` to give `/review` repo-specific context. + +```markdown +## Review + +- Source of truth for intent: if the PR or commit message links a GitHub issue / Linear ticket, read it before deciding scope drift. +- High-risk paths: `db/migrate/**`, `app/services/billing/**`, `config/initializers/auth*`. +- Never AUTO-FIX without explicit approval: money movement, auth/session logic, customer-visible API contract changes. +- External consumers exist outside this repo: mobile app, webhooks, warehouse sync jobs. +- Known hotspot: `app/services/reconciliation/**` has intentionally defensive duplication; do not flag it as dead code without tracing the call sites. +- If a diff touches a high-risk path and the stated intent is silent about it, call out probable scope drift explicitly. +- If auth or billing code changes, prefer ASK over AUTO-FIX unless the fix is obviously mechanical and reversible. +``` diff --git a/review/SKILL.md b/review/SKILL.md index 912e1f3ec..f551ffd07 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -288,6 +288,16 @@ You are running the `/review` workflow. Analyze the current branch's diff agains --- +## Step 1.25: Read project review context (optional) + +Before the main review, check `CLAUDE.md` for a `## Review` section. If present, read it as additive repo-specific context — not a replacement for `.claude/skills/review/checklist.md`. + +Use it for scope calibration (source of truth for intent, ticketing conventions), risk calibration (high-risk paths, trust boundaries), escalation rules (who to involve for auth/billing changes), and auto-fix boundaries (areas that should never be AUTO-FIXed without explicit approval). + +If this context names an accessible ticketing source of truth, use it during Scope Drift Detection in Step 1.5. If no `## Review` section exists, skip silently. + +--- + ## Step 1.5: Scope Drift Detection Before reviewing code quality, check: **did they build what was requested — nothing more, nothing less?** diff --git a/review/SKILL.md.tmpl b/review/SKILL.md.tmpl index 712b91a90..645ec68cc 100644 --- a/review/SKILL.md.tmpl +++ b/review/SKILL.md.tmpl @@ -37,6 +37,16 @@ You are running the `/review` workflow. Analyze the current branch's diff agains --- +## Step 1.25: Read project review context (optional) + +Before the main review, check `CLAUDE.md` for a `## Review` section. If present, read it as additive repo-specific context — not a replacement for `.claude/skills/review/checklist.md`. + +Use it for scope calibration (source of truth for intent, ticketing conventions), risk calibration (high-risk paths, trust boundaries), escalation rules (who to involve for auth/billing changes), and auto-fix boundaries (areas that should never be AUTO-FIXed without explicit approval). + +If this context names an accessible ticketing source of truth, use it during Scope Drift Detection in Step 1.5. If no `## Review` section exists, skip silently. + +--- + ## Step 1.5: Scope Drift Detection Before reviewing code quality, check: **did they build what was requested — nothing more, nothing less?**