Production Readiness Review

[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.

Quick Summary

Goal: Ensure service/API changes are production-ready for observability, reliability, data integrity, and database performance — scoring each of these dimensions on service-layer and API changes.

Summary:

• Main steps (in order): (1) Resolve scope — args else git diff --name-only uncommitted; backend service/API files only, skip frontend/tests/docs/config-only. (2) Score 12 criteria 0-2 across the 4 dimensions (/24). (3) Extended SRE Readiness gate — 8 pass/fail deploy-time + operate-time items; an unaccepted CRITICAL/HIGH fail blocks PASS regardless of the /24 score. Gating, NOT scored — does not change the /24 math. (4) Map score + gate → verdict. (5) Structural Impact Analysis — graph gate (blast-radius, tests_for, downstream trace) when graph.db exists. (6) Validated Fix + Full Re-Review loop on any finding. (7) Emit the SRE Review Results report — file:line evidence per score and per gate item. Execute in order; NEVER skip/merge a step — why: untracked steps get silently merged and gaps reach production.
• Score 12 criteria 0-2 across four dimensions (Observability/8, Reliability/8, Data Integrity/4, DB Performance/4) for a /24 PASS (19-24) / NEEDS WORK (13-18) / NOT READY (0-12) verdict — every score needs file:line evidence or it is 0.
• The DB Performance Protocol is MANDATORY and non-advisory: ALL list queries must paginate (no unbounded GetAll/ToList) and ALL filter fields, foreign keys, and sort columns must have matching indexes.
• VERDICT is advisory only; the graph gate, validated-fix full re-review, and DB Performance Protocol are NEVER skippable regardless of change size — and when batched (≥10 files), re-score all 12 criteria holistically from combined cross-batch evidence, never by averaging per-batch scores.
• After applying any fix, validate findings first, then rerun the FULL review (fresh sub-agent with zero prior-round memory); a clean pass ENDS the loop.

When to use: After implementing backend service or API changes, before committing. Frontend-only changes exempt.

Why: Working code that can't be debugged, monitored, or rolled back is technical debt in disguise.

Deployment context: Read docs/project-config.json → infrastructure section:

• containerization → check Dockerfiles, docker-compose
• orchestration → check K8s manifests, Helm charts
• cicd.tool → check pipeline configs

Your Mission

Review Mindset (NON-NEGOTIABLE)

Be skeptical. Every claim needs traced proof, confidence >80%.

• NEVER accept operational readiness at face value — verify by reading implementations
• Every score MUST have file:line evidence — unprovable score = 0
• Question: "Is this really handled?" → trace error/retry/timeout path to confirm
• Challenge: "Are ALL failure modes covered?" → check behavior when dependencies fail
• Verify: "Can we debug this in production?" → check logging, correlation, metrics

Scope Resolution

1. Arguments specify files/directories → review those
2. Else → review uncommitted changes (git diff --name-only)
3. Focus: backend source files under service root (per the project's structure reference / docs/project-config.json), API controllers, service classes
4. Skip: frontend files, test files, documentation, config-only changes

Production Readiness Scoring

Score each criterion 0-2: 0 = not addressed, 1 = partially, 2 = fully.

MANDATORY when batched (≥10 files, SYNC:systematic-review-batching active): score the 12 criteria holistically across the FULL cross-batch scope, NOT by merging or averaging per-batch scores. Several criteria are cross-file — e.g. "all query filter fields have indexes" can have the query in one batch, the migration in another; a per-batch score sees only its ≤8 files and false-flags 0 when the satisfying file lives in a different batch. The synthesis/reduce tier MUST therefore RE-SCORE each of the 12 criteria from combined cross-batch evidence (batch agents surface evidence per criterion; reducer assigns the score). If holistic re-score is infeasible, do NOT batch production-readiness-review — fall back to whole-scope serial scoring.

Observability (max 8)

Think: If this service errors at 3am, can on-call engineer diagnose root cause from logs alone — without reproducing?

Reliability (max 8)

Think: If the downstream dependency is down or slow, does this service degrade gracefully or cascade-fail?

Data Integrity (max 4)

Think: If database wiped and reseeded from scratch, does system still reach a valid state?

Decision test: "If the database is reset, does this data still need to exist?" Yes → must be in seeder. No → migration acceptable.

Database Performance (max 4)

Think: At 10x current data volume, do these queries still complete in <1s?

Database Performance Protocol (MANDATORY):

1. Paging Required — ALL list/collection queries use pagination. NEVER load all records into memory. Verify: no unbounded GetAll(), ToList(), or Find() without Skip/Take or cursor-based paging.
2. Index Required — ALL query filter fields, foreign keys, and sort columns have database indexes configured. Verify: entity expressions match index field order, database collections have index management methods, migrations include indexes for WHERE/JOIN/ORDER BY columns.

Spec-Loop Discipline for changed core logic (MANDATORY — gates the verdict, not a scored criterion):

1. Mutation bar, not coverage % — for changed service/API core logic the bar is the MUTATION-SCORE gate: a surviving mutant on a changed line is a release blocker (it proves an invariant the tests do not assert), NEVER a line-coverage-% question. A green coverage number over un-asserted behavior does not clear this gate.
2. Dual feedback — every production-readiness finding that changes behavior feeds BOTH the spec (NAME the contract/invariant in Section 8) AND a guarding test; a code-only fix is INCOMPLETE. A surviving mutant → add the killing test AND record the invariant it protects in the spec.

Extended SRE Readiness Gate (step-by-step, pass/fail — gating, NOT scored)

Runs as main step 3, after scoring, before verdict mapping. Deploy-time and operate-time SRE aspects the 12-criteria /24 model does NOT score. Check each item step by step; record pass / partial / fail with file:line evidence or explicit N/A — reason. Gate does not change /24 math — it overlays it: an unaccepted CRITICAL/HIGH fail blocks a PASS verdict regardless of score (per Severity Rubric — CRITICAL/HIGH must be resolved or owner-accepted before PASS). Read deployment context from docs/project-config.json → infrastructure (referenced above) to decide which items are N/A (e.g. no orchestration → readiness/liveness probes N/A with stated reason).

Gate verdict: {n}/8 pass. Any CRITICAL/HIGH fail not explicitly owner-accepted ⇒ overall verdict cannot be PASS even at a 19-24 score.

Technique Applicability (advisory — NON-SCORING, NON-GATING)

Invoke SYNC:scale-technique-gate: derive the system's scale tier from evidence (users/RPS, SLO, data volume, tenancy, topology — cite file:line/config/infra + confidence), then emit the Technique Applicability Matrix (technique | tier-warranted? | present? | verdict | advice | evidence) across the 10 concern groups. Surface warranted-but-missing reliability/scale techniques (rate limiting, backups, DR, failover, graceful degradation) as advice; flag OVER-ENGINEERED techniques the tier does not warrant.

Advisory only — this matrix does NOT add a gate item, does NOT change the {n}/8 gate result, the /24 score, or the verdict. A MISSING-WARRANTED technique is guidance to consider at this tier, NOT a gate fail. N/A-by-scale for small systems is expected, never a failure. Full catalog → .claude/docs/scale-technique-catalog.md.

Scoring

Run python .claude/scripts/code_graph connections <file> --json on service boundary files for cross-service impact.

Structural Impact Analysis (MANDATORY when graph.db exists)

• python .claude/scripts/code_graph graph-blast-radius --json → blast radius >20 nodes = high-risk deployment
• python .claude/scripts/code_graph query tests_for <function_name> --json → verify test coverage on changed functions
• python .claude/scripts/code_graph trace <service-file> --direction downstream --json → verify all downstream event handlers, bus consumers, cross-service calls have error handling

Why-Review Findings Validation Gate (MANDATORY when findings exist)

Purpose: Adversarial validation of own findings BEFORE any fix. Catches over-flagged criteria, false positives, and severity/score inflation at the source rather than letting them drive fixes or ship downstream.

Trigger: Any finding produced (any severity). Skip ONLY when the verdict is unconditional PASS with literally zero findings.

Protocol:

1. Read own finalized report from plans/reports/{skill}-{date}-{slug}.md
2. Invoke /why-review --validate-findings plans/reports/{skill}-{date}-{slug}.md — verify each finding has file:line proof, steel-man each rejected interpretation, and stress-test every severity/score classification (each finding must clear why-review's finding-survival bar to be kept)
3. Read the CLEAN / HAS-ISSUES verdict returned by why-review
4. If why-review demotes/removes any finding: UPDATE own 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 a ## Why-Review Validation line stating "All N findings re-validated against actual code; no severity changes."

Skip conditions (record explicit reason if skipping): unconditional PASS with zero findings; why-review is itself the active context (avoid recursion).

Why this exists: SRE sub-agent reports inherit confirmation bias — the orchestrator absorbs severity claims as ground truth. Validate findings BEFORE the fix so no fix is ever driven by an inflated or false finding; this gate feeds the "Validated Fix + Full Re-Review" loop below.

Validated Fix + Full Re-Review (MANDATORY when fixes are applied)

When a review pass finds issues, validate findings before any fix. Do NOT spawn a fresh sub-agent only to re-review the same finding set before validation/fix. After validated SRE fixes applied, rerun the full SRE review. If that restarted review uses a sub-agent, spawn it with ZERO prior-round memory. A clean review pass ENDS the review.

When a fresh sub-agent is part of the restarted review, spawn via canonical template in SYNC:review-protocol-injection:

1. subagent_type: code-reviewer
2. Task: "SRE production readiness review after validated fixes — score all 12 criteria (0-2) for {files reviewed in the current full scope}"
3. Review mode: "Fresh full re-review after validated fixes. Zero memory of prior rounds. Re-read ALL target files from scratch."
4. Reference Docs: docs/project-reference/code-review-rules.md
5. Target Files: same files from Scope Resolution
6. Integrate sub-agent report findings — DO NOT filter or override

Fresh re-review focus (what prior rounds typically miss):

• Operational concerns spanning multiple services
• Subtle reliability gaps (retry, circuit breakers, timeout handling)
• Missing observability (structured logging, correlation IDs, metrics)
• Data-integrity edge cases under concurrent load

Final verdict = every review pass that actually ran, combined.

Output Format

## SRE Review Results

**Scope:** {files reviewed}
**Date:** {date}
**Score:** {X}/24
**Verdict:** PASS / NEEDS WORK / NOT READY

### Observability ({X}/8)

| #   | Criterion          | Score | Evidence                   |
| --- | ------------------ | ----- | -------------------------- |
| 1   | Structured Logging | 0/1/2 | {file:line or "not found"} |
| 2   | Error Context      | 0/1/2 | ...                        |
| 3   | Metrics Awareness  | 0/1/2 | ...                        |
| 4   | Correlation        | 0/1/2 | ...                        |

### Reliability ({X}/8)

| #   | Criterion         | Score | Evidence |
| --- | ----------------- | ----- | -------- |
| 5   | Retry Strategy    | 0/1/2 | ...      |
| 6   | Timeout Config    | 0/1/2 | ...      |
| 7   | Error Handling    | 0/1/2 | ...      |
| 8   | Fallback Behavior | 0/1/2 | ...      |

### Data Integrity ({X}/4)

| #   | Criterion          | Score | Evidence |
| --- | ------------------ | ----- | -------- |
| 9   | Seed vs Migration  | 0/1/2 | ...      |
| 10  | Seeder Idempotency | 0/1/2 | ...      |

### Database Performance ({X}/4)

| #   | Criterion        | Score | Evidence |
| --- | ---------------- | ----- | -------- |
| 11  | Pagination       | 0/1/2 | ...      |
| 12  | Database Indexes | 0/1/2 | ...      |

### Extended SRE Readiness ({n}/8 gate — pass/fail, does not change /24)

| #   | Gate Item                  | Status            | Evidence          |
| --- | -------------------------- | ----------------- | ----------------- |
| G1  | Rollout & Rollback         | pass/partial/fail | `file:line` / N/A |
| G2  | Health Checks              | pass/partial/fail | ...               |
| G3  | Alerting & Runbook         | pass/partial/fail | ...               |
| G4  | SLO / Error-Budget         | pass/partial/fail | ...               |
| G5  | Capacity & Resource Limits | pass/partial/fail | ...               |
| G6  | Config & Secrets           | pass/partial/fail | ...               |
| G7  | Graceful Shutdown/Startup  | pass/partial/fail | ...               |
| G8  | Concurrency & Idempotency  | pass/partial/fail | ...               |

_Any unaccepted CRITICAL/HIGH `fail` above blocks a PASS verdict regardless of the /24 score._

### Gaps to Address

- {specific actionable item}

### Recommendation

{Proceed / Address gaps first}

Important Notes

• Advisory (final VERDICT only) — score/verdict inform team but don't block commits; MANDATORY process steps (graph gate, validated-fix full re-review, Database Performance Protocol) are NEVER advisory
• Evidence-based — cite file:line for every score; unprovable score = 0
• Proportional — small bug fixes need less rigor than new endpoints (applies to VERDICT interpretation, NOT to skipping MANDATORY steps)
• Extended SRE Readiness gate is pass/fail, NOT scored — does not change /24 math; but an unaccepted CRITICAL/HIGH gate fail blocks a PASS verdict (Severity Rubric). Use docs/project-config.json → infrastructure to mark items N/A with stated reason
• Check framework patterns — background-job base handlers, base-controller error handling

Workflow Recommendation

MANDATORY — NO EXCEPTIONS: If NOT already in workflow, use AskUserQuestion to ask user:

1. Activate workflow-feature workflow (Recommended) — scout → investigate → plan → feature-implement → review → production-readiness-review → test → docs
2. Execute /production-readiness-review directly — run standalone

Next Steps

MANDATORY — NO EXCEPTIONS — after completing, use AskUserQuestion:

• "/watzup (Recommended)" — wrap up + check doc staleness
• "/test" — run tests before wrapping up
• "Skip, continue manually" — user decides

Combined audit: For a whole-project architecture + compliance + production-readiness audit in one pass, run /architecture-review-full (or /start-workflow workflow-architecture-audit) — fans out this skill, architecture-review, architecture-scalability-review as parallel sub-agents and synthesizes one consolidated report.

[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting. For simple tasks, AI MUST ask user whether to skip.

• docs/project-reference/domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)

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

External Memory: Complex/lengthy work → write intermediate findings + final results to plans/reports/ — prevents context loss, serves as deliverable.

Evidence Gate: MANDATORY — every claim, finding, recommendation requires file:line proof or traced evidence with confidence percentage (>80% to act, <80% verify first).

Graph-Assisted Investigation — MANDATORY when .code-graph/graph.db exists.

HARD-GATE: MUST ATTENTION run at least ONE graph command on key files before concluding any investigation.

Pattern: Grep finds files → trace --direction both reveals full system flow → Grep verifies details

Task	Minimum Graph Action
Investigation/Scout	trace --direction both on 2-3 entry files
Fix/Debug	callers_of on buggy function + tests_for
Feature/Enhancement	connections on files to be modified
Code Review	tests_for on changed functions
Blast Radius	trace --direction downstream

CLI: python .claude/scripts/code_graph {command} --json. Use --node-mode file first (10-30x less noise), then --node-mode function for detail.

Sub-Agent Return Contract — When this skill spawns a sub-agent, the sub-agent MUST return ONLY this structure. Main agent reads only this summary — NEVER requests full sub-agent output inline.

## Sub-Agent Result: [skill-name]

Status: ✅ PASS | ⚠️ PARTIAL | ❌ FAIL
Confidence: [0-100]%

### Findings (Critical/High only — max 10 bullets)

- [severity] [file:line] [finding]

### Actions Taken

- [file changed] [what changed]

### Blockers (if any)

- [blocker description]

Full report: plans/reports/[skill-name]-[date]-[slug].md

Main agent reads Full report file ONLY when: (a) resolving a specific blocker, or (b) building a fix plan. Sub-agent writes full report incrementally (per SYNC:incremental-persistence) — not held in memory.

Context budget — the return payload is a SUMMARY, not a transcript: ≤10 finding bullets, no raw file contents / full diffs / verbatim logs inline, no re-pasted source. Everything beyond the summary lives in the Full report on disk. A sub-agent that would exceed the summary shape MUST write the detail to its report and return only the pointer — the orchestrator's context is the scarce resource the whole map-reduce protects.

Nested Task Expansion Contract — For workflow-step invocation, the [Workflow] ... row is only a parent container; the child skill still creates visible phase tasks.

1. Call TaskList first. If a matching active parent workflow row exists, set nested=true and record parentTaskId; otherwise run standalone.
2. Create one task per declared phase before phase work. When nested, prefix subjects [N.M] $skill-name — phase.
3. When nested, link the parent with TaskUpdate(parentTaskId, addBlockedBy: [childIds]).
4. Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent.
5. Mark exactly one child in_progress before work and completed immediately after evidence is written.
6. Complete the parent only after all child tasks are completed or explicitly cancelled with reason.

Blocked until: TaskList done, child phases created, parent linked when nested, first child marked in_progress.

Project Reference Docs Gate — Run after task-tracking bootstrap and before target/source file reads, grep, edits, or analysis. Project docs override generic framework assumptions.

1. Identify scope: file types, domain area, and operation.
2. Read docs/project-config.json first — the project's machine-readable map. It is the single source of truth for THIS repo (modules/paths, framework + search keywords, test/E2E/integration run-commands, design system, architecture rules, workflow patterns); ground exact paths, run-commands, and conventions on it before investigating, planning, or coding — never assume framework defaults (CLAUDE.md + reference docs are derived from it). If it — or the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any required reference doc — is missing or stale, auto-run /project-init or the narrow route (/project-config, /docs-init, /scan-all, /scan --target=<key>, /claude-md-init) first; if Codex mirrors or AGENTS.md are stale, ask the user to run /sync-codex (never auto-run it).
3. Required docs by trigger: always docs/project-reference/lessons.md; doc lookup docs-index-reference.md; review code-review-rules.md; backend/CQRS/API backend-patterns-reference.md; domain/entity domain-entities-reference.md; frontend/UI frontend-patterns-reference.md; styles/design scss-styling-guide.md + design-system/design-system-canonical.md; integration tests integration-test-reference.md; E2E e2e-test-reference.md; feature docs/specs feature-spec-reference.md + spec-system-reference.md + spec-principles.md; behavior/public-contract/spec-test-code sync workflow-spec-test-code-cycle-reference.md; derived spec index/ERD/reimplementation guides spec-system-reference.md + source Feature Specs under docs/specs/; architecture/new area project-structure-reference.md.
4. Read every required doc, then before target work state: Reference docs read: ... | Not applicable: ....

Ready when: scope evaluated, docs/project-config.json consulted, required docs checked/read or setup route completed, lessons.md confirmed, citation emitted.

Task Tracking & External Report Persistence — Bootstrap this before execution; then run project-reference doc prefetch before target/source work.

1. Create a small task breakdown before target file reads, grep, edits, or analysis. On context loss, inspect the current task list first.
2. Mark one task in_progress before work and completed immediately after evidence; never batch transitions.
3. For plan/review work, create plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md before first finding.
4. Append findings after each file/section/decision and synthesize from the report file at the end.
5. Final output cites Full report: plans/reports/{filename}.

Blocked until: task breakdown exists, report path declared for plan/review work, first finding persisted before the next finding.

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

Evidence-Based Reasoning — Speculation is FORBIDDEN. Every claim needs proof.

1. Cite file:line, grep results, or framework docs for EVERY claim
2. Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend
3. Cross-service validation required for architectural changes
4. "I don't have enough evidence" is valid and expected output

BLOCKED until: - [ ] Evidence file path (file:line) - [ ] Grep search performed - [ ] 3+ similar patterns found - [ ] Confidence level stated

Forbidden without proof: "obviously", "I think", "should be", "probably", "this is because" If incomplete → output: "Insufficient evidence. Verified: [...]. Not verified: [...]."

Validated-Finding Fix + Full Re-Review Loop — Re-review is triggered by a validated finding fix cycle, not by a round number. Review purpose: review → validate findings → fix validated findings → full re-review until a complete review pass clears the round's exit bar (see Severity floor below). A clean review ENDS the loop — no further rounds required.

aka Self-Review Convergence Loop. The name is historical — there is NO 2-round cap; "double-round-trip" only means a validated-finding fix cycle forces at least one fresh re-review. It runs until a clean pass, bounded by the 3-round ceiling below.

Round cap — 3 rounds MAX (a ceiling, NEVER a target). A clean pass ENDS the loop immediately at ANY round — round 1 included; the cap never obliges you to keep spinning. Hitting round 3 with blocking findings still open (severity floor applied) → STOP and escalate via AskUserQuestion with the still-open findings listed; NEVER emit a silent "good enough" PASS on cap exhaustion, and NEVER let the cap substitute for the clean-review requirement. The 2-repeated-no-progress blocker rule stays an EARLIER exit — escalate at whichever trips first.

Severity floor — from round 3, LOW stops blocking. The exit bar tightens by round, so the loop converges on consequence instead of spinning on polish:

Define one predicate everywhere: blocking_findings(round, findings) returns all validated findings in rounds 1–2 and only validated CRITICAL/HIGH/MEDIUM findings in round 3+. A binary gate (test-green, security must-fix, required artifact) is exempt only when its owning invariant explicitly says so.

Round	Exit bar — loop ENDS when the fresh full review has…	Must be fixed to continue
1-2	zero validated findings at ANY severity	CRITICAL · HIGH · MEDIUM · LOW
3+	zero validated CRITICAL / HIGH / MEDIUM findings — LOW-only is a PASS	CRITICAL · HIGH · MEDIUM only

From round 3 onward LOW findings are NOT required to be fixed: a round whose validated findings are ALL LOW ENDS the loop immediately — do not open another round for them. Severity tiers are SYNC:severity-rubric (CRITICAL block-merge · HIGH must-fix · MEDIUM should-fix · LOW nice-to-fix); rounds 1-2 are unchanged, so an easy LOW still gets fixed early when it is cheap.

Severity-floor rules:

• Never silently drop a deferred LOW. Every unfixed LOW is listed in the final report under ## Deferred LOW Findings (severity floor, round ≥3) with file, line, and description, so the owner can schedule it. Dropping it from the report is a protocol violation, not a clean pass.
• Never re-tier a finding to trigger the exit. Downgrading a real CRITICAL/HIGH/MEDIUM to LOW so the loop can end is a FALSE PASS. Severity is set by consequence per SYNC:severity-rubric before the round bar is applied — never after, and never with the exit in view. — why: a floor that can be reached by relabeling is not a floor.
• The floor bounds the loop, not the standard. It ends iteration; it never authorizes shipping a known CRITICAL/HIGH/MEDIUM, and it never lowers the finding-survival bar that admits a finding in the first place.
• The floor never applies to a hard gate. Test-green gates (a suite must actually pass), security must-fix gates, and any gate whose criterion is binary rather than severity-rated are unaffected — a failing test is a failure, not a LOW finding.

Universal scope (any new output/judgment): any newly produced output or judgment gets ≥1 self-review; any new judgment gets ≥1 /why-review --validate-findings pass; anything flagged to re-check is re-checked ≥1 time — before that output is treated as final. This loop is the default convergence contract for ANY work-producing skill, not review skills only.

Routing invariant (author-facing): a skill that validates findings MUST route them through /why-review --validate-findings (the terminal validator) — NEVER fork an inline finding-validation. Routing through why-review is what makes the finding-survival bar and this loop apply; the verify-review-validate-coverage sensor enforces this exact route mechanically.

Round 1: Main-session review. Read target files, build understanding, note issues. Output findings + verdict (PASS / FAIL).

Decision after Round 1:

• No issues found (PASS, zero findings) → review ENDS. Do NOT spawn a fresh sub-agent for confirmation.
• blocking_findings(round, findings) is non-empty → run the active review skill's findings-validation gate first; for review skills the default gate is /why-review --validate-findings <report-path>. Fix only validated findings, then restart the full review protocol from the beginning with a fresh task breakdown.

Fresh full re-review after every fix cycle: Re-run the whole review protocol over the current full target. When sub-agents are part of that protocol, spawn NEW Agent calls — never reuse prior agents. Reviewers re-read ALL files from scratch with ZERO memory of prior rounds. See SYNC:fresh-context-review for the spawn mechanism and SYNC:review-protocol-injection for the canonical Agent prompt template. Each fresh full review must catch:

• Cross-cutting concerns missed in the prior round
• Interaction bugs between changed files
• Convention drift (new code vs existing patterns)
• Missing pieces that should exist but don't
• Subtle edge cases the prior round rationalized away
• Regressions introduced by the fixes themselves

Loop termination: After each full re-review, repeat the same decision against that round's exit bar: bar cleared → END; blocking findings remain → validate findings → fix → restart from the first review phase. Rounds 1-2 clear on zero findings at any severity; from round 3 the bar is zero CRITICAL/HIGH/MEDIUM, so a LOW-only round ENDS the loop (deferred LOWs go in the report). Capped at 3 rounds. Escalate via AskUserQuestion at whichever comes first: the same validated finding repeats for 2 full invocations with no progress · a fix requires product/owner input · round 3 completes with CRITICAL/HIGH/MEDIUM still open. NEVER loop past 3 rounds, and NEVER convert cap exhaustion into a PASS.

Rules:

• A clean Round 1 ENDS the review — no mandatory Round 2
• From round 3 on, a round whose validated findings are ALL LOW ENDS the loop — never open round N+1 to fix LOW alone; list those LOWs as deferred instead
• NEVER re-tier a CRITICAL/HIGH/MEDIUM down to LOW to reach the round-3 exit — severity is assigned by consequence before the bar is applied
• NEVER fix unvalidated findings; validate first using the caller's validation gate
• Every surviving finding must additionally clear the finding-survival bar defined in why-review's Findings Validation Routine (a deliberately higher bar than the generic act-gate — "keep this finding?" is a stricter question than "act on this evidence?"); a finding below the bar is demoted or dropped, not kept
• NEVER skip the full re-review after a fix cycle (every fix invalidates the prior verdict)
• NEVER reuse a sub-agent across rounds — every iteration that uses sub-agents spawns NEW Agent calls
• Main agent READS sub-agent reports but MUST NOT filter, reinterpret, or override findings
• The 3-round cap NEVER replaces the clean-review requirement — it bounds runaway looping, it does not authorize shipping an un-clean review; a clean pass ends the loop early at any round, and cap exhaustion escalates rather than passes
• Enforce the round cap of 3 alongside the 2 repeated-no-progress blocker rule; both are escalation triggers, neither is a completion criterion
• Track recursive invocation count and repeated blockers in conversation context (session-scoped)
• Final verdict must incorporate ALL rounds executed

Report must include ## Round N Findings (Fresh Sub-Agent) for every round N≥2 that was executed, plus ## Deferred LOW Findings (severity floor, round ≥3) whenever the loop ended on the round-3+ bar with LOWs still open.

Fresh Context Re-Review — Eliminate orchestrator confirmation bias after fixes by r

…(truncated)