# Code Quality Review

> [Code Quality] Use when evaluating received review feedback, reviewing named code on request, or verifying a completion claim. Current diffs: changes-review; rationale: why-review.

- Skill: `duc01226/code-quality-review` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add duc01226/code-quality-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/code-quality-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: duc01226 (https://skillmd.com/u/duc01226)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/duc01226/code-quality-review

---


> Codex compatibility note:
> - Invoke `$skill-name`: load the registered `.agents/skills/<name>/SKILL.md` and execute it with Codex tools; no separate `Skill` tool or Claude mode switch is needed. When a workflow step or another skill names a skill, read that file in full yourself (every line, with no line limit; in parts only when output is cut off): a skill whose implicit invocation is off is never loaded for you. Author `.claude/**`; mirrors are generated.
> - Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
> - Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
> - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task.
> - Preserve protocol order unless the user approves a deviation. Workflows use `$start-workflow`: gates stay fixed; other steps may flex with logged reasons and evidence.
<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->

> **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run, `$start-workflow` → Workflow-step mode bounds this rule.
> **[BLOCKING]** Before each step or sub-skill call, update todo 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.

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->

## Quick Summary

> **Review modes:** For review/audit work, standalone defaults to `--review-only` (`--report-only` alias); `--fix-loop` enables review → validate → authorized fix → fresh re-review, default cap 3. `--fix-loop --loop-owner=caller` returns a read-only pass to the caller that owns fixes/re-review. Create triage, review, validation and re-review todo tasks first; apply the carried `review-policy` contract for LOW deferral and user-approved bounded extensions. Non-review modes and terminal findings validation keep their own dispatch.

**Goal:** Verify feedback, request targeted code-reviewer reviews, and gate completion claims so accepted code is correct, easy to change and convention-aligned.

**Summary:**

- Evaluate feedback, review named code, or verify completion; current/branch diffs route to `changes-review`. Prepared inputs establish scope, never acceptance.
- Create report → assess blast radius and full-pipeline impact → detect risks, plan compliance and surfaces → review each file → holistic assessment → final result → validate findings → fix validated blockers → full re-review after fixes.
- Direct named-code reviews resolve the requested files and applicable rules, including a conditional domain entity quality task for new or updated entities. Feedback evaluation uses the supplied evidence. Trace consumers/dependents and tests; cite `file:line` before acceptance.
- Round 1 closes every validated severity; from round 2 CRITICAL/HIGH/MEDIUM block and LOW-only defers. Failed binary gates always block; retain the shared LOW deferral and fresh post-fix evidence rule.

> **Routing boundary:** If the user asks to review current changes, uncommitted work, staged/unstaged diffs, or a branch-to-branch diff, use `changes-review` instead.

> **Dispatched as a leaf reviewer** (a sub-agent whose brief assigns your scope): review exactly that scope with every review rule in this skill and return the report. Batching, fan-out, validation passes, the fix loop, re-review rounds, user questions and next steps belong to your caller — except the in-batch `$why-review --validate-findings` over your own report that a batch brief explicitly assigns under the shared adaptive review plan, which you run and record as `validated: in-batch`. When the scope is too large to review well, say so in your return instead of sampling or spawning reviewers.

> **Shared engine (keep in sync):** `code-quality-review` and `changes-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 (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`, `contributing`
> **Architecture** — search: `patterns-reference`, `architecture`, `adr`
> **Test conventions** — search: `integration-test-reference`, `test-guide`, `test-conventions`
> **Design system** — search: `design-system`, `design-tokens`, `component-library`
>
> Read found docs relevant to the selected surface; UI design authorities apply to UI changes. Resolve the canonical artifact/case profile from config and required references before spec/test checks: use native owners, roles, IDs, carriers and cardinality when declared; strict §3/§4/§5/§8 and TC examples below apply only when absent. Invalid or unresolved declarations stay BLOCKED; do not create a shadow registry. None found → inspect local code/config and state material assumptions.

**Workflow:**

1. **Create Review Report** — Init `tmp/reports/code-review-{date}-{slug}.md`

2. **Phase 0: Blast Radius** — assess by grep/read first; an optional graph hint when the change looks high-risk
3. **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)
4. **Phase 0.3: Risk Detection** — Detect dependency, migration, bus/event, API, security, config, and infra risks
5. **Phase 0.5: Plan Compliance** — Verify changed files and tests against active plan when present
6. **Phase 0.7: Surface Detection** — Classify files by language + directory semantics + change nature → route sub-agents; invoke `$ui-design --mode=review` when frontend/UI files are present
7. **Phase 1: File-by-File** — Review each file, update report with correctness, convention, DRY, intent, test, and docs checks
8. **Phase 2: Holistic** — Re-read accumulated report, assess overall approach, architecture, duplication, and cross-boundary behavior
9. **Phase 3: Final Result** — Update report with overall assessment, critical issues, recommendations, docs staleness, and test gaps
10. **Fix Loop: Validate → Fix → Full Re-Review** — When findings exist, validate them first, fix only validated findings that block the current round, then restart the full review after the fix cycle (including round-1 LOW fixes); round-2 LOW-only findings are recorded/deferred and do not open another round.

