diff --git a/docs/skills.md b/docs/skills.md index afbac0d2de..107de805d7 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 0000000000..57fa897ff9 --- /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 912e1f3ec5..f551ffd07c 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 712b91a905..645ec68cc9 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?**