[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval.
[BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends.
[BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason.
[BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.
[TOP REMINDER — WHY-REVIEW FINDINGS-VALIDATION GATE IS NON-NEGOTIABLE]
If this review produces ANY finding (Critical / High / Medium / Low) in standalone mode, you MUST invoke the /why-review skill through the Skill tool with --validate-findings <report-path> before any fix, docs-update, commit, or handoff. An actual skill call is the ONLY way to pass this gate — re-reading the cited file:lines yourself, "self-validating," or any inline/manual substitute does NOT count.
Create the todo the moment the first finding is recorded — never rely on memory: call TaskCreate → [Review Phase 6] Why-review findings validation gate — invoke /why-review so the gate is tracked and cannot be skipped. Inside $workflow-review-changes, stop after the report; parent step 2 owns validation. Full protocol in Phase 6; mirrored in the Closing Reminders at the bottom.
Quick Summary
Goal: Review current working-tree, staged, branch, or commit diffs across code, docs, config, infra, and non-code artifacts — finding correctness bugs, flaws, missing updates, stale docs, and convention drift with evidence — so every reviewed change is defect-free, evidence-backed, convention-aligned, and synchronized with required tests/docs before handoff; when code files changed, also prove the code stays easy to change.
Summary: read-this-if-nothing-else digest —
- Report-driven and evidence-gated. Every finding is written to
plans/reports/code-review-{date}-{slug}.md with file:line proof; speculation is forbidden, "looks fine" is not a verdict, codebase convention (grep 3+ examples) wins over textbook rules.
- Self-recursive loop is protocol-bound (goal-gated when available). Standalone mode's FIRST action (Phase -1) binds the review loop as a standing protocol obligation you self-drive — and installs a
/goal Stop-hook condition WHEN available — so stopping is BLOCKED until the loop converges. Findings are never auto-fixed on sight: validate (Phase 6 /why-review --validate-findings, an actual skill call) → SELF-FIX (Phase 7) → restart /changes-review from Phase 0 over the WHOLE updated diff (combined with prior fixes, not just the last fix), looping until one whole pass clears that round's exit bar — zero findings in rounds 1-2, zero CRITICAL/HIGH/MEDIUM from round 3 (a LOW-only round ENDS the loop; list those LOWs as deferred, never fix-and-loop for them). Inside $workflow-review-changes you skip Phase -1, stop after the report, and hand findings to the parent (which owns the goal).
- When code changed, three delegated gates are MANDATORY: Phase 3.5
/code-simplifier (clarity/maintainability), Phase 3.7 /integration-test-review Gate-7 coverage (every behavior change → covering test + spec TC), and — for every behavior change — Spec Drift Adjudication + the Dual-Feedback Ledger (the gap feeds BOTH spec AND tests).
- Docs-update is the unconditional terminal step. Once the loop converges clean, Phase 8
/docs-update ALWAYS runs over the full changeset (deferred only to the parent inside the workflow).
- MUST ATTENTION — run ALL main phases in order (the steps AI keeps forgetting): Phase -1 bind self-recursive review loop — protocol-primary, optional
/goal gate when available (standalone, FIRST action) → 0 /graph-blast-radius → 0.1 change-context + full-pipeline trace (tier FE↔BE + cross-service/event) → 0.3 change-type risk tasks → 0.7 surface-detection dimension tasks → 0.8 parallel full-mode /why-review rationale sub-agent, spawned in the SAME batch as the 0.7 agents → 0.5 plan compliance → 1 collect diff + create report → 2 file-by-file review → 3 fresh-context gate (SKIP when findings exist) → 3.5 /code-simplifier (code diffs) → 3.7 /integration-test-review Gate-7 coverage (behavior diffs) → 4 finalize + Dual-Feedback Ledger → 5 docs triage → 6 /why-review --validate-findings → 7 self-fix + full restart from Phase 0 → 7.5 holistic full-mode /why-review → 8 /docs-update (unconditional terminal) — why: a skipped phase silently drops a guard (coverage, spec-drift, holistic review, or docs sync) and ships unreviewed work.
Routing boundary: This skill reviews a git diff — working-tree (default), staged, branch, or commit. For an explicit file-set or SHA-range review, processing received review feedback, or a pre-completion verification gate over already-known scope, use code-review instead.
Shared engine (keep in sync): changes-review and code-review share the same review-protocol SYNC: blocks. Canonical source: .claude/skills/shared/sync-inline-versions.md; policy: SYNC:shared-protocol-duplication-policy. When you change a shared block in one skill, update the canonical file AND the sibling skill so the two never drift. The skills differ only in entry intent (diff vs explicit scope) and diff-specific gates (integration-test-sync, translation-sync, the Phase 3.7 integration-test-review coverage gate) — not in review quality.
Workflow:
- Phase -1: Bind the Self-Recursive Review Loop (FIRST ACTION — standalone-only; protocol-first,
/goal optional) — Before any other work, in standalone mode bind the review loop as a standing protocol obligation you self-drive — and, WHEN available, invoke the /goal command as an ACTUAL call — with a self-recursive review-loop condition so stopping is BLOCKED until the loop converges: review the full diff → validate findings (Phase 6) → SELF-FIX validated findings (Phase 7) → restart /changes-review from Phase 0 over the WHOLE updated diff (combined with the prior fixes, never just re-checking the last fix) → loop until one complete pass clears that round's exit bar — zero findings in rounds 1-2, zero CRITICAL/HIGH/MEDIUM from round 3 (a LOW-only round ENDS the loop; list those LOWs as deferred, never fix-and-loop for them), then docs-update. Skip this gate when running as step 1 inside $workflow-review-changes (the parent owns the goal). Full procedure in Phase -1.
- Phase 0: Blast Radius — Call
/graph-blast-radius skill FIRST (if .code-graph/graph.db exists)
- Phase 0.1: Change Context & Full-Pipeline Impact Trace (MANDATORY comprehension-first) — Note the change context, then holistically trace the main affected area's full pipeline across BOTH boundaries — client↔server tier (FE↔BE) AND service/event/external — classifying each seam/touchpoint NONE/ADDITIVE/BREAKING (explicit N/A for single-tier or monolith)
- Phase 0.3: Change Types — Detect high-risk change types; create risk tasks
- Phase 0.5: Plan Compliance — Verify against active plan (conditional)
- Phase 0.7: Surface Detection — AI categorizes changed files; creates dimension tasks
- Phase 0.8: Parallel Rationale Review — Spawn a full-mode
/why-review sub-agent in the SAME parallel batch as the 0.7 dimensional agents; its findings merge into the Phase 4 final evaluation (standalone-only)
- Phase 1: Collect — Run git status/diff, create report file
- Phase 2: File Review — Review each changed file, update report incrementally
- Phase 3: Fresh-Context Gate — Skip when findings already exist; run a second-round sub-agent only for an explicit user/workflow/high-risk synthesis trigger
- Phase 3.5: Code-Simplifier Optimization (MANDATORY when code files changed) — Invoke
/code-simplifier scoped to the changed code files to surface clarity/consistency/maintainability simplifications; record them as findings that flow into the same validation/fix loop (skip docs-only diffs)
- Phase 3.7: Integration-Test-Review Coverage Gate (MANDATORY when behavior-bearing code changed) — Invoke
/integration-test-review over the full diff; its 8 quality gates audit changed tests AND its Gate 7 (Change Coverage) maps every behavior-changing production file to a covering test (integration-first; unit fallback needs justification) and a spec TC. GAP/SPEC-GAP results become findings for the same validation/fix loop (skip docs-only diffs; deferred to the parent's dedicated step inside $workflow-review-changes)
- Phase 3.8: Domain Entity Gate (MANDATORY when the diff touches an entity/VO/aggregate) — Apply
SYNC:domain-entity-change-gate over the changed domain types; Mode A reviews inline, Mode B delegates to /domain-entities-review (its A–P checklist owns the gate). Findings flow into the same validation/fix loop (skip when no domain-entity surface)
- Phase 4: Finalize — Generate critical issues, recommendations, suggested commit message
- Phase 5: Docs Triage — Record stale-doc findings for validation/fix loop
- Phase 6: Why-Review Findings Validation (standalone-only; REQUIRED before any standalone fix) — Whenever the report contains one or more findings, you MUST invoke the
/why-review skill (an actual Skill-tool call) with --validate-findings to verify every finding is correct, proof-backed, reasonable, and best-practice before fixing. This is a genuine skill invocation — re-reading the cited lines yourself, "self-validating," or any inline/manual substitute does NOT satisfy this gate. When this skill is step 1 inside $workflow-review-changes, stop after the report; parent step 2 owns findings validation.
- Phase 7: Recursive Fix + Full Re-Review Loop (standalone-only) — If validated findings remain in standalone mode, auto-fix them, then re-invoke
/changes-review from Phase 0 with a fresh task breakdown over the full current diff; repeat until an entire review pass clears that round's exit bar — zero findings in rounds 1-2, zero CRITICAL/HIGH/MEDIUM from round 3 (a LOW-only round ENDS the loop; list those LOWs as deferred, never fix-and-loop for them). When inside $workflow-review-changes, parent steps 10-15 own plan/feature-implement/restart.
- Phase 7.5: Holistic Standalone Full-Mode Why-Review Gate (standalone-only) — Once the dimensional review/fix loop converges clean, invoke
/why-review in FULL mode (NOT --validate-findings) ONCE over the WHOLE review target combined with the current changes as a single artifact — a real standalone /why-review call, the same as a user running /why-review against the target directly. The per-file/per-dimension reviewers and the Phase 6 validate-findings gate routinely miss holistic design-rationale and whole-package issues that a standalone full-mode review catches. If it surfaces findings, fix them and re-run Phase 7.5 (run→fix→run) until a full-mode pass clears that round's exit bar — zero findings in rounds 1-2, zero CRITICAL/HIGH/MEDIUM from round 3 (a LOW-only round ENDS the loop; list those LOWs as deferred, never fix-and-loop for them). When inside $workflow-review-changes, SKIP this — the parent workflow's dedicated standalone /why-review step (step 13) owns the holistic pass.
- Phase 8: Mandatory Final Docs-Update Gate (MANDATORY — runs once the review/fix loop converges clean) — After the review reaches zero findings and all fixes are applied, ALWAYS invoke
/docs-update over the full changeset as the terminal step so no stale docs survive. This is unconditional (not gated on a flagged finding) — /docs-update independently detects impacted docs the review may not have surfaced. When inside $workflow-review-changes, the parent workflow's /docs-update step owns this; do not run it locally.
Key Rules:
- Report-driven: ALWAYS write findings to
plans/reports/code-review-{date}-{slug}.md
- MUST ATTENTION create todo tasks for ALL phases before starting
- Skeptical: every claim needs
file:line proof
- Verify convention by grepping 3+ existing examples before flagging violations
- Actively check DRY violations, YAGNI/KISS over-engineering, correctness bugs
- When changed files include source code, run the Easy-to-Change gate: estimate future edit sites, coupling, hidden state, duplicated knowledge, unclear intent, and abstraction boundary health
- When changed files include source code, run the Phase 3.5
/code-simplifier optimization gate over the changed code files — its simplification opportunities are findings that flow through the same Phase 6 validation → Phase 7 fix loop (never auto-applied unvalidated)
- When changed files include behavior-bearing code, run the Phase 3.7
/integration-test-review coverage gate over the full diff — every behavior change must map to a covering test (integration-first) and a spec TC; GAP/SPEC-GAP verdicts are findings for the same Phase 6 → Phase 7 loop, never silently logged
- Cross-reference changed files against related docs — flag stale docs, test specs, READMEs
- MANDATORY FINAL step: once the review/fix loop converges to zero findings, ALWAYS run the Phase 8
/docs-update sweep over the full changeset — unconditional, never skipped on a clean verdict — why: a clean code review still leaves docs stale unless docs-update reconciles them against the actual changes
- Findings are not eligible for auto-fix until Phase 6 why-review validation returns CLEAN for the current finding set
- FIRST ACTION (standalone): bind the Phase -1 self-recursive review loop — the protocol loop is the primary, host-independent binding you self-drive, plus an optional
/goal Stop-hook gate WHEN available — so stopping is blocked until a complete review pass over the whole diff is clean; soft "loop until clean" prose alone is not enough, and the protocol binding makes abandoning the loop early impossible whether or not /goal exists
- After Phase 6 validation, the skill MUST SELF-FIX every validated finding in Phase 7 (standalone) — a surfaced+validated finding that is reported but left unfixed keeps the review loop open (and, when available, the
/goal gate); never hand validated findings back to the user as "recommendations" in standalone mode
- Every fix cycle invalidates the prior review result; restart
/changes-review from Phase 0 and review the full updated diff AS A WHOLE FROM THE BEGINNING — combined with the prior fixes, NOT just re-reviewing the previous cycle's fix in isolation
- Continue review → validate findings → self-fix → full whole-diff re-review until a complete review pass clears that round's exit bar — zero findings in rounds 1-2, zero CRITICAL/HIGH/MEDIUM from round 3 (a LOW-only round ENDS the loop; list those LOWs as deferred, never fix-and-loop for them); do not add a fresh-context pass just because findings exist or a fix cycle restarted the review
- Severity floor — from round 3, LOW stops blocking. Rounds 1-2 of the Phase 7 loop require zero findings at any severity. From round 3 the bar is zero validated CRITICAL/HIGH/MEDIUM — a round whose validated findings are ALL LOW ENDS the loop. Do NOT restart Phase 0 for LOW findings alone: record them under
## Deferred LOW Findings (severity floor, round ≥3) in the report and advance to Phase 7.5. NEVER re-tier a real CRITICAL/HIGH/MEDIUM down to LOW to reach the exit, and NEVER apply the floor to a binary gate (a missing §8 TC for a behavior change is HIGH, not a deferrable LOW). Severity tiers per SYNC:severity-rubric.
MANDATORY Plan ToDo Task to discover and READ project-specific reference docs:
- Search for code standards docs:
*code-review*, *patterns*, *conventions*, *style-guide* — read any found
- Search for architecture docs:
*architecture*, *adr-*, README.md at service/module roots
- Look for docs referencing changed technology areas (backend, frontend, infra, etc.)
- Read docs most relevant to the categories of files changed
Prerequisites: MUST ATTENTION READ before executing:
Critical Purpose: Ensure quality — no flaws, no bugs, no missing updates, no stale content. Verify both artifacts AND documentation.
External Memory: For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in plans/reports/ — prevents context loss and serves as deliverable.
Evidence Gate: MANDATORY — every claim, finding, and recommendation requires file:line proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).
OOP & DRY Enforcement: MANDATORY — flag duplicated patterns that should be extracted to a base class, generic, or helper. Classes in the same group or suffix MUST ATTENTION inherit a common base (even if empty now — enables future shared logic and child overrides). Verify project has code linting/analyzer configured for the stack.
Code Review: Current Or Branch Diff
Review current changes or explicit branch/commit diffs against project standards.
Review Scope
Target: current working-tree changes by default; explicit branch/tag/commit diff when user asks branch comparison.
Use these sources:
- Current changes:
git status, git diff, and git diff --cached
- Branch diff:
git diff <base>...<head> plus git diff --name-only <base>...<head>
- Commit range:
git diff <base>..<head> plus git diff --name-only <base>..<head>
Review Mindset (NON-NEGOTIABLE)
Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80%.
- Verify correctness by reading actual implementations, never accept it at face value
- Every finding MUST include
file:line evidence (grep results, read confirmations)
- Include a claim only when a trace proves it; otherwise leave it out of the report
- Question assumptions: "Does this actually work?" → trace call path to confirm
- Challenge completeness: "Is this all?" → grep related usages
- Verify side effects: "What else does this change break?" → check consumers and dependents
- No "looks fine" without proof — state what was verified and how
First Principle — Easy to Change
Apply this gate when diff includes source-code or code-adjacent files
(.cs, .ts, .html, .scss, .css, tests, scripts, build/config-as-code).
Pure docs-only changes skip this gate except for executable examples or code
snippets.
Success metric: future change cost.
DRY, SRP, abstraction, design patterns, naming, layering, tests — all serve one goal: make next change cheaper.
When evaluating code, refactor, test, or abstraction, ask: does this make next change cheaper or more expensive?
- Reject "best practices" raising change cost: premature abstraction, speculative generality, leaky indirection, ceremony without payoff.
- Name real enemies in findings: coupling, hidden state, duplicated knowledge, unclear intent, irreversible decisions exposed too early.
- Favor project-owned boundaries around external libraries, e.g. component/service input-output contracts, when they localize future library changes; reject pass-through wrappers adding ceremony without lowering change cost.
- Simpler design easy to change beats sophisticated design that isn't.
Apply this lens before specific rules, patterns, or checklists below. If downstream rule raises change cost, this principle wins.
Core Principles (ENFORCE ALL)
YAGNI — Flag code solving hypothetical future problems (unused parameters, speculative interfaces, premature abstractions)
KISS — Flag unnecessarily complex solutions. "Is there a simpler way meeting same requirement?"
DRY — Actively grep for similar/duplicate code before accepting new code. 3+ similar patterns → flag for extraction.
Clean Code — Readable > clever. Names reveal intent. Functions do one thing. No deep nesting.
Follow Convention — Before flagging ANY pattern violation, grep for 3+ existing examples. Codebase convention wins over textbook rules.
No Flaws/No Bugs — Trace logic paths. Verify edge cases (null, empty, boundary values). Check error handling covers failure modes.
Proof Required — Every claim backed by file:line evidence or grep results. Speculation FORBIDDEN.
Doc Staleness — Cross-reference changed files against related docs (feature docs, test specs, READMEs). Flag stale or missing updates.
Run python .claude/scripts/code_graph batch-query <f1> <f2> --json on changed files for test coverage and caller impact.
Blast Radius Pre-Analysis (MANDATORY FIRST REVIEW STEP)
IMPORTANT MANDATORY MUST ATTENTION: FIRST review action in every review — only the Phase -1 self-recursive review-loop binding (standalone) precedes it. Call /graph-blast-radius BEFORE any other review work.
If .code-graph/graph.db exists, run graph-blast-radius analysis before reviewing changes:
- Call
/graph-blast-radius skill (runs python .claude/scripts/code_graph blast-radius --json)
- Include in review: impacted files count, untested changes, risk level based on blast radius size
- Use results to prioritize file review order (highest-impact files first)
Graph-Assisted Change Review
For each changed file, trace full impact:
python .claude/scripts/code_graph trace <changed-file> --direction downstream --json — all files affected by changes
- Flag any affected file NOT covered by tests
- Catches cross-service impact simple diff review misses
Review Approach (Report-Driven Multi-Phase — CRITICAL)
MANDATORY FIRST: Create Todo Tasks for Review Phases
Before starting, call TaskCreate with:
Update todo status as each phase completes.
Note: If Phase 1 reveals 10+ changed files, replace Phase 2-4 tasks with Systematic Review Protocol tasks:
[Review Phase 2] Categorize and fire parallel sub-agents, [Review Phase 3] Synchronize and cross-reference, [Review Phase 3.5] Run /code-simplifier on changed code files, [Review Phase 3.7] Run /integration-test-review coverage gate, [Review Phase 4] Generate consolidated report
Phase -1: Bind the Self-Recursive Review Loop (FIRST ACTION — standalone-only; protocol-first, /goal optional)
IMPORTANT MANDATORY MUST ATTENTION: This is the VERY FIRST action in standalone mode — before Phase 0, before any git/graph command. Its purpose is to make the review→fix→re-review loop UNABANDONABLE. The loop is bound by TWO layers: the protocol loop (primary, host-independent) you self-drive, plus an optional /goal accelerator (a session Stop hook) WHEN available. Correctness rides on the protocol loop — hooks/commands are accelerators only, so /goal's absence NEVER weakens it.
Entry gate:
- Run in standalone invocation (user called
/changes-review directly).
- SKIP when this skill is invoked as step 1 inside
$workflow-review-changes — the parent workflow owns the loop goal (its own Phase -1 / step-0 goal gate). Record: Phase -1 deferred to parent $workflow-review-changes goal gate.
Procedure:
Set the [Review Phase -1] task to in_progress.
Protocol loop — ALWAYS binding (hook/command-independent). You, the running agent, are personally responsible for not stopping until the loop below converges or bounded-escalates. This binds Claude, Codex, and Copilot equally, whether or not /goal exists:
Review the full diff → run /why-review --validate-findings on every finding → SELF-FIX each validated finding → restart /changes-review from Phase 0 over the WHOLE updated diff (combined with the prior fixes, not just the last fix) → loop until one complete review pass clears that round's bar (rounds 1-2: zero findings; round 3+: zero CRITICAL/HIGH/MEDIUM, a LOW-only round ENDS the loop with the LOWs recorded as deferred) → then run Phase 7.5: one standalone FULL-mode /why-review over the whole target+diff (NOT --validate-findings), fixing and re-running until it is clean → only then run the Phase 8 /docs-update. Do not stop while any validated finding is unfixed, any review pass is non-clean, or the holistic full-mode /why-review has unaddressed findings.
/goal command — invoke as an accelerator WHEN AVAILABLE. If a /goal command exists and you are permitted to run it in this environment, ALSO invoke it (the actual command, NOT a paraphrase) with the SAME condition, so a session Stop hook mechanically enforces the loop:
/goal changes-review self-recursive loop: review the full diff → run /why-review --validate-findings on every finding → SELF-FIX each validated finding → restart /changes-review from Phase 0 over the WHOLE updated diff (combined with the prior fixes, not just the last fix) → loop until one complete review pass clears that round's bar (rounds 1-2: zero findings; round 3+: zero CRITICAL/HIGH/MEDIUM, a LOW-only round ENDS the loop with the LOWs recorded as deferred) → then run Phase 7.5: one standalone FULL-mode /why-review over the whole target+diff (NOT --validate-findings), fixing and re-running until it is clean → only then run the Phase 8 /docs-update. Do not stop while any validated finding is unfixed, any review pass is non-clean, or the holistic full-mode /why-review has unaddressed findings.
The /goal Stop hook blocks stopping until that condition holds and auto-clears when it does — do not tell the user to clear it. If /goal is unavailable, unregistered, or not permitted (e.g. Codex/Copilot, or a Claude run without the command): DO NOT error, DO NOT block, and DO NOT invent a stand-in gate. Record /goal accelerator unavailable — review loop bound by protocol (Phase -1 step 2) on the [Review Phase -1] task and proceed; the protocol loop IS the gate, enforced by discipline instead of a hook.
Set the [Review Phase -1] task to completed and proceed to Phase 0.
Why bind the loop, not just prose: the loop rules below ("restart from Phase 0", "continue until zero findings") are soft directives an agent can rationalize away after one cycle. Binding them as a standing protocol obligation (and, WHEN available, a /goal Stop hook) converts them into a mechanical block — the session cannot end with a validated finding still unfixed or a non-clean review pass. — why: a review that reports findings but stops before fixing-and-reproving them ships unreviewed work.
Phase 0: Run Graph Blast Radius Analysis (MANDATORY FIRST REVIEW STEP)
IMPORTANT MANDATORY MUST ATTENTION: FIRST review step, after the Phase -1 goal gate and before ANY other review work.
- Call
/graph-blast-radius skill
- Record in report: changed files count, impacted files count, untested changes, risk level
- Use blast radius output to prioritize which files to review most carefully in Phase 2
- If
.code-graph/graph.db does not exist, note "Graph not available — skipping blast radius" and proceed to Phase 0.1
Phase 0.1: Change Context Comprehension & Full-Pipeline Impact Trace (MANDATORY — comprehension-first)
IMPORTANT MANDATORY MUST ATTENTION: First comprehension step — before any file-by-file or dimensional review. Blast radius (Phase 0) gathers impact data; here holistically UNDERSTAND the change, trace main affected area's full pipeline across every boundary it crosses. Apply BOTH the Cross-Stack Impact Trace and Cross-Service Check protocols (bodies in the SYNC section below). This holistic first-pass map FEEDS the later Phase 0.3 change-type risk tasks and the conditional Phase 3 synthesis — does not replace them.
Write a one-paragraph Change Context note (what changed · intent · originating tier · main affected feature/flow), then run both traces per the Cross-Stack Impact Trace and Cross-Service Check protocols (SYNC blocks below).
Parent workflow boundary: Inside $workflow-review-changes, still RUN Phase 0.1 (comprehension is local review value) but hand findings to the parent — same pattern as Phase 3.5/3.7.
Phase 0.3: Change Type Detection + Risk Tasks (MANDATORY)
Purpose: Identify HIGH-RISK change types in this diff before dimensional review.
Each detected type creates a focused risk task. Change types are ORTHOGONAL to file category:
the same file can be both a migration AND a security change — detect all independently.
Step 1: Detect change types
git diff --name-only HEAD # unstaged
git diff --cached --name-only # staged
# For branch or commit-range review, use the user-provided diff source:
git diff --name-only <base>...<head>
Evaluate each change type for this diff:
| Change Type |
Detection Signal (adapt to project's actual conventions) |
TRUE if... |
| DepUpgrade |
Dependency manifest changed (package.json, *.csproj, Gemfile, go.mod, requirements.txt, Cargo.toml, pom.xml, etc.) |
A version number changed in any dependency manifest |
| Migration |
File path or name suggests schema change (contains migration, schema, alter_table, or matches project's migration convention) |
Any migration-convention file appears in the diff |
| BusEvent |
New or modified event/message definition or consumer (infer from project conventions: consumer naming, message type directories) |
A consumer or event class is new or its contract changed |
| ApiContract |
API definition file changed (controller, route handler, OpenAPI/GraphQL schema) with route or field differences |
Diff shows route/action/field additions or removals |
| SecurityChange |
Auth/permission definition changed — infer from project conventions (auth middleware, permission constants, policy definitions) |
Any auth or permission gate is added, removed, or changed |
| ConfigChange |
Configuration files changed (e.g., *.json, *.yaml, *.env*, *Config*, *Options*, *Settings*, *.toml) |
Any config-convention file appears |
| InfraChange |
Infrastructure definition changed (Dockerfile, docker-compose*.yml, CI/CD pipelines, k8s manifests, IaC files) |
Any infra-convention file appears |
Record in report:
## Change Type Analysis
DepUpgrade: [YES/NO] | Migration: [YES/NO] | BusEvent: [YES/NO]
ApiContract: [YES/NO] | SecurityChange: [YES/NO] | ConfigChange: [YES/NO] | InfraChange: [YES/NO]
Step 2: Create change-type risk tasks (ALWAYS before any review work)
MANDATORY: Call TaskCreate for each TRUE signal. Do NOT create tasks for FALSE signals.
The concerns listed are starting points — apply domain knowledge beyond them.
| Condition |
TaskCreate subject |
Key concerns to investigate (starting points — expand with domain knowledge) |
| DepUpgrade TRUE |
[Review-DepUpgrade] Dependency upgrade — semver, breaking changes, security advisories |
Major/minor/patch? Read upstream CHANGELOG for breaking API changes. Grep deprecated API usage. Check transitive dependency changes. Known security advisories for new version? Peer dependency compatibility? Tests still passing? |
| Migration TRUE |
[Review-Migration] DB migration — rollback path, volume impact, zero-downtime |
Rollback/Down script exists? Table size estimate — large tables need lock analysis. NOT NULL column without default on non-empty table? Indexes created with no-lock option? Deployment ordering (before/after service deploy)? Backfill idempotent if run twice? |
| BusEvent TRUE |
[Review-BusEvent] Cross-service event/message — consumer, idempotency, retry, poison pill |
Consumer exists for new event? Retry strategy: prerequisite data not synced → wait-retry vs silent skip? Handler safe to run twice (idempotency)? Malformed message handling / dead-letter configured? Ordering assumptions vs broker guarantees? |
| ApiContract TRUE |
[Review-ApiContract] API contract change — backward compat, client alignment, auth |
Additive or breaking? Breaking → versioning or coordinated deploy required. All callers (UI, other services, tests) still compatible? New endpoint protected appropriately? No required response fields added without client update? |
| SecurityChange TRUE |
[Review-SecurityChange] Security/permission change — all paths covered, no privilege escalation |
All code paths reaching the gate covered? Negative test verifying unauthorized access DENIED? Privilege escalation possible? BOTH enforcement AND display control updated? Permission definition in single authoritative place (no duplicated strings risking drift)? |
| ConfigChange TRUE |
[Review-ConfigChange] Config/env change — all environments, no secrets committed |
New config key present in ALL environment configs? Hardcoded default masking missing production config? Any secret value in the diff? → CRITICAL if yes. Documented in setup guide? App fails fast if config missing? |
| InfraChange TRUE |
[Review-InfraChange] Infrastructure change — env parity, no dev values in prod, reproducible build |
Change affects all environments consistently? Hardcoded dev values (localhost, debug flags, dev credentials)? Pinned image/dependency versions? Local dev impact documented? CI/CD secret/permission requirements documented? |
AI-SDD risk lenses: Apply these lenses when the changed files touch specs, workflows, tooling, or shared guidance.
| Lens |
Review focus |
| Contract/API/routes |
Public behavior, clients, generated specs, and regression tests still agree. |
| Permissions/security-review |
Enforcement, display controls, negative tests, and authoritative permission definitions align. |
| Config/flags |
All environments, examples, fail-fast behavior, and docs are current. |
| Docs/spec/test drift |
Canonical specs, Section 8 TCs, dashboards, and test code are synchronized or explicitly N/A. |
| Generated mirrors |
Shared skill/workflow/tooling changes were synced to generated agent surfaces. |
| Reference-only artifacts |
AI-extracted specs/TCs remain draft/reference until accepted by the owning review gate. |
Step 3: Work through change-type tasks before dimensional review
For each created change-type task:
- Set task to
in_progress
- Work through ALL applicable concerns — the table above is a starting point, not a ceiling
- For each concern: cite
file:line for PASS or describe finding for FAIL/WARN
- Write findings under
## {Task Subject} Findings in report
- Set task to
completed
IMPORTANT: Complete ALL change-type tasks FIRST, then proceed to Phase 0.7.
If no change-type signals detected, log "No high-risk change types detected" and proceed.
Phase 0.7: Change Surface Detection + Dynamic Review Tasks (MANDATORY)
Purpose: Let AI categorize the changes by nature and create review tasks accordingly.
Derive categories from what the project's actual changed files are, never assume a fixed set.
Think, don't classify into a preset grid. The AI owns this step entirely.
Step 1: Derive categories from the diff
git diff --name-only HEAD # unstaged
git diff --cached --name-only # staged
# For branch or commit-range review, use the user-provided diff source:
git diff --name-only <base>
…(truncated)
1---2name: changes-review-23description: "[Code Quality] Use when reviewing current changes, staged or unstaged diffs, or branch-to-branch diffs."4---56<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->78> **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval.9> **[BLOCKING]** Before each step or sub-skill call, update task tracking: set `in_progress` when step starts, set `completed` when step ends.10> **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason.11> **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.1213<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->1415> **[TOP REMINDER — WHY-REVIEW FINDINGS-VALIDATION GATE IS NON-NEGOTIABLE]**16>17> If this review produces **ANY** finding (Critical / High / Medium / Low) in standalone mode, you **MUST invoke the `/why-review` skill** through the `Skill` tool with `--validate-findings <report-path>` **before** any fix, docs-update, commit, or handoff. An actual skill call is the ONLY way to pass this gate — re-reading the cited `file:line`s yourself, "self-validating," or any inline/manual substitute does **NOT** count.18>19> **Create the todo the moment the first finding is recorded — never rely on memory:** call `TaskCreate` → `[Review Phase 6] Why-review findings validation gate — invoke /why-review` so the gate is tracked and cannot be skipped. Inside `$workflow-review-changes`, stop after the report; parent step 2 owns validation. Full protocol in **Phase 6**; mirrored in the **Closing Reminders** at the bottom.2021## Quick Summary2223**Goal:** Review current working-tree, staged, branch, or commit diffs across code, docs, config, infra, and non-code artifacts — finding correctness bugs, flaws, missing updates, stale docs, and convention drift with evidence — so every reviewed change is defect-free, evidence-backed, convention-aligned, and synchronized with required tests/docs before handoff; when code files changed, also prove the code stays easy to change.2425**Summary:** read-this-if-nothing-else digest —2627- **Report-driven and evidence-gated.** Every finding is written to `plans/reports/code-review-{date}-{slug}.md` with `file:line` proof; speculation is forbidden, "looks fine" is not a verdict, codebase convention (grep 3+ examples) wins over textbook rules.28- **Self-recursive loop is protocol-bound (goal-gated when available).** Standalone mode's FIRST action (Phase -1) binds the review loop as a standing protocol obligation you self-drive — and installs a `/goal` Stop-hook condition WHEN available — so stopping is BLOCKED until the loop converges. Findings are never auto-fixed on sight: validate (Phase 6 `/why-review --validate-findings`, an actual skill call) → SELF-FIX (Phase 7) → restart `/changes-review` from Phase 0 over the WHOLE updated diff (combined with prior fixes, not just the last fix), looping until one whole pass clears that round's exit bar — **zero findings in rounds 1-2, zero CRITICAL/HIGH/MEDIUM from round 3 (a LOW-only round ENDS the loop; list those LOWs as deferred, never fix-and-loop for them)**. Inside `$workflow-review-changes` you skip Phase -1, stop after the report, and hand findings to the parent (which owns the goal).29- **When code changed, three delegated gates are MANDATORY:** Phase 3.5 `/code-simplifier` (clarity/maintainability), Phase 3.7 `/integration-test-review` Gate-7 coverage (every behavior change → covering test + spec TC), and — for every behavior change — Spec Drift Adjudication + the Dual-Feedback Ledger (the gap feeds BOTH spec AND tests).30- **Docs-update is the unconditional terminal step.** Once the loop converges clean, Phase 8 `/docs-update` ALWAYS runs over the full changeset (deferred only to the parent inside the workflow).31- **MUST ATTENTION — run ALL main phases in order (the steps AI keeps forgetting):** Phase -1 bind self-recursive review loop — protocol-primary, optional `/goal` gate when available (standalone, FIRST action) → 0 `/graph-blast-radius` → 0.1 change-context + full-pipeline trace (tier FE↔BE + cross-service/event) → 0.3 change-type risk tasks → 0.7 surface-detection dimension tasks → 0.8 parallel full-mode `/why-review` rationale sub-agent, spawned in the SAME batch as the 0.7 agents → 0.5 plan compliance → 1 collect diff + create report → 2 file-by-file review → 3 fresh-context gate (SKIP when findings exist) → 3.5 `/code-simplifier` (code diffs) → 3.7 `/integration-test-review` Gate-7 coverage (behavior diffs) → 4 finalize + Dual-Feedback Ledger → 5 docs triage → 6 `/why-review --validate-findings` → 7 self-fix + full restart from Phase 0 → 7.5 holistic full-mode `/why-review` → 8 `/docs-update` (unconditional terminal) — why: a skipped phase silently drops a guard (coverage, spec-drift, holistic review, or docs sync) and ships unreviewed work.3233> **Routing boundary:** This skill reviews a **git diff** — working-tree (default), staged, branch, or commit. For an explicit file-set or SHA-range review, processing received review feedback, or a pre-completion verification gate over already-known scope, use `code-review` instead.3435> **Shared engine (keep in sync):** `changes-review` and `code-review` share the same review-protocol `SYNC:` blocks. Canonical source: `.claude/skills/shared/sync-inline-versions.md`; policy: `SYNC:shared-protocol-duplication-policy`. When you change a shared block in one skill, update the canonical file AND the sibling skill so the two never drift. The skills differ only in entry intent (diff vs explicit scope) and diff-specific gates (integration-test-sync, translation-sync, the Phase 3.7 integration-test-review coverage gate) — not in review quality.3637**Workflow:**38390. **Phase -1: Bind the Self-Recursive Review Loop (FIRST ACTION — standalone-only; protocol-first, `/goal` optional)** — Before any other work, in standalone mode bind the review loop as a standing protocol obligation you self-drive — and, WHEN available, invoke the `/goal` command as an ACTUAL call — with a self-recursive review-loop condition so stopping is BLOCKED until the loop converges: _review the full diff → validate findings (Phase 6) → SELF-FIX validated findings (Phase 7) → restart `/changes-review` from Phase 0 over the WHOLE updated diff (combined with the prior fixes, never just re-checking the last fix) → loop until one complete pass clears that round's exit bar — **zero findings in rounds 1-2, zero CRITICAL/HIGH/MEDIUM from round 3 (a LOW-only round ENDS the loop; list those LOWs as deferred, never fix-and-loop for them)**, then docs-update_. Skip this gate when running as step 1 inside `$workflow-review-changes` (the parent owns the goal). Full procedure in **Phase -1**.401. **Phase 0: Blast Radius** — Call `/graph-blast-radius` skill FIRST (if `.code-graph/graph.db` exists)412. **Phase 0.1: Change Context & Full-Pipeline Impact Trace (MANDATORY comprehension-first)** — Note the change context, then holistically trace the main affected area's full pipeline across BOTH boundaries — client↔server tier (FE↔BE) AND service/event/external — classifying each seam/touchpoint NONE/ADDITIVE/BREAKING (explicit N/A for single-tier or monolith)423. **Phase 0.3: Change Types** — Detect high-risk change types; create risk tasks434. **Phase 0.5: Plan Compliance** — Verify against active plan (conditional)445. **Phase 0.7: Surface Detection** — AI categorizes changed files; creates dimension tasks456. **Phase 0.8: Parallel Rationale Review** — Spawn a full-mode `/why-review` sub-agent in the SAME parallel batch as the 0.7 dimensional agents; its findings merge into the Phase 4 final evaluation (standalone-only)467. **Phase 1: Collect** — Run git status/diff, create report file478. **Phase 2: File Review** — Review each changed file, update report incrementally489. **Phase 3: Fresh-Context Gate** — Skip when findings already exist; run a second-round sub-agent only for an explicit user/workflow/high-risk synthesis trigger4910. **Phase 3.5: Code-Simplifier Optimization (MANDATORY when code files changed)** — Invoke `/code-simplifier` scoped to the changed code files to surface clarity/consistency/maintainability simplifications; record them as findings that flow into the same validation/fix loop (skip docs-only diffs)5011. **Phase 3.7: Integration-Test-Review Coverage Gate (MANDATORY when behavior-bearing code changed)** — Invoke `/integration-test-review` over the full diff; its 8 quality gates audit changed tests AND its Gate 7 (Change Coverage) maps every behavior-changing production file to a covering test (integration-first; unit fallback needs justification) and a spec TC. GAP/SPEC-GAP results become findings for the same validation/fix loop (skip docs-only diffs; deferred to the parent's dedicated step inside `$workflow-review-changes`)5112. **Phase 3.8: Domain Entity Gate (MANDATORY when the diff touches an entity/VO/aggregate)** — Apply `SYNC:domain-entity-change-gate` over the changed domain types; Mode A reviews inline, Mode B delegates to `/domain-entities-review` (its A–P checklist owns the gate). Findings flow into the same validation/fix loop (skip when no domain-entity surface)5213. **Phase 4: Finalize** — Generate critical issues, recommendations, suggested commit message5314. **Phase 5: Docs Triage** — Record stale-doc findings for validation/fix loop5415. **Phase 6: Why-Review Findings Validation (standalone-only; REQUIRED before any standalone fix)** — Whenever the report contains one or more findings, you MUST invoke the `/why-review` skill (an actual `Skill`-tool call) with `--validate-findings` to verify every finding is correct, proof-backed, reasonable, and best-practice before fixing. This is a genuine skill invocation — re-reading the cited lines yourself, "self-validating," or any inline/manual substitute does NOT satisfy this gate. When this skill is step 1 inside `$workflow-review-changes`, stop after the report; parent step 2 owns findings validation.5516. **Phase 7: Recursive Fix + Full Re-Review Loop (standalone-only)** — If validated findings remain in standalone mode, auto-fix them, then re-invoke `/changes-review` from Phase 0 with a fresh task breakdown over the full current diff; repeat until an entire review pass clears that round's exit bar — **zero findings in rounds 1-2, zero CRITICAL/HIGH/MEDIUM from round 3 (a LOW-only round ENDS the loop; list those LOWs as deferred, never fix-and-loop for them)**. When inside `$workflow-review-changes`, parent steps 10-15 own plan/feature-implement/restart.5617. **Phase 7.5: Holistic Standalone Full-Mode Why-Review Gate (standalone-only)** — Once the dimensional review/fix loop converges clean, invoke `/why-review` in **FULL mode** (NOT `--validate-findings`) ONCE over the WHOLE review target combined with the current changes as a single artifact — a real standalone `/why-review` call, the same as a user running `/why-review` against the target directly. The per-file/per-dimension reviewers and the Phase 6 validate-findings gate routinely miss holistic design-rationale and whole-package issues that a standalone full-mode review catches. If it surfaces findings, fix them and re-run Phase 7.5 (run→fix→run) until a full-mode pass clears that round's exit bar — **zero findings in rounds 1-2, zero CRITICAL/HIGH/MEDIUM from round 3 (a LOW-only round ENDS the loop; list those LOWs as deferred, never fix-and-loop for them)**. When inside `$workflow-review-changes`, SKIP this — the parent workflow's dedicated standalone `/why-review` step (step 13) owns the holistic pass.5718. **Phase 8: Mandatory Final Docs-Update Gate (MANDATORY — runs once the review/fix loop converges clean)** — After the review reaches zero findings and all fixes are applied, ALWAYS invoke `/docs-update` over the full changeset as the terminal step so no stale docs survive. This is unconditional (not gated on a flagged finding) — `/docs-update` independently detects impacted docs the review may not have surfaced. When inside `$workflow-review-changes`, the parent workflow's `/docs-update` step owns this; do not run it locally.5859**Key Rules:**6061- Report-driven: ALWAYS write findings to `plans/reports/code-review-{date}-{slug}.md`62- MUST ATTENTION create todo tasks for ALL phases before starting63- Skeptical: every claim needs `file:line` proof64- Verify convention by grepping 3+ existing examples before flagging violations65- Actively check DRY violations, YAGNI/KISS over-engineering, correctness bugs66- When changed files include source code, run the Easy-to-Change gate: estimate future edit sites, coupling, hidden state, duplicated knowledge, unclear intent, and abstraction boundary health67- When changed files include source code, run the Phase 3.5 `/code-simplifier` optimization gate over the changed code files — its simplification opportunities are findings that flow through the same Phase 6 validation → Phase 7 fix loop (never auto-applied unvalidated)68- When changed files include behavior-bearing code, run the Phase 3.7 `/integration-test-review` coverage gate over the full diff — every behavior change must map to a covering test (integration-first) and a spec TC; GAP/SPEC-GAP verdicts are findings for the same Phase 6 → Phase 7 loop, never silently logged69- Cross-reference changed files against related docs — flag stale docs, test specs, READMEs70- MANDATORY FINAL step: once the review/fix loop converges to zero findings, ALWAYS run the Phase 8 `/docs-update` sweep over the full changeset — unconditional, never skipped on a clean verdict — why: a clean code review still leaves docs stale unless docs-update reconciles them against the actual changes71- Findings are not eligible for auto-fix until Phase 6 why-review validation returns CLEAN for the current finding set72- FIRST ACTION (standalone): bind the Phase -1 self-recursive review loop — the **protocol loop is the primary, host-independent binding** you self-drive, plus an optional `/goal` Stop-hook gate WHEN available — so stopping is blocked until a complete review pass over the whole diff is clean; soft "loop until clean" prose alone is not enough, and the protocol binding makes abandoning the loop early impossible whether or not `/goal` exists73- After Phase 6 validation, the skill MUST SELF-FIX every validated finding in Phase 7 (standalone) — a surfaced+validated finding that is reported but left unfixed keeps the review loop open (and, when available, the `/goal` gate); never hand validated findings back to the user as "recommendations" in standalone mode74- Every fix cycle invalidates the prior review result; restart `/changes-review` from Phase 0 and review the full updated diff AS A WHOLE FROM THE BEGINNING — combined with the prior fixes, NOT just re-reviewing the previous cycle's fix in isolation75- Continue review → validate findings → self-fix → full whole-diff re-review until a complete review pass clears that round's exit bar — **zero findings in rounds 1-2, zero CRITICAL/HIGH/MEDIUM from round 3 (a LOW-only round ENDS the loop; list those LOWs as deferred, never fix-and-loop for them)**; do not add a fresh-context pass just because findings exist or a fix cycle restarted the review76- **Severity floor — from round 3, LOW stops blocking.** Rounds 1-2 of the Phase 7 loop require zero findings at any severity. **From round 3 the bar is zero validated CRITICAL/HIGH/MEDIUM — a round whose validated findings are ALL LOW ENDS the loop.** Do NOT restart Phase 0 for LOW findings alone: record them under `## Deferred LOW Findings (severity floor, round ≥3)` in the report and advance to Phase 7.5. NEVER re-tier a real CRITICAL/HIGH/MEDIUM down to LOW to reach the exit, and NEVER apply the floor to a binary gate (a missing §8 TC for a behavior change is HIGH, not a deferrable LOW). Severity tiers per `SYNC:severity-rubric`.7778> **MANDATORY** Plan ToDo Task to discover and READ project-specific reference docs:79>80> 1. Search for code standards docs: `*code-review*`, `*patterns*`, `*conventions*`, `*style-guide*` — read any found81> 2. Search for architecture docs: `*architecture*`, `*adr-*`, `README.md` at service/module roots82> 3. Look for docs referencing changed technology areas (backend, frontend, infra, etc.)83> 4. Read docs most relevant to the categories of files changed8485**Prerequisites:** **MUST ATTENTION READ** before executing:8687> **Critical Purpose:** Ensure quality — no flaws, no bugs, no missing updates, no stale content. Verify both artifacts AND documentation.8889> **External Memory:** For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in `plans/reports/` — prevents context loss and serves as deliverable.9091> **Evidence Gate:** MANDATORY — every claim, finding, and recommendation requires `file:line` proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).9293> **OOP & DRY Enforcement:** MANDATORY — flag duplicated patterns that should be extracted to a base class, generic, or helper. Classes in the same group or suffix MUST ATTENTION inherit a common base (even if empty now — enables future shared logic and child overrides). Verify project has code linting/analyzer configured for the stack.9495# Code Review: Current Or Branch Diff9697Review current changes or explicit branch/commit diffs against project standards.9899## Review Scope100101Target: current working-tree changes by default; explicit branch/tag/commit diff when user asks branch comparison.102103Use these sources:104105- Current changes: `git status`, `git diff`, and `git diff --cached`106- Branch diff: `git diff <base>...<head>` plus `git diff --name-only <base>...<head>`107- Commit range: `git diff <base>..<head>` plus `git diff --name-only <base>..<head>`108109## Review Mindset (NON-NEGOTIABLE)110111**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80%.**112113- Verify correctness by reading actual implementations, never accept it at face value114- Every finding MUST include `file:line` evidence (grep results, read confirmations)115- Include a claim only when a trace proves it; otherwise leave it out of the report116- Question assumptions: "Does this actually work?" → trace call path to confirm117- Challenge completeness: "Is this all?" → grep related usages118- Verify side effects: "What else does this change break?" → check consumers and dependents119- No "looks fine" without proof — state what was verified and how120121## First Principle — Easy to Change122123Apply this gate when diff includes source-code or code-adjacent files124(`.cs`, `.ts`, `.html`, `.scss`, `.css`, tests, scripts, build/config-as-code).125Pure docs-only changes skip this gate except for executable examples or code126snippets.127128> **Success metric: _future change cost_.**129> DRY, SRP, abstraction, design patterns, naming, layering, tests — all serve one goal: **make next change cheaper**.130131When evaluating code, refactor, test, or abstraction, ask: **does this make next change cheaper or more expensive?**132133- Reject "best practices" raising change cost: premature abstraction, speculative generality, leaky indirection, ceremony without payoff.134- Name real enemies in findings: **coupling, hidden state, duplicated knowledge, unclear intent, irreversible decisions exposed too early**.135- Favor project-owned boundaries around external libraries, e.g. component/service input-output contracts, when they localize future library changes; reject pass-through wrappers adding ceremony without lowering change cost.136- Simpler design easy to change beats sophisticated design that isn't.137138Apply this lens **before** specific rules, patterns, or checklists below. If downstream rule raises change cost, this principle wins.139140---141142## Core Principles (ENFORCE ALL)143144**YAGNI** — Flag code solving hypothetical future problems (unused parameters, speculative interfaces, premature abstractions)145**KISS** — Flag unnecessarily complex solutions. "Is there a simpler way meeting same requirement?"146**DRY** — Actively grep for similar/duplicate code before accepting new code. 3+ similar patterns → flag for extraction.147**Clean Code** — Readable > clever. Names reveal intent. Functions do one thing. No deep nesting.148**Follow Convention** — Before flagging ANY pattern violation, grep for 3+ existing examples. Codebase convention wins over textbook rules.149**No Flaws/No Bugs** — Trace logic paths. Verify edge cases (null, empty, boundary values). Check error handling covers failure modes.150**Proof Required** — Every claim backed by `file:line` evidence or grep results. Speculation FORBIDDEN.151**Doc Staleness** — Cross-reference changed files against related docs (feature docs, test specs, READMEs). Flag stale or missing updates.152153> Run `python .claude/scripts/code_graph batch-query <f1> <f2> --json` on changed files for test coverage and caller impact.154155## Blast Radius Pre-Analysis (MANDATORY FIRST REVIEW STEP)156157> **IMPORTANT MANDATORY MUST ATTENTION:** FIRST _review_ action in every review — only the Phase -1 self-recursive review-loop binding (standalone) precedes it. Call `/graph-blast-radius` BEFORE any other review work.158159If `.code-graph/graph.db` exists, run graph-blast-radius analysis before reviewing changes:160161- Call `/graph-blast-radius` skill (runs `python .claude/scripts/code_graph blast-radius --json`)162- Include in review: impacted files count, untested changes, risk level based on blast radius size163- Use results to prioritize file review order (highest-impact files first)164165### Graph-Assisted Change Review166167For each changed file, trace full impact:1681691. `python .claude/scripts/code_graph trace <changed-file> --direction downstream --json` — all files affected by changes1702. Flag any affected file NOT covered by tests1713. Catches cross-service impact simple diff review misses172173## Review Approach (Report-Driven Multi-Phase — CRITICAL)174175**MANDATORY FIRST: Create Todo Tasks for Review Phases**176Before starting, call TaskCreate with:177178- [ ] `[Review Phase -1] Bind self-recursive review loop — protocol-primary; optional /goal gate when available (standalone-only; skip inside $workflow-review-changes)` - in_progress **(MUST ATTENTION BE FIRST)**179- [ ] `[Review Phase 0] Run /graph-blast-radius to analyze change impact` - pending **(FIRST review step after the goal gate)**180- [ ] `[Review Phase 0.1] Note change context + holistic full-pipeline trace across BOTH boundaries — client↔server tier (FE↔BE) AND service/event/external — classify each seam/touchpoint NONE/ADDITIVE/BREAKING` - pending **(MANDATORY comprehension-first; record explicit N/A for single-tier or monolith)**181- [ ] `[Review Phase 0.3] Detect high-risk change types, create risk tasks` - pending182- [ ] `[Review Phase 0.7] Categorize changed files, create dimension review tasks` - pending183- [ ] `[Review Phase 0.8] Spawn parallel /why-review full-mode rationale sub-agent in the SAME batch as the Phase 0.7 dimensional agents; merge its findings into the final evaluation` - pending **(MANDATORY standalone; skip inside `$workflow-review-changes` — parent steps 2-3 own it)**184- [ ] `[Review Phase 0.5] Plan compliance check (skip if no active plan)` - pending185- [ ] `[Review Phase 1] Get changes and create report file` - pending186- [ ] `[Review Phase 2] Review file-by-file and update report` - pending187- [ ] `[Review Phase 3] Evaluate fresh-context gate; skip when findings already exist` - pending188- [ ] `[Review Phase 3.5] Run /code-simplifier on changed code files to optimize code quality` - pending **(MANDATORY when code files changed; skip docs-only diffs)**189- [ ] `[Review Phase 3.7] Run /integration-test-review coverage gate over full diff` - pending **(MANDATORY when behavior-bearing code changed; skip docs-only diffs; deferred to parent step inside `$workflow-review-changes`)**190- [ ] `[Review Phase 3.8] Run the domain entity change gate over changed entities/VOs/aggregates` - pending **(MANDATORY when the diff touches an entity, value object, or aggregate; skip otherwise)**191- [ ] `[Review Phase 4] Generate final review findings` - pending192- [ ] `[Review Phase 5] Record stale-doc findings for validation/fix loop` - pending193- [ ] `[Review Phase 6] Why-review findings validation gate before any fix` - pending **(MANDATORY when findings exist)**194- [ ] `[Review Phase 7] Auto-fix validated findings and restart /changes-review from Phase 0` - pending **(MANDATORY when validated findings remain)**195- [ ] `[Review Phase 7.5] Run standalone full-mode /why-review over the whole target+diff; fix and re-run until zero findings` - pending **(MANDATORY when review loop converges clean; standalone-only — skip inside `$workflow-review-changes`)**196- [ ] `[Review Phase 8] Run /docs-update over full changeset to sync all impacted docs` - pending **(MANDATORY FINAL — always runs once review converges to zero findings; never skipped)**197198Update todo status as each phase completes.199200> **Note:** If Phase 1 reveals 10+ changed files, replace Phase 2-4 tasks with Systematic Review Protocol tasks:201> `[Review Phase 2] Categorize and fire parallel sub-agents`, `[Review Phase 3] Synchronize and cross-reference`, `[Review Phase 3.5] Run /code-simplifier on changed code files`, `[Review Phase 3.7] Run /integration-test-review coverage gate`, `[Review Phase 4] Generate consolidated report`202203**Phase -1: Bind the Self-Recursive Review Loop (FIRST ACTION — standalone-only; protocol-first, `/goal` optional)**204205> **IMPORTANT MANDATORY MUST ATTENTION:** This is the VERY FIRST action in standalone mode — before Phase 0, before any git/graph command. Its purpose is to make the review→fix→re-review loop UNABANDONABLE. The loop is bound by TWO layers: the **protocol loop (primary, host-independent)** you self-drive, plus an **optional `/goal` accelerator** (a session Stop hook) WHEN available. Correctness rides on the protocol loop — hooks/commands are accelerators only, so `/goal`'s absence NEVER weakens it.206207**Entry gate:**208209- **Run** in standalone invocation (user called `/changes-review` directly).210- **SKIP** when this skill is invoked as step 1 inside `$workflow-review-changes` — the parent workflow owns the loop goal (its own Phase -1 / step-0 goal gate). Record: `Phase -1 deferred to parent $workflow-review-changes goal gate.`211212**Procedure:**2132141. Set the `[Review Phase -1]` task to `in_progress`.2152. **Protocol loop — ALWAYS binding (hook/command-independent).** You, the running agent, are personally responsible for not stopping until the loop below converges or bounded-escalates. This binds Claude, Codex, and Copilot equally, whether or not `/goal` exists:216217 > Review the full diff → run `/why-review --validate-findings` on every finding → SELF-FIX each validated finding → restart `/changes-review` from Phase 0 over the WHOLE updated diff (combined with the prior fixes, not just the last fix) → loop until one complete review pass clears that round's bar (rounds 1-2: zero findings; round 3+: zero CRITICAL/HIGH/MEDIUM, a LOW-only round ENDS the loop with the LOWs recorded as deferred) → then run Phase 7.5: one standalone FULL-mode `/why-review` over the whole target+diff (NOT `--validate-findings`), fixing and re-running until it is clean → only then run the Phase 8 `/docs-update`. Do not stop while any validated finding is unfixed, any review pass is non-clean, or the holistic full-mode `/why-review` has unaddressed findings.2182193. **`/goal` command — invoke as an accelerator WHEN AVAILABLE.** If a `/goal` command exists and you are permitted to run it in this environment, ALSO invoke it (the actual command, NOT a paraphrase) with the SAME condition, so a session Stop hook mechanically enforces the loop:220221 ```222 /goal changes-review self-recursive loop: review the full diff → run /why-review --validate-findings on every finding → SELF-FIX each validated finding → restart /changes-review from Phase 0 over the WHOLE updated diff (combined with the prior fixes, not just the last fix) → loop until one complete review pass clears that round's bar (rounds 1-2: zero findings; round 3+: zero CRITICAL/HIGH/MEDIUM, a LOW-only round ENDS the loop with the LOWs recorded as deferred) → then run Phase 7.5: one standalone FULL-mode /why-review over the whole target+diff (NOT --validate-findings), fixing and re-running until it is clean → only then run the Phase 8 /docs-update. Do not stop while any validated finding is unfixed, any review pass is non-clean, or the holistic full-mode /why-review has unaddressed findings.223 ```224225 The `/goal` Stop hook blocks stopping until that condition holds and auto-clears when it does — do not tell the user to clear it. **If `/goal` is unavailable, unregistered, or not permitted** (e.g. Codex/Copilot, or a Claude run without the command): DO NOT error, DO NOT block, and DO NOT invent a stand-in gate. Record `/goal accelerator unavailable — review loop bound by protocol (Phase -1 step 2)` on the `[Review Phase -1]` task and proceed; the protocol loop IS the gate, enforced by discipline instead of a hook.2262274. Set the `[Review Phase -1]` task to `completed` and proceed to Phase 0.228229> **Why bind the loop, not just prose:** the loop rules below ("restart from Phase 0", "continue until zero findings") are soft directives an agent can rationalize away after one cycle. Binding them as a standing protocol obligation (and, WHEN available, a `/goal` Stop hook) converts them into a mechanical block — the session cannot end with a validated finding still unfixed or a non-clean review pass. — why: a review that reports findings but stops before fixing-and-reproving them ships unreviewed work.230231**Phase 0: Run Graph Blast Radius Analysis (MANDATORY FIRST REVIEW STEP)**232233> **IMPORTANT MANDATORY MUST ATTENTION:** FIRST review step, after the Phase -1 goal gate and before ANY other review work.234235- Call `/graph-blast-radius` skill236- Record in report: changed files count, impacted files count, untested changes, risk level237- Use blast radius output to prioritize which files to review most carefully in Phase 2238- If `.code-graph/graph.db` does not exist, note "Graph not available — skipping blast radius" and proceed to Phase 0.1239240**Phase 0.1: Change Context Comprehension & Full-Pipeline Impact Trace (MANDATORY — comprehension-first)**241242> **IMPORTANT MANDATORY MUST ATTENTION:** First _comprehension_ step — before any file-by-file or dimensional review. Blast radius (Phase 0) gathers impact data; here holistically UNDERSTAND the change, trace main affected area's full pipeline across every boundary it crosses. Apply BOTH the **Cross-Stack Impact Trace** and **Cross-Service Check** protocols (bodies in the SYNC section below). This holistic first-pass map FEEDS the later Phase 0.3 change-type risk tasks and the conditional Phase 3 synthesis — does not replace them.243244Write a one-paragraph **Change Context** note (what changed · intent · originating tier · main affected feature/flow), then run both traces per the **Cross-Stack Impact Trace** and **Cross-Service Check** protocols (SYNC blocks below).245246**Parent workflow boundary:** Inside `$workflow-review-changes`, still RUN Phase 0.1 (comprehension is local review value) but hand findings to the parent — same pattern as Phase 3.5/3.7.247248**Phase 0.3: Change Type Detection + Risk Tasks (MANDATORY)**249250> **Purpose:** Identify HIGH-RISK change types in this diff before dimensional review.251> Each detected type creates a focused risk task. Change types are ORTHOGONAL to file category:252> the same file can be both a migration AND a security change — detect all independently.253254**Step 1: Detect change types**255256```bash257git diff --name-only HEAD # unstaged258git diff --cached --name-only # staged259# For branch or commit-range review, use the user-provided diff source:260git diff --name-only <base>...<head>261```262263Evaluate each change type for this diff:264265| Change Type | Detection Signal (adapt to project's actual conventions) | TRUE if... |266| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |267| **DepUpgrade** | Dependency manifest changed (`package.json`, `*.csproj`, `Gemfile`, `go.mod`, `requirements.txt`, `Cargo.toml`, `pom.xml`, etc.) | A version number changed in any dependency manifest |268| **Migration** | File path or name suggests schema change (contains `migration`, `schema`, `alter_table`, or matches project's migration convention) | Any migration-convention file appears in the diff |269| **BusEvent** | New or modified event/message definition or consumer (infer from project conventions: consumer naming, message type directories) | A consumer or event class is new or its contract changed |270| **ApiContract** | API definition file changed (controller, route handler, OpenAPI/GraphQL schema) with route or field differences | Diff shows route/action/field additions or removals |271| **SecurityChange** | Auth/permission definition changed — infer from project conventions (auth middleware, permission constants, policy definitions) | Any auth or permission gate is added, removed, or changed |272| **ConfigChange** | Configuration files changed (e.g., `*.json`, `*.yaml`, `*.env*`, `*Config*`, `*Options*`, `*Settings*`, `*.toml`) | Any config-convention file appears |273| **InfraChange** | Infrastructure definition changed (`Dockerfile`, `docker-compose*.yml`, CI/CD pipelines, k8s manifests, IaC files) | Any infra-convention file appears |274275Record in report:276277```278## Change Type Analysis279DepUpgrade: [YES/NO] | Migration: [YES/NO] | BusEvent: [YES/NO]280ApiContract: [YES/NO] | SecurityChange: [YES/NO] | ConfigChange: [YES/NO] | InfraChange: [YES/NO]281```282283**Step 2: Create change-type risk tasks (ALWAYS before any review work)**284285> **MANDATORY:** Call `TaskCreate` for each TRUE signal. Do NOT create tasks for FALSE signals.286> The concerns listed are starting points — apply domain knowledge beyond them.287288| Condition | TaskCreate subject | Key concerns to investigate (starting points — expand with domain knowledge) |289| ------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |290| DepUpgrade TRUE | `[Review-DepUpgrade] Dependency upgrade — semver, breaking changes, security advisories` | Major/minor/patch? Read upstream CHANGELOG for breaking API changes. Grep deprecated API usage. Check transitive dependency changes. Known security advisories for new version? Peer dependency compatibility? Tests still passing? |291| Migration TRUE | `[Review-Migration] DB migration — rollback path, volume impact, zero-downtime` | Rollback/Down script exists? Table size estimate — large tables need lock analysis. NOT NULL column without default on non-empty table? Indexes created with no-lock option? Deployment ordering (before/after service deploy)? Backfill idempotent if run twice? |292| BusEvent TRUE | `[Review-BusEvent] Cross-service event/message — consumer, idempotency, retry, poison pill` | Consumer exists for new event? Retry strategy: prerequisite data not synced → wait-retry vs silent skip? Handler safe to run twice (idempotency)? Malformed message handling / dead-letter configured? Ordering assumptions vs broker guarantees? |293| ApiContract TRUE | `[Review-ApiContract] API contract change — backward compat, client alignment, auth` | Additive or breaking? Breaking → versioning or coordinated deploy required. All callers (UI, other services, tests) still compatible? New endpoint protected appropriately? No required response fields added without client update? |294| SecurityChange TRUE | `[Review-SecurityChange] Security/permission change — all paths covered, no privilege escalation` | All code paths reaching the gate covered? Negative test verifying unauthorized access DENIED? Privilege escalation possible? BOTH enforcement AND display control updated? Permission definition in single authoritative place (no duplicated strings risking drift)? |295| ConfigChange TRUE | `[Review-ConfigChange] Config/env change — all environments, no secrets committed` | New config key present in ALL environment configs? Hardcoded default masking missing production config? Any secret value in the diff? → CRITICAL if yes. Documented in setup guide? App fails fast if config missing? |296| InfraChange TRUE | `[Review-InfraChange] Infrastructure change — env parity, no dev values in prod, reproducible build` | Change affects all environments consistently? Hardcoded dev values (localhost, debug flags, dev credentials)? Pinned image/dependency versions? Local dev impact documented? CI/CD secret/permission requirements documented? |297298**AI-SDD risk lenses:** Apply these lenses when the changed files touch specs, workflows, tooling, or shared guidance.299300| Lens | Review focus |301| --------------------------- | ---------------------------------------------------------------------------------------------- |302| Contract/API/routes | Public behavior, clients, generated specs, and regression tests still agree. |303| Permissions/security-review | Enforcement, display controls, negative tests, and authoritative permission definitions align. |304| Config/flags | All environments, examples, fail-fast behavior, and docs are current. |305| Docs/spec/test drift | Canonical specs, Section 8 TCs, dashboards, and test code are synchronized or explicitly N/A. |306| Generated mirrors | Shared skill/workflow/tooling changes were synced to generated agent surfaces. |307| Reference-only artifacts | AI-extracted specs/TCs remain draft/reference until accepted by the owning review gate. |308309**Step 3: Work through change-type tasks before dimensional review**310311For each created change-type task:3123131. Set task to `in_progress`3142. Work through ALL applicable concerns — the table above is a starting point, not a ceiling3153. For each concern: cite `file:line` for PASS or describe finding for FAIL/WARN3164. Write findings under `## {Task Subject} Findings` in report3175. Set task to `completed`318319> **IMPORTANT:** Complete ALL change-type tasks FIRST, then proceed to Phase 0.7.320> If no change-type signals detected, log `"No high-risk change types detected"` and proceed.321322**Phase 0.7: Change Surface Detection + Dynamic Review Tasks (MANDATORY)**323324> **Purpose:** Let AI categorize the changes by nature and create review tasks accordingly.325> Derive categories from what the project's actual changed files are, never assume a fixed set.326> **Think, don't classify into a preset grid.** The AI owns this step entirely.327328**Step 1: Derive categories from the diff**329330```bash331git diff --name-only HEAD # unstaged332git diff --cached --name-only # staged333# For branch or commit-range review, use the user-provided diff source:334git diff --name-only <base>335336…(truncated)