**Key Rules:**

- **Report-Driven**: Build report incrementally; re-read for big picture
- **Detect First**: Assess blast radius (grep/read; an optional graph hint may help), 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 once the persisted `minRounds` is met.** Do not spend a fresh-context pass re-reviewing known findings before validation/fix; re-review after fixes change the target or to satisfy an explicitly declared independent-pass minimum.

## Contents

- [Quick Summary](#quick-summary)
- [Code Review](#code-review)
- [Review Mindset (NON-NEGOTIABLE)](#review-mindset-non-negotiable)
- [First Principle — Easy to Change · Easy to Scale · Easy to Maintain](#first-principle--easy-to-change--easy-to-scale--easy-to-maintain)
- [Core Principles (ENFORCE ALL)](#core-principles-enforce-all)
- [Graph-Enhanced Review (optional advice)](#graph-enhanced-review-optional-advice)
- [Review Approach (Report-Driven Two-Phase — CRITICAL)](#review-approach-report-driven-two-phase--critical)
- [Validated Fix + Full Re-Review (MANDATORY when findings are fixed)](#validated-fix--full-re-review-mandatory-when-findings-are-fixed)
- [Clean Code Rules (MUST ATTENTION CHECK)](#clean-code-rules-must-attention-check)
- [Data Lifecycle Rules (MUST ATTENTION CHECK)](#data-lifecycle-rules-must-attention-check)
- [Legacy Pattern Compliance](#legacy-pattern-compliance)
- [When to Use This Skill](#when-to-use-this-skill)
- [Quick Decision Tree](#quick-decision-tree)
- [Receiving Feedback Protocol](#receiving-feedback-protocol)
- [Requesting Review Protocol](#requesting-review-protocol)
- [Verification Gates Protocol](#verification-gates-protocol)
- [Related](#related)
- [Systematic Review Strategy](#systematic-review-strategy)
- [Architecture Boundary Check](#architecture-boundary-check)
- [Phase 4: Why-Review Self-Validation Gate (MANDATORY when findings exist)](#phase-4-why-review-self-validation-gate-mandatory-when-findings-exist)
- [Next Steps](#next-steps)
- [AI Agent Integrity Gate (NON-NEGOTIABLE)](#ai-agent-integrity-gate-non-negotiable)
- [Prompt-Enhance Closing Anchors](#prompt-enhance-closing-anchors)
- [Closing Reminders](#closing-reminders)

# Code Review

Three practices: receiving feedback with technical rigor, requesting systematic reviews via code-reviewer subagent, enforcing verification gates before completion claims.

> Optional: `python .claude/scripts/code_graph query tests_for <function> --json` on changed functions can hint at coverage gaps (verify by reading the tests).

## 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:line` evidence (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 · Easy to Scale · Easy to Maintain

> The full gate is `SYNC:core-engineering-principles`, published at `.claude/skills/shared/protocols/core-engineering-principles.md`; read its full text when absent from current context; its closing digest ends this file.

**Skill focus:** 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.

---

## 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**            | Compare repeated responsibilities; share only with aligned ownership/change reasons and lower change cost                                  |
| **Clean Code**     | Readable intent, cohesive responsibilities and purposeful names; size/nesting signal investigation, not automatic refactors              |
| **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 (optional advice)

Read [references/code-quality-review-conditional-checks.md](references/code-quality-review-conditional-checks.md) when the change is high-risk (shared contract, many callers, cross-module or cross-service flow, public API) and `.code-graph/graph.db` exists; it holds the optional graph queries (blast radius, tests for a function, downstream and two-way traces) and the >20-node hint rule. Low-risk or local work skips it.

## Review Approach (Report-Driven Two-Phase — CRITICAL)

**MANDATORY FIRST: Create Todo Tasks**

| Task                                                                   | Status      |
| ---------------------------------------------------------------------- | ----------- |
| `[Review] Create report file`                                          | in_progress |
| `[Review Phase 0] Assess blast radius (grep/read; optional graph hint)` | 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-design --mode=review sub-review — skip if no frontend/UI files in changeset` | pending     |
| `[Review Phase 0.7c] Domain entity quality — conditional on new or updated domain entities, value objects or aggregates` | 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 blocking findings, and full re-review until the current severity bar is clear` | pending     |
| `[Review Final] Consolidate all rounds`                                | pending     |

**Step 0: Create Report File**

Create `tmp/reports/code-review-{date}-{slug}.md` with Scope, Files to Review sections.

**Phase 0: Blast Radius (grep/read first; optional graph hint)**

Assess impact by grep/reading callers and dependents before reviewing. Optional, for a high-risk change when `.code-graph/graph.db` exists: `python .claude/scripts/code_graph graph-blast-radius --json` (or the project equivalent) can add hints — it may be stale or incomplete, so verify by reading.

- Record impacted files count, untested changed functions, and risk level in the report (mark graph-derived numbers as hints)
- Prioritize high-impact files during Phase 1

Without a graph (or with a stale one), proceed to Phase 0.1 on grep/reading; never a finding.

**Phase 0.1: Change Context Comprehension & Full-Pipeline Impact Trace (MANDATORY — comprehension-first)**

> **MANDATORY:** Before file-by-file or dimensional review, comprehend the change and trace the main affected pipeline across every boundary. Phase 0 supplies impact data; apply **Cross-Stack Impact Trace** and **Cross-Service Check** here to inform Phase 0.3 risk tasks and Phase 2 assessment, preserving both later phases.

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 (full published sources named by the guides; read applicable text absent from current context).

**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`; plans root default `plans/`, overridable via `docsRoots.plans.path` in `docs/project-config.json`). 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-design --mode=review` (see Phase 0.7b) |
| AI surface? Only if the change creates or changes a model call, prompt, agent, tool/MCP, retrieval or eval (see `node .claude/scripts/ai-signal-scan.cjs`) | read `.claude/skills/shared/protocols/ai-engineering-gate.md`; `$ai-engineering-review --report-only`, fold its findings in; otherwise skip this row |
| 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-design --mode=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 `$ui-design --mode=review` 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.7c: Domain Entity Quality (CONDITIONAL)**

For new or updated domain entities/VOs/aggregates, read [the conditional task contract](../changes-review/SKILL.md#domain-entity-quality-conditional-task); it routes the shared quality criteria only when relevant. Complete the task or incorporate the named caller's domain pass. No surface → record inspected paths and skip; leaves return gaps without nested delegation.

**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, and 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**: Is behavior placed with its documented owner, and are consumers kept behind the project's intended boundaries?
- **Data ownership**: Are constants/config/derivations at the invariant or contract owner established by this architecture?
- **Duplication**: Grep to verify — duplicated logic across changes?
- **Architecture**: Does the change preserve the project’s selected dependency, module and service boundaries where present?
- **Plan Compliance**: If active plan → check `## Plan Context`: impl matches requirements, TCs have code evidence (not "TBD"), no requirement unaddressed
- **Design Patterns**: Do actual coupling, duplicated knowledge or variation justify a simpler/shared owner? Preserve fitting local branches and independent responsibilities; do not require base classes or a particular layer.
- **Cross-Boundary Behavior**: Callers/callees aligned? API/event contracts consistent? New wiring reachable?
- **Whole-diff correctness** (every behavior-changing diff): cover the complete behavior flows per `SYNC:whole-diff-correctness`. One reader owns a fitting working set; otherwise the parent assigns bounded overlapping flow leaves and cross-flow synthesis with complete entry/range/rule coverage. Batches add depth but never replace flow coverage.
- **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):** Review the whole canonical intent/contracts + tests + code package through the resolved profile. Use the project’s required mutation/fault/intent-strength proof; a surviving required probe exposes a missing invariant, while line coverage alone proves no assertion strength. Universally quantified hard invariants need property/boundary coverage in the selected case format. Every behavior-changing finding records both spec feedback and the mapped executor/assertion/result action. Adjudicate CODE-WRONG / SPEC-STALE / AMBIGUOUS / SPEC-SILENT through the shared owner. A proven spec-silent invariant must be added to the selected canonical intent/contracts and guarding evidence case/test; strict-default §4/§3/§5/§8 and TC only when no native contract exists. Never leave the rule only in code/tests or fabricate execution.

**MUST ATTENTION CHECK — Clean Code:** YAGNI (unused params, speculative interfaces)? KISS (simpler exists)? Does size/nesting obscure intent or amplify changes under the project’s conventions?

**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-manager --mode=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 that block the current round. Because fixes change the review target, restart the full review after the fix cycle (including round-1 LOW fixes); from round 2 onward a LOW-only result is deferred and does not trigger another cycle. If that restarted protocol uses sub-agents, construct each Agent call with the canonical template from `SYNC:review-protocol-injection`:

1. Copy Agent call shape from `SYNC:review-protocol-injection` verbatim
2. 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`
3. 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."`
4. Target Files: `"use the explicit files, plan scope, or reviewer-provided target range"`
5. Report: `tmp/reports/code-review-rerun{N}-{date}.md`

After sub-agent returns:

1. **Read** report from `tmp/reports/code-review-rerun{N}-{date}.md`
2. **Integrate** findings as `## Re-Review {N} Findings` — DO NOT filter or override
3. **If findings remain:** validate the new finding set before any additional fixes
4. **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 `ask user question tool`

## Clean Code Rules (MUST ATTENTION CHECK)

| #   | Rule                      | Details                                                                                                                                 |
| --- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| 1   | **No Magic Values**       | Name values when they encode shared policy or unexplained meaning; retain obvious local literals                                                                                                          |
| 2   | **Type Annotations**      | Use the project’s supported type/static-checking conventions; do not impose syntax absent from its language                                                                                    |
| 3   | **Single Responsibility** | Keep cohesive responsibilities; inspect the actual dispatcher/error contract before splitting handlers or assuming swallowed exceptions |
| 4   | **DRY**                   | Share aligned rules/behavior when an evidenced owner reduces future change cost; independent look-alikes may remain separate                                                                                                    |
| 5   | **Naming**                | Names reveal purpose, not mechanism: specific names (`orderRecords` not `data`), Verb+Noun methods, is/has/can/should booleans, no unexplained abbreviations; public/cross-layer abstractions name the capability or domain contract and keep provider details on concrete adapters (`IStorage`/`Storage` → `AzureBlobStorage`), with narrow contracts and local interface syntax |
| 6   | **Performance**           | Judge complexity and bounds against expected/worst workload. Apply supported projection, paging and batching where the actual data path warrants them                                     |
| 7   | **Entity Indexes**        | When persistence/search is in scope, verify the configured store’s actual access paths, index/query semantics and relevant volume evidence; no universal ORM/index recipe      |

## Data Lifecycle Rules (MUST ATTENTION CHECK)

Read [references/code-quality-review-conditional-checks.md](references/code-quality-review-conditional-checks.md) when the reviewed files add or change seeders, fixtures, migrations, reference data or system configuration records; it holds the seeder-versus-migration decision test and what each may and must never contain.

## Legacy Pattern Compliance

Read [references/code-quality-review-conditional-checks.md](references/code-quality-review-conditional-checks.md) when the reviewed files mix legacy and modern patterns (a legacy flag, version marker or annotation in config or manifests); it holds the four-step legacy compliance derivation.

## 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

1. Get git SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
2. Dispatch code-reviewer subagent with: WHAT_WAS_IMPLEMENTED, PLAN_OR_REQUIREMENTS, BASE_SHA, HEAD_SHA, DESCRIPTION
3. 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-simplifier`
- `investigate --mode=debug`

---

## Systematic Review Strategy

> Apply **Systematic Review Batching** to choose the smallest approach preserving full coverage and every gate from risk, related flows, working-set fit and delegation cost. File counts are planning cues; inline, bounded sequential, authorized fresh parallel review and bounded synthesis retain the same obligations.

---

## Architecture Boundary Check

Read [references/code-quality-review-conditional-checks.md](references/code-quality-review-conditional-checks.md) when `docs/project-config.json` declares `architectureRules.layerBoundaries` (absent → skip silently); it holds the per-file layer-import check that BLOCKS on a forbidden import.

---

## 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:**

1. Read own finalized report from `tmp/reports/{skill}-{date}-{slug}.md`
2. Invoke `$why-review` skill with arg: `validate findings in tmp/reports/{skill}-{date}-{slug}.md — verify each finding has file:line proof, steel-man each rejected interpretation, and stress-test severity classifications`
3. Read the validation verdict path returned by why-review, expected as `tmp/reports/why-review-validate-{date}.md`
4. **If why-review demotes/removes any finding:** UPDATE own finalized report with revised severities, remove false positives, and add a `## Why-Review Validation Notes` section citing what changed and why
5. **If why-review confirms all findings:** Append `## Why-Review Validation` line 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:** Adversarial validation catches false positives and inflated severity before the caller accepts them as ground truth.

---

## Next Steps

Choose and report the best supported next step under `SYNC:review-decision-autonomy`; do not ask the user to select `$fix`, `$watzup` or manual continuation. Continue a fixing or closing workflow only when already authorized; a report-only review returns its findings and recommended remedy.

## AI Agent Integrity Gate (NON-NEGOTIABLE)

**Completion ≠ Correctness.** Before reporting ANY work done:

1. **Grep every removed name.** Extraction/rename/delete → grep confirms 0 dangling refs across ALL file types.
2. **Ask WHY before changing.** Existing values intentional until proven otherwise.
3. **Verify ALL outputs.** One build passing ≠ all builds passing.
4. **Evaluate pattern fit.** Copying nearby code? Verify preconditions match — scope, lifetime, base class, constraints.
5. **New artifact = wired artifact.** Created something? Prove it's registered, imported, reachable by all consumers.

---

> **[IMPORTANT]** Use todo tracking to break ALL work into small tasks BEFORE starting. This prevents context loss from long files. For simple tasks, choose the smallest gate-preserving task breakdown without a skip question.

> **Critical Purpose:** Ensure quality — no flaws, bugs, missing updates, stale content. Verify code AND documentation.

> **External Memory:** Complex work → write findings incrementally to `tmp/reports/` — prevents context loss, serves as deliverable.

> **Evidence Gate:** MANDATORY — every claim, finding, recommendation requires `file:line` proof + confidence % (>80% act, <80% verify first).

> **Ownership & reuse:** Inspect actual consumers, invariants and change reasons before recommending sharing. Similar names/lifecycles do not require a base class. Choose the project’s idiom only when it reduces change cost; retain applicable quality-tooling checks.

<!-- PROTOCOL-GUIDES:START -->

> **Protocol guides** — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.

- `bug-detection` — Four bug-detection categories checked on every review; reviewing code for defects → .claude/skills/shared/protocols/bug-detection.md
- `category-review-thinking` — Derive review concerns per category of changed files from domain knowledge; reviewing a changeset that spans several file categories → .claude/skills/shared/protocols/category-review-thinking.md
- `complexity-prevention` — Change-cost lens on complexity (Ousterhout); designing or reviewing code → .claude/skills/shared/protocols/complexity-prevention.md
- `core-engineering-principles` — Core quality gate: easy to change, easy to scale, easy to maintain, judged by future change cost; planning, implementing or reviewing any change → .claude/skills/shared/protocols/core-engineering-principles.md
- `cross-service-check` — Scan producers, consumers, sagas and shared contracts for cross-service impact; concluding an investigation, plan or spec in a service-based system → .claude/skills/shared/protocols/cross-service-check.md
- `cross-stack-impact-trace` — Trace the changed area end to end across the client-server seam before judging files; starting a review of a diff that touches more than

…(truncated)
