[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_progresswhen step starts, setcompletedwhen 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.
Quick Summary
Goal: Ensure reviewed code is correct, easy to change, convention-aligned, and verification-backed before acceptance or handoff — via receiving feedback with verification (not performative agreement), requesting targeted systematic reviews through the code-reviewer subagent, and enforcing verification gates before completion claims.
Routing boundary: If the user asks to review current changes, uncommitted work, staged/unstaged diffs, or a branch-to-branch diff, use
changes-reviewinstead.
Shared engine (keep in sync):
code-reviewandchanges-reviewshare the same review-protocolSYNC: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 (explicit scope / feedback / completion-gate vs git diff) — not in review quality.
MANDATORY Before reviewing, search for project-specific reference docs:
Coding standards — search:
code-review-rules,coding-standards,style-guide,contributingArchitecture — search:patterns-reference,architecture,adrTest conventions — search:integration-test-reference,test-guide,test-conventionsDesign system — search:design-system,design-tokens,component-libraryRead found docs before reviewing. None found → rely on tech stack knowledge from file extensions/directory structure.
Workflow:
- Create Review Report — Init
plans/reports/code-review-{date}-{slug}.md - Phase 0: Blast Radius — Run graph analysis first if
.code-graph/graph.dbexists - 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: Risk Detection — Detect dependency, migration, bus/event, API, security, config, and infra risks
- Phase 0.5: Plan Compliance — Verify changed files and tests against active plan when present
- Phase 0.7: Surface Detection — Classify files by language + directory semantics + change nature → route sub-agents; invoke
/ui-reviewwhen frontend/UI files are present - Phase 1: File-by-File — Review each file, update report with correctness, convention, DRY, intent, test, and docs checks
- Phase 2: Holistic — Re-read accumulated report, assess overall approach, architecture, duplication, and cross-boundary behavior
- Phase 3: Final Result — Update report with overall assessment, critical issues, recommendations, docs staleness, and test gaps
- Fix Loop: Validate → Fix → Full Re-Review — When findings exist, validate them first, fix only validated findings, then restart the full review after the fix cycle
Key Rules:
- Report-Driven: Build report incrementally; re-read for big picture
- Detect First: Run graph blast radius when available, then classify change types and file surfaces before any review
- Easy to Change for Code: Treat future change cost as the primary code-quality metric; DRY, SOLID, abstraction, and patterns are tools only when they reduce change amplification
- No Performative Agreement: Technical evaluation only ("You're right!" banned)
- Verification Gates: Evidence required before completion claims
- Review Current Diffs Elsewhere: Current changes, staged/unstaged diffs, and branch diffs belong to
changes-review - A clean review pass ENDS the review. Do not spend a fresh-context pass re-reviewing known findings before validation/fix; only re-review after fixes change the target.
Code Review
Three practices: receiving feedback with technical rigor, requesting systematic reviews via code-reviewer subagent, enforcing verification gates before completion claims.
Run
python .claude/scripts/code_graph query tests_for <function> --jsonon changed functions to flag coverage gaps.
Review Mindset (NON-NEGOTIABLE)
Skeptical. Every claim needs traced proof file:line. Confidence >80% to act.
- NEVER accept code correctness at face value — trace call paths
- NEVER include finding without
file:lineevidence (grep results, read confirmations) - ALWAYS question: "Does this actually work?" → trace it. "Is this all?" → grep cross-service
- ALWAYS verify side effects: check consumers + dependents before approving
First Principle — Easy to Change
The success metric of every coding decision is future change cost. DRY, SRP, abstraction, design patterns, naming, layering, tests — every technique exists to serve one goal: making the next change cheaper.
When evaluating code, a refactor, a test, or an abstraction, ask: does this make the next change cheaper or more expensive?
- Reject "best practices" that raise change cost (premature abstraction, speculative generality, leaky indirection, ceremony without payoff).
- Name the real enemies in findings: coupling, hidden state, duplicated knowledge, unclear intent, irreversible decisions exposed too early.
- Favor project-owned boundaries around external libraries, for example component/service input-output contracts, when they localize future library changes; reject pass-through wrappers that add ceremony without lowering change cost.
- A simpler design that is easy to change beats a sophisticated design that isn't.
Apply this lens before invoking any specific rule, pattern, or checklist below — if a downstream rule would raise change cost, this principle wins.
Core Principles (ENFORCE ALL)
| Principle | Rule |
|---|---|
| YAGNI | Flag code solving hypothetical problems (unused params, speculative interfaces) |
| KISS | Flag unnecessary complexity. "Is there a simpler way?" |
| DRY | Grep for similar/duplicate code. 3+ similar patterns → flag for extraction |
| Clean Code | Readable > clever. Names reveal intent. Functions do ONE thing. Nesting <=3. Methods <30 lines |
| Convention | MUST ATTENTION grep 3+ existing examples before flagging violations. Codebase convention wins over textbook |
| No Bugs | Trace logic paths. Verify edge cases (null, empty, boundary). Check error handling |
| Proof Required | Every claim backed by file:line evidence. Speculation is forbidden |
| Doc Staleness | Cross-ref changed files against related docs. Flag stale/missing updates |
Technical correctness over social comfort. Verify before implementing. Evidence before claims.
Graph-Enhanced Review (RECOMMENDED if graph.db exists)
python .claude/scripts/code_graph graph-blast-radius --json— prioritize files by impact (most dependents first)python .claude/scripts/code_graph query tests_for <function_name> --json— flag untested changed functionspython .claude/scripts/code_graph trace <file> --direction downstream --json— downstream impact (events, bus, cross-service)python .claude/scripts/code_graph trace <file> --direction both --json— full flow context for controllers/commands/handlers- Wide blast radius (>20 impacted nodes) = high-risk. Flag in report.
Review Approach (Report-Driven Two-Phase — CRITICAL)
MANDATORY FIRST: Create Todo Tasks
| Task | Status |
|---|---|
[Review] Create report file |
in_progress |
[Review Phase 0] Run graph blast-radius if available |
pending |
[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 (MANDATORY comprehension-first; N/A for single-tier/monolith) |
pending |
[Review Phase 0.3] Detect high-risk change types |
pending |
[Review Phase 0.5] Plan compliance check (skip if no active plan) |
pending |
[Review Phase 0.7] Detect categories + route sub-agents |
pending |
[Review Phase 0.7b] /ui-review sub-review — skip if no frontend/UI files in changeset |
pending |
[Review Phase 1] File-by-file review + update report |
pending |
[Review Phase 2] Holistic assessment |
pending |
[Review Phase 3] Final findings, docs triage, and test sync findings |
pending |
[Review Fix Loop] Validate findings, fix validated issues, and full re-review if fixes are applied |
pending |
[Review Final] Consolidate all rounds |
pending |
Step 0: Create Report File
Create plans/reports/code-review-{date}-{slug}.md with Scope, Files to Review sections.
Phase 0: Graph Blast Radius (FIRST WHEN AVAILABLE)
If .code-graph/graph.db exists, run graph impact analysis before reviewing:
python .claude/scripts/code_graph graph-blast-radius --jsonor the project equivalent- Record impacted files count, untested changed functions, and risk level in the report
- Prioritize high-impact files during Phase 1
If graph data is unavailable, record "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 Phase 2 holistic cross-boundary assessment — 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).
Phase 0.3: Detect High-Risk Change Types
Before file review, inspect the target diff or explicit file set for:
- Bugfix, failed verification, stale/incorrect final output, regression, or behavior-changing fix — require
Debugger Trace: End -> Start, all feeder paths, hypothesis matrix, owning fix layer, and forward convergence proof; missing trace evidence is a High/Critical review finding - Dependency upgrades — semver, breaking changes, advisories, peer compatibility
- Migrations or schema changes — rollback, lock/volume impact, zero-downtime deployment, idempotent backfill
- Bus events/messages — consumer existence, idempotency, retries, poison/dead-letter handling
- API contract changes — backward compatibility, caller alignment, auth, required response fields
- Security changes — enforcement coverage, privilege escalation, negative tests, duplicated permission strings
- Config/env changes — all environments covered, no secrets, fail-fast behavior, setup docs
- Infra changes — dev/prod parity, pinned versions, CI/CD permissions, reproducible builds
Create focused review tasks for every true signal and complete them before dimensional review.
Phase 0.5: Plan Compliance Check (CONDITIONAL)
If active plan context exists, verify scope, test evidence, and success criteria against the plan before file review; otherwise record the skip reason.
Goal Contract mapping (CONDITIONAL — when an active goal exists): Resolve the active Goal Contract per the goal-contract-satisfaction-loop protocol (active plan goal.md → plans/goals/{YYMMDD-HHmm}-{slug}/goal.md). When found, map the reviewed changes to the saved success criteria in the report — which criteria this changeset advances (with file:line evidence), which it leaves untouched, and any change serving NO saved criterion (flag as scope drift unless justified). Record No active goal — mapping skipped. when none exists; do NOT create a goal file from inside a review.
Phase 0.7: Detect Review Categories
Before any review — classify the changeset and route sub-agents:
| Signal in changed files | Route to |
|---|---|
| Auth/permission/token/encryption files | security-auditor |
| Query files, caching, batch processing | performance-optimizer |
| Source code (logic, handlers, services) | code-reviewer |
Frontend/UI files (components, templates, .html/.scss/.css, design-system) |
/ui-review skill (see Phase 0.7b) |
| Docs, plans, specs, markdown | general-purpose |
| Mixed changeset with security/perf files | Spawn specialized sub-agent first, then code-reviewer |
Phase 0.7b: Frontend/UI Sub-Review (CONDITIONAL — /ui-review)
If the changeset contains any frontend/UI files matching the project's configured UI patterns (components, templates, .html/.scss/.css, design-system tokens), invoke the /ui-review skill as a sub-review so UI-specific concerns are covered — long-content overflow (wrap vs ellipsis+tooltip), responsive multi-screen flex, flex-grow with min/max over fixed px, semantic z-index discipline (no raw numbers, no !important), and BEM classes on all template elements. Fold its findings into this report's Phase 3 results.
Skip (record reason) when no frontend/UI files are present in the changeset — log "Skipped Phase 0.7b — no frontend/UI files in changeset".
Phase 0.8: Derive Review Categories
Group changed files by: file language (extension), directory semantics (path), change nature (new entity, schema, config, UI, test).
For each category: name it, create sub-task, derive concerns using SYNC:category-review-thinking (first principles — NOT a fixed checklist).
Category list = Phase 1 work breakdown. Each category → own section in report.
Phase 1: File-by-File Review (Build Report)
For EACH file, immediately update report:
- File path, Change Summary, Purpose, Issues Found
- Convention check: Grep 3+ similar patterns — does new code follow existing convention?
- Correctness check: Trace logic — null, empty, boundary, error cases handled?
- DRY check: Grep for similar/duplicate code — does this logic exist elsewhere?
- Intention check: Does the change serve the stated purpose? Flag unrelated modifications
- Test check: Changed behavior has corresponding test/spec coverage or a documented gap
- Documentation check: Related docs/specs/READMEs still match the changed behavior
Phase 2: Holistic Review (Re-read Report)
After all files reviewed, re-read accumulated report:
- Technical Solution: Overall approach coherent as unified plan?
- Responsibility: Logic in LOWEST layer? Business logic not in controllers?
- Data ownership: Constants/config in model/entity, not controller/component?
- Duplication: Grep to verify — duplicated logic across changes?
- Architecture: Clean Architecture? Service boundaries respected?
- Plan Compliance: If active plan → check
## Plan Context: impl matches requirements, TCs have code evidence (not "TBD"), no requirement unaddressed - Design Patterns: Pattern opportunities (switch→Strategy)? Anti-patterns (God Object, Copy-Paste, Circular Dep)? DRY via base classes?
- Cross-Boundary Behavior: Callers/callees aligned? API/event contracts consistent? New wiring reachable?
- Test Sync: Business logic changes have corresponding tests or explicit user-facing gap
- Translation Sync: Multilingual UI text changes have translation updates or explicit risk acceptance
- Bugfix Trace Completeness: If the diff is a bugfix or behavior-changing fix, the review report must state whether final-state trace, feeder paths, hypothesis matrix, owning fix layer, forward convergence proof, and tests/proof mapping are complete
MUST ATTENTION CHECK — Spec-Loop Test Discipline (changed core logic): Beyond the happy/error path traces above, hold changed core logic to a hard-to-fake bar. Apply a MUTATION-SCORE bar — a surviving mutant means a missing invariant, so demand the killing test — and do NOT accept a line-coverage % as proof of test strength. Flag any [HARD]/§5 invariant whose only coverage is example tests with no universally-quantified property TC (plus boundary counter-case) as a HIGH finding. Every behavior-changing finding requires a Dual-Feedback row (does it feed the spec? does it feed the tests? a blank axis = INCOMPLETE) — record it in the report. Adjudicate any spec divergence per SYNC:spec-drift-adjudication (CODE-WRONG / SPEC-STALE / AMBIGUOUS / SPEC-SILENT); a SPEC-SILENT finding — the code correctly enforces an invariant NO spec artifact states — has BOTH axes non-N/A: Spec feedback = add the missing §4 BR / §3 AC (+ §5 invariant if applicable) and a §8 TC via /spec [update] + /spec [mode=tests]; Test feedback = the new property/regression test guarding the now-written invariant — never leave a discovered invariant only in code or only in tests. Review the whole package (spec + tests + code), not just the diff, so the spec is enriched, not just patched.
MUST ATTENTION CHECK — Clean Code: YAGNI (unused params, speculative interfaces)? KISS (simpler exists)? Methods >30 lines or nesting >3?
MUST ATTENTION CHECK — Correctness: Null/empty/boundary handled? Error paths caught? Async race conditions? Trace happy + error paths.
Documentation Staleness Check:
For each changed file — grep file name/module across docs/ and AI tooling dirs. Changed behavior → flag stale doc (specific section + what changed). Flag the staleness only — never auto-fix docs here.
Common staleness patterns: count/limit changed → docs embedding that number | API/contract changed → API usage docs | hook/skill added/removed → catalogs/README | schema changed → entity reference docs.
Phase 3: Final Review Result
Update report: Overall Assessment, Critical Issues, High Priority, Architecture Recommendations, Cross-Boundary Impact (from Phase 0.1 — per client↔server seam AND per service/event/external touchpoint: NONE / ADDITIVE / BREAKING with routed fix; or explicit "Single-tier / monolith — N/A"), Documentation Staleness, Positive Observations.
If documentation staleness is detected, recommend docs-update and list exact stale sections; do not silently pass stale docs.
Validated Fix + Full Re-Review (MANDATORY when findings are fixed)
After Phase 3, do not spawn a fresh reviewer just to re-review the same finding set. First validate findings, then fix only validated findings. Because fixes change the review target, restart the full review after the fix cycle. If that restarted protocol uses sub-agents, construct each Agent call with the canonical template from SYNC:review-protocol-injection:
- Copy Agent call shape from
SYNC:review-protocol-injectionverbatim - Embed full verbatim body of all 11 SYNC blocks:
SYNC:spec-tests-code-triangulation,SYNC:evidence-based-reasoning,SYNC:bug-detection,SYNC:design-patterns-quality,SYNC:complexity-prevention,SYNC:logic-and-intention-review,SYNC:test-spec-verification,SYNC:fix-layer-accountability,SYNC:rationalization-prevention,SYNC:graph-assisted-investigation,SYNC:understand-code-first - Task:
"Run a full fresh code-review pass over the current assigned scope after validated fixes were applied. Focus: cross-cutting concerns, interaction bugs, convention drift, missing pieces, subtle edge cases, logic errors, test spec gaps, and regressions introduced by the fixes." - Target Files:
"use the explicit files, plan scope, or reviewer-provided target range" - Report:
plans/reports/code-review-rerun{N}-{date}.md
After sub-agent returns:
- Read report from
plans/reports/code-review-rerun{N}-{date}.md - Integrate findings as
## Re-Review {N} Findings— DO NOT filter or override - If findings remain: validate the new finding set before any additional fixes
- Repeat only after another fix cycle: restart the full review again after validated fixes are applied; if the same blocker repeats across 2 full invocations with no progress, escalate via
AskUserQuestion
Clean Code Rules (MUST ATTENTION CHECK)
| # | Rule | Details |
|---|---|---|
| 1 | No Magic Values | All literals → named constants |
| 2 | Type Annotations | Explicit parameter and return types on all functions |
| 3 | Single Responsibility | One concern per method/class. Event handlers/consumers: one handler = one concern. NEVER bundle — a framework event dispatcher can swallow handler exceptions silently |
| 4 | DRY | No duplication; extract shared logic |
| 5 | Naming | Specific (orderRecords not data), Verb+Noun methods, is/has/can/should booleans, no abbreviations |
| 6 | Performance | No O(n²) (use dictionary). Project in query (not load-all). ALWAYS paginate. Batch-by-IDs (not N+1) |
| 7 | Entity Indexes | Collections: index management methods. EF Core: composite indexes. Expression fields match index order. Text search → text indexes |
Data Lifecycle Rules (MUST ATTENTION CHECK)
Decision test: "Delete the DB and start fresh — does this data still need to exist?" Yes → Seeder/fixture. No → Migration.
| Type | Contains | NEVER contains |
|---|---|---|
| Seeder / Fixture | Default records, system config, reference data (idempotent — safe to run every startup) | Schema changes |
| Migration | Schema changes, column adds/removes, data transforms, index changes | Default records, permission seeds, system config |
Apply project's language/framework conventions. Principle universal — implementation project-specific.
Legacy Pattern Compliance
When reviewing files with legacy and modern patterns:
- Detect legacy signals — search
project-config.json,package.json, or equivalent for"legacy", version flags, feature annotations - Read what "legacy" means — grep 3+ legacy files to understand pattern constraints vs. modern files
- Derive compliance rules — what lifecycle/memory management differences exist between legacy/modern for this tech stack?
- Apply tech stack knowledge to flag anti-patterns
NEVER assume any specific framework's lifecycle. Derive from codebase evidence.
When to Use This Skill
| Practice | Triggers | MUST ATTENTION READ |
|---|---|---|
| Receiving Feedback | Review comments received, feedback unclear/questionable, conflicts with existing decisions | references/code-review-reception.md |
| Requesting Review | After each subagent task, major feature done, targeted review scope, after complex bug fix | references/requesting-code-review.md |
| Verification Gates | Before any completion claim, commit, push, or PR. ANY success/satisfaction statement | references/verification-before-completion.md |
Quick Decision Tree
SITUATION?
│
├─ Received feedback
│ ├─ Unclear items? → STOP, ask for clarification first
│ ├─ From human partner? → Understand, then implement
│ └─ From external reviewer? → Verify technically before implementing
│
├─ Completed work
│ ├─ Major feature/task? → Request code-reviewer subagent review
│ └─ Before merge? → Request code-reviewer subagent review
│
└─ About to claim status
├─ Have fresh verification? → State claim WITH evidence
└─ No fresh verification? → RUN verification command first
Receiving Feedback Protocol
Pattern: READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
- NEVER use performative agreement ("You're right!", "Great point!", "Thanks for...")
- NEVER implement before verification
- MUST ATTENTION restate requirement, ask questions, or push back with technical reasoning
- ask for clarification on ALL unclear items BEFORE starting
- grep for usage before implementing suggested "proper" features (YAGNI check)
Source handling: Human partner → implement after understanding. External reviewer → verify technically, push back if wrong.
Full protocol: references/code-review-reception.md
Requesting Review Protocol
- Get git SHAs:
BASE_SHA=$(git rev-parse HEAD~1)andHEAD_SHA=$(git rev-parse HEAD) - Dispatch code-reviewer subagent with: WHAT_WAS_IMPLEMENTED, PLAN_OR_REQUIREMENTS, BASE_SHA, HEAD_SHA, DESCRIPTION
- Act on feedback: Critical → fix immediately. Important → fix before proceeding. Minor → note for later.
Full protocol: references/requesting-code-review.md
Verification Gates Protocol
Iron Law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
Gate: IDENTIFY command → RUN it → READ output → VERIFY it confirms claim → THEN claim. Skip any step = lying.
| Claim | Required Evidence |
|---|---|
| Tests pass | Test output shows 0 failures |
| Build succeeds | Build command exit 0 |
| Bug fixed | Original symptom test passes |
| Requirements met | Line-by-line checklist verified |
Red Flags — STOP: "should"/"probably"/"seems to", satisfaction before verification, committing without verification, trusting agent reports.
Full protocol: references/verification-before-completion.md
Related
code-simplifierdebug-investigaterefactoring
Systematic Review Protocol (10+ changed files)
When Phase 1 finds 10+ changed files, apply the Systematic Review Batching protocol (map-reduce: size-capped batches + hierarchical synthesis) defined below.
Workflow Recommendation
MANDATORY — NO EXCEPTIONS: If NOT already in a workflow, use
AskUserQuestionto ask user:
- Activate
workflow-review-changesworkflow (Recommended) — full review → validated fix cycle → re-review until clean- Execute
/code-reviewdirectly — run standalone
Architecture Boundary Check
For each changed file, verify no forbidden layer imports:
- Read rules from
docs/project-config.json→architectureRules.layerBoundaries - Determine layer — match file path against each rule's
pathsglob patterns - Scan imports — grep for the configured language's import/include statements
- Check violations — import path contains forbidden layer name → violation
- Exclude framework — skip files matching
architectureRules.excludePatterns - BLOCK on violation —
"BLOCKED: {layer} layer file {filePath} imports from {forbiddenLayer} ({importStatement})"
If architectureRules absent in project-config.json → skip silently.
Phase 4: Why-Review Self-Validation Gate (MANDATORY when findings exist)
Purpose: Adversarial validation of own findings BEFORE handoff. Catches over-flagged Highs, false positives, and severity inflation at the source rather than letting them propagate downstream.
Trigger: Any finding produced (Critical, High, Medium, OR Low). Skip ONLY when the report's verdict is unconditional PASS with literally zero findings.
Protocol:
- Read own finalized report from
plans/reports/{skill}-{date}-{slug}.md - Invoke
/why-reviewskill with arg:validate findings in plans/reports/{skill}-{date}-{slug}.md — verify each finding has file:line proof, steel-man each rejected interpretation, and stress-test severity classifications - Read the validation verdict path returned by why-review, expected as
plans/reports/why-review-validate-{date}.md - If why-review demotes/removes any finding: UPDATE own finalized report with revised severities, remove false positives, and add a
## Why-Review Validation Notessection citing what changed and why - If why-review confirms all findings: Append
## Why-Review Validationline to own report stating "All N findings re-validated against actual code; no severity changes."
Skip conditions (record explicit reason if skipping):
- Verdict is unconditional PASS with zero findings → log "Skipped — no findings to validate"
- Why-review skill itself is the active context (avoid recursion)
Why this exists: AI sub-agent reports inherit confirmation bias — the orchestrator absorbs severity claims as ground truth. The 2026-05-09 review incident produced 5 Highs; adversarial validation demoted 3 of them. Codify this as standard practice.
Next Steps
MANDATORY — NO EXCEPTIONS after completing, use AskUserQuestion:
- "/fix (Recommended)" — review found issues needing fixes
- "/watzup" — review clean, wrap up session
- "Skip, continue manually" — user decides
AI Agent Integrity Gate (NON-NEGOTIABLE)
Completion ≠ Correctness. Before reporting ANY work done:
- Grep every removed name. Extraction/rename/delete → grep confirms 0 dangling refs across ALL file types.
- Ask WHY before changing. Existing values intentional until proven otherwise.
- Verify ALL outputs. One build passing ≠ all builds passing.
- Evaluate pattern fit. Copying nearby code? Verify preconditions match — scope, lifetime, base class, constraints.
- New artifact = wired artifact. Created something? Prove it's registered, imported, reachable by all consumers.
[IMPORTANT] Use
TaskCreateto break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.
Critical Purpose: Ensure quality — no flaws, bugs, missing updates, stale content. Verify code AND documentation.
External Memory: Complex work → write findings incrementally to
plans/reports/— prevents context loss, serves as deliverable.
Evidence Gate: MANDATORY — every claim, finding, recommendation requires
file:lineproof + confidence % (>80% act, <80% verify first).
OOP & DRY: MANDATORY — flag patterns extractable to base class/generic/helper. Same-suffix/lifecycle/responsibility classes share common base. Apply idiomatic abstraction (base class, mixin, trait, protocol) for project's language. Verify linting/analyzer configured.
Cross-Stack Impact Trace — FIRST review action: comprehend change holistically, THEN judge files. Every reviewed diff: note change context, trace full pipeline of main affected area end-to-end across client↔server seam, so a change on one tier can never silently break the other. (Distinct from
SYNC:cross-service-check, which owns service-to-service / event boundary — this owns client↔server tier seam inside one app; pair both for full-pipeline coverage.)
- Comprehend context FIRST — before file-by-file review, write short Change Context note: what changed, intent (why), originating tier (frontend / backend / shared / infra), main affected feature/flow. Do before flagging anything.
- Identify cross-stack seam(s) — for main affected area, locate contract seam(s) between client and server: API route/endpoint + verb, request/response DTO or payload shape, shared type/schema, event/message contract, query/route params. Infer tier layout from
docs/project-config.jsonand project conventions.- Trace full pipeline end-to-end, in change's direction:
- Backend change → trace FORWARD to every frontend consumer: handler/controller → response DTO/serializer → API client/service → store/state → component/template rendering or submitting it.
- Frontend change → trace BACKWARD to backend contract: component/form → API client call → route/endpoint → request DTO/validation → handler/domain.
- When
.code-graph/graph.dbexists, use/graph-connect-apiandpython .claude/scripts/code_graph trace <file> --direction both --jsonto map connection; otherwise grep route path, DTO/type name, each field name across BOTH tiers.- Verify BOTH sides still agree — for every changed seam confirm other tier matches: route path & verb, field names & types, nullability/optionality, required vs optional params, enum values, auth/permission, error/status shape. Any mismatch = BREAKING finding (backend change breaks a frontend consumer, or frontend now sends what backend rejects).
- Classify each seam: NONE (no contract change) / ADDITIVE (backward-compatible) / BREAKING (consumer on other tier must change too). BREAKING seam whose other-tier consumer NOT updated in same diff = HIGH severity minimum (CRITICAL for auth/money/data-integrity paths).
Skip ONLY when change has no cross-tier seam — pure docs, pure styling with no data contract, or single-tier tooling. State explicitly:
Single-tier change — no cross-stack seam. Backend-only or single-tier repo still traces internal consumers (SYNC:cross-service-checkfor service/event boundaries).BLOCKED until: Change Context noted · seam(s) identified or explicit N/A · full pipeline traced in change direction · every changed seam classified NONE / ADDITIVE / BREAKING.
Cross-Service Check — Microservices/event-driven: MANDATORY before concluding investigation, plan, spec, or feature doc. Missing downstream consumer = silent regression.
Boundary Grep terms Event producers Publish,Dispatch,Send,emit,EventBus,outbox,IntegrationEventEvent consumers Consumer,EventHandler,Subscribe,@EventListener,inboxSagas/orchestration Saga,ProcessManager,Choreography,Workflow, `O
…(truncated)