# Knowledge Review > [Research] Use when you need to review knowledge artifacts for completeness, citation quality, confidence accuracy, and template compliance. - Skill: `duc01226/knowledge-review-2` (Agent Skill) - Install (CLI): `npx skillmds@latest add duc01226/knowledge-review-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/knowledge-review-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/duc01226/knowledge-review-2 --- ## Quick Summary **Goal:** Ensure knowledge artifacts are evidence-backed, complete, protocol-compliant, and safe to use for decisions — reviewing for quality, completeness, citation accuracy, and template compliance. **Summary:** - PURPOSE: READ-ONLY audit of a knowledge artifact (research report / course / strategy) for completeness, citation accuracy, confidence calibration, source quality, and template compliance — output is a verdict, NEVER an edit. - MAIN STEPS in order: (1) read the artifact → (2) run the 7-checklist audit — template compliance · citation audit · confidence accuracy · source quality · knowledge gaps · cross-validation · actionability, verifying presence AND quality depth (never just that a section exists) → (3) run the adversarial Anti-Bias Gate → (4) emit PASS/WARN/FAIL per-check + verdict (APPROVED/REVISE/BLOCKED) → (5) conditional Round 2 focused re-review. - Default to SKEPTIC: run the Anti-Bias Gate before any verdict — find a contradicting source per major claim, stress-test every score ≥80%, state the strongest alternative conclusion, check supporting-vs-contradicting source ratio, run a pre-mortem, and argue the opposite verdict in 2+ sentences. - Calibrate confidence to evidence: a single source ≠ 80%, scores >80% need 2+ independent sources with contradicting evidence addressed, single-source claims marked unverified must be <60%, and findings <60% must be flagged prominently. - Convergence: a clean Round 1 ENDS the review; any finding triggers validate → fix → full re-review until zero issues. **Workflow:** 1. **Read artifact** — Load the knowledge report/course/strategy 2. **Template compliance** — Verify all enforced sections present 3. **Citation audit** — Check inline citations and source table 4. **Confidence check** — Verify scores match evidence 5. **Output review** — Summary with pass/warn/fail per check **Key Rules:** - Every section from template must be present and non-empty - Every factual claim must have inline citation - Confidence scores must match evidence basis - READ-ONLY — do not modify the artifact **Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).** ## First Principle — Easy to Change > **Success metric of every coding decision: _future change cost_.** > DRY, SRP, abstraction, design patterns, naming, layering, tests — every technique serves one goal: **making next change cheaper**. When evaluating code, refactor, test, or abstraction, ask: **does this make next change cheaper or more expensive?** - Reject "best practices" raising change cost (premature abstraction, speculative generality, leaky indirection, ceremony without payoff). - Name real enemies in findings: **coupling, hidden state, duplicated knowledge, unclear intent, irreversible decisions exposed too early**. - Simpler design that is easy to change beats sophisticated design that isn't. Apply this lens **before** invoking any specific rule, pattern, or checklist below — if downstream rule would raise change cost, this principle wins. --- ## Adversarial Review Mindset (NON-NEGOTIABLE) **Default stance: SKEPTIC challenging research quality, NOT confirming research completeness.** > **Source confirmation bias trap:** AI gravitates toward sources confirming its working hypothesis. Knowledge artifact built iteratively — by completion, framing is locked in. This section forces challenge of both sources AND framing. ### Adversarial Techniques (apply ALL before concluding) **1. Source Bias Detection** Top 3 claims: "What sources CONTRADICT this claim?" No contradicting source cited → either reviewer didn't look, or evidence truly one-sided. Ask: "What would skeptic of this conclusion cite?" No counterevidence addressed → confidence score inflated. **2. Confidence Calibration Challenge** Each confidence score ≥ 80%: "What would need to be true for this confidence to be wrong?" High confidence warranted ONLY when: (a) multiple independent sources agree, (b) contradicting evidence addressed, (c) methodology sound. Challenge any score resting on single source or undisclosed assumptions. **3. Alternative Conclusion Check** Given same evidence, what DIFFERENT conclusion could reasonable expert reach? Artifact not addressing 1+ credible alternative interpretation → analysis incomplete. State strongest alternative conclusion. **4. Cherry-Picking Detection** Count sources supporting main conclusion vs. sources challenging it. Ratio > 3:1 favoring supporting sources without explicit explanation of why contradicting sources discounted → flag cherry-picking. **5. Pre-Mortem** Assume artifact's recommendation implemented and fails. Write most plausible failure scenario given research limitations. Artifact not acknowledging this failure mode → missing a risk section. **6. Contrarian Pass** Before writing any verdict, generate 2+ sentences arguing OPPOSITE conclusion about artifact's quality. Then decide which argument is stronger. ### Forbidden Patterns - **"Sources are cited"** → Presence of citations ≠ quality. Do they actually support the claim? - **"Confidence scores look reasonable"** → What would LOWER the confidence score? Name it. - **"Comprehensive coverage"** → What perspective is MISSING from this research? - **"Recommendations are actionable"** → On what evidence? What's the confidence of the evidence chain? - **Approving a knowledge artifact without challenging the evidence quality** → Forbidden. ### Anti-Bias Gate (MANDATORY before finalizing verdict) (MUST ATTENTION) - found 1+ contradicting source per major claim (or flagged its absence) - challenged 1+ confidence score ≥ 80% with a stress test - stated strongest alternative conclusion from same evidence - checked source balance (supporting vs. contradicting ratio) - ran pre-mortem on main recommendation - generated 2+ sentences arguing opposite verdict Any item unmet → adversarial review incomplete. Go back. — why: skipping the gate ships confirmation-biased verdicts as fact. # Knowledge Review ## Review Checklist ### 1. Template Compliance | # | Check | Presence | Quality Depth | | --- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | **All enforced sections present** — every required section from the template exists in the artifact | Are ALL required sections present (not just most)? Is any section empty vs. placeholder? | Does each section contain substantive content, or is it a heading with nothing beneath it? A partially-filled section is as dangerous as a missing one. | | 2 | **No sections are empty placeholders** — section bodies contain real content, not "TBD" or "to be filled" | Are section bodies substantive or just "TBD / to be filled"? | Is the content specific to this artifact, or generic filler? A section that says "risks will be identified later" has negative value — it creates false confidence. | | 3 | **Section order matches template** — sections appear in prescribed sequence | Do sections appear in the prescribed order? | Does reordering break any cross-references between sections? If section 3 references section 2, out-of-order placement creates reading confusion. | ### 2. Citation Audit | # | Check | Presence | Quality Depth | | --- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | **Every factual claim has inline citation `[N]`** — all assertions are backed by a numbered source reference | Are ALL claims cited, or only the obvious ones? Uncited claims are assertions, not findings. | Do the cited sources actually say what the text claims? A source cited for a paraphrase is different from a source cited for a direct claim. | | 2 | **Every source in Sources table is referenced in text** — no source appears in the table without a corresponding `[N]` reference | Are all table sources referenced in the text body? Orphan sources = sources added for credibility, not used for evidence. | Are sources cited at the most specific claim they support, or cited vaguely at section level? Section-level citation hides which sub-claims are actually supported. | | 3 | **No orphan citations** — every `[N]` reference in the text matches a Sources table row | Are there `[N]` references that don't match any Sources table row? | Are citation numbers consistent throughout (no gaps, no duplicates)? Broken citation numbering signals the artifact was edited without maintaining integrity. | | 4 | **Sources table has: Title, URL, Author, Date, Tier** — all five fields present for every source | Are ALL 5 fields filled? Is Tier assigned (not just blank)? | Are the Tier assignments accurate? A blog post assigned Tier 1 inflates perceived source quality. Is the Date current enough for the topic? | ### 3. Confidence Accuracy | # | Check | Presence | Quality Depth | | --- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | **Per-finding confidence scores declared** — each finding has its own explicit confidence percentage | Does EACH finding have its own score, or is one artifact-level score applied everywhere? | Are scores at the finding level, not the section level? A single score per section hides that some findings within it may be poorly supported. | | 2 | **Overall confidence declared** — an aggregate confidence score for the artifact is stated | Is the overall score present and explicitly stated? | Is the overall score a reasoned aggregate, or just the highest per-finding score? An average of 85%, 60%, and 40% is NOT 85%. | | 3 | **Scores match evidence basis (not inflated)** — confidence percentages are calibrated to actual source count and quality | Is each score justified by the number and quality of independent sources? A single source ≠ 80%. | What would LOWER this confidence score? If no answer exists, the score is likely inflated. Are scores above 80% supported by 2+ independent sources with contradicting evidence addressed? | | 4 | **Findings <60% flagged prominently** — low-confidence findings are visually distinct from high-confidence ones | Are low-confidence findings visually distinct (e.g., ⚠️ prefix), not buried in body text? | Are low-confidence findings positioned to prevent downstream misuse? A low-confidence finding mentioned once in passing will be treated as fact by readers who skim. | ### 4. Source Quality | # | Check | Presence | Quality Depth | | --- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | **Tier distribution appropriate (not all Tier 4)** — source tiers are spread across quality levels | Is the Tier distribution recorded? Are Tier 4 sources a minority? | Does Tier distribution match the claim importance? A Tier 4 source for a core claim is a risk regardless of how many Tier 1 sources exist elsewhere. | | 2 | **At least 50% Tier 1-2 sources for key claims** — high-stakes conclusions rest on authoritative sources | Do key claims cite Tier 1-2 sources? Is the 50% threshold met overall? | Are the Tier 1-2 sources actually authoritative for THIS specific claim domain, or just prestigious in a different domain? Domain mismatch inflates perceived authority. | | 3 | **Recency appropriate for topic type** — sources are current relative to how fast the topic evolves | Are sources dated? Is recency assessed for each source? | Is "recency" calibrated to the topic's rate of change? A 2019 source on cloud pricing is stale; a 2019 source on database theory may be fine. Are any outdated sources flagged? | ### 5. Knowledge Gaps | # | Check | Presence | Quality Depth | | --- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | **Gaps section is present and honest** — a dedicated section describes what the research did NOT find | Is a Gaps section present? Does it list specific gaps, not just "more research needed"? | Are the gaps specific enough to guide follow-up research? "Unknown pricing" is actionable; "some uncertainty exists" is not. Are gaps ranked by impact on the artifact's conclusions? | | 2 | **Known limitations declared** — methodological or coverage limitations are explicitly stated | Are limitations listed (not inferred)? Does the section distinguish limitations from gaps? | Are limitations acknowledged BEFORE they are used to discount findings, or only in a footnote after conclusions are stated? A limitation that invalidates a key finding must appear near that finding, not only in the Gaps section. | | 3 | **Suggestions for further research included** — the artifact proposes next steps to close identified gaps | Are 1+ follow-up research suggestions present? Are they tied to specific gaps? | Are suggestions actionable (specific query + source type) or vague ("investigate further")? Do suggestions address the gaps that most affect decision-making? | ### 6. Cross-Validation | # | Check | Presence | Quality Depth | | --- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | **Key claims verified by 2+ sources** — core conclusions are supported by multiple independent sources | Are 2+ sources cited for each key claim? | Are the sources truly independent, or do they cite each other (amplification, not validation)? Two sources from the same original study do not constitute cross-validation. | | 2 | **Discrepancies noted where sources conflict** — when sources contradict each other, the conflict is documented | Are source conflicts recorded in the artifact? | Are conflicts resolved or just noted? If sources conflict, the artifact should explain which source was weighted more and why — not just acknowledge the conflict exists. | | 3 | **Single-source claims marked as unverified** — any finding backed by only one source is explicitly labeled | Are single-source claims identified with an "unverified" marker or equivalent? | Are single-source claims given confidence scores below 60% as required? A single source labeled "unverified" but assigned 75% confidence is self-contradictory. | ### 7. Actionability | # | Check | Presence | Quality Depth | | --- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | **Recommendations are concrete (not vague)** — each recommendation specifies who should do what | Are recommendations present? Do they name an action (not just "consider X")? | Are recommendations actionable enough to assign to a specific role without further clarification? "Improve monitoring" is not actionable; "add P99 latency alert at 500ms threshold" is. | | 2 | **Next steps are evidence-based** — proposed actions are traceable to findings in the artifact | Are next steps present and linked to specific findings? | Is each next step traceable to a specific finding and confidence score? A next step driven by a 40%-confidence finding should be labeled speculative, not presented as a directive. | | 3 | **Executive summary captures key findings** — the summary conveys findings accurately without omitting critical caveats | Is an executive summary present? Does it list key findings? | Does the summary preserve confidence caveats and limitations, or does it strip them out for readability? A summary that presents 60%-confidence findings as facts is worse than no summary. | ## Output Format ```markdown ## Knowledge Review Result **Status:** PASS | WARN | FAIL **Artifact:** {path} ### Checks (N/7 passed) - [x] Template compliance - [x] Citation audit - [ ] Confidence accuracy — {issue} - [ ] Source quality — {issue} ... ### Issues - {specific issues found} ### Verdict {APPROVED | REVISE | BLOCKED} ``` ## Round 2: Focused Re-Review (conditional — triggered by findings) Convergence follows the single contract in `SYNC:double-round-trip-review` below: **a clean Round 1 ENDS the review — there is no unconditional mandatory Round 2.** Re-review is triggered by a validated-finding fix cycle (`review → validate findings → fix → full re-review`), not by a round number. When Round 1 surfaces findings, run this focused re-review as part of that full re-review (do NOT rely on Round 1 memory): 1. **Re-read** the Round 1 verdict and checklist results 2. **Re-evaluate** ALL checklist items from scratch 3. **Challenge** Round 1 PASS items: "Is this really PASS? Did I verify citations and confidence?" 4. **Focus on** what Round 1 typically misses: - Citation accuracy (do sources actually say what's claimed?) - Confidence calibration (are percentages realistic?) - Knowledge gaps that weren't flagged - Template compliance shortcuts 5. **Update verdict** to incorporate the new findings; then re-enter the loop until a complete review pass finds zero issues. --- > **[IMPORTANT]** Use `TaskCreate` to break ALL work into small tasks BEFORE starting. **Prerequisites:** **MUST ATTENTION READ** before executing: > **OOP & DRY Enforcement:** MANDATORY — flag duplicated patterns that should be extracted to a base class, generic, or helper. Classes in the same group or suffix (ex *Entity, *Dto, \*Service, etc...) must inherit a common base (even if empty now — enables future shared logic and child overrides). Verify project has code linting/analyzer configured for the stack. > **AI Mistake Prevention** — Failure modes to avoid on every task: > > **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting. > **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. > **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. > **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done. > **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect. > **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard. > **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk. > **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure. > **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols. > **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 `. 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 restarting the full review with isolated sub-agents where applicable. > > **Why:** The main agent knows what it (or `/feature-implement`) just fixed and rationalizes findings accordingly. A fresh sub-agent has ZERO memory, re-reads from scratch, and catches what the main agent dismissed. Sub-agent bias is mitigated by (1) fresh context, (2) verbatim protocol injection, (3) main agent not filtering the report. > > **When:** ONLY after a validated-finding fix cycle. A review round that finds zero issues ENDS the loop — do NOT spawn a confirmation sub-agent. A review round that finds issues triggers: validate findings → fix → full review restart from the first phase. > > **How:** > > 1. Start a NEW full review invocation/task breakdown; when that protocol calls for agents, spawn NEW `Agent` tool calls — use `code-reviewer` subagent_type for code reviews, `general-purpose` for plan/doc/artifact reviews > 2. Inject ALL required review protocols VERBATIM into the prompt — see `SYNC:review-protocol-injection` for the full list and template. Never reference protocols by file path; AI compliance drops behind file-read indirection (see `SYNC:shared-protocol-duplication-policy`) > 3. Sub-agent re-reads ALL target files from scratch via its own tool calls — never pass file contents inline in the prompt > 4. Sub-agent writes structured report to `plans/reports/{review-type}-round{N}-{date}.md` > 5. Main agent reads the report, integrates findings into its own report, DOES NOT override or filter > > **Rules:** > > - SKIP fresh sub-agent when the prior full review found zero issues (no fixes = nothing new to verify) > - NEVER skip the full review restart after a fix cycle — every fix invalidates the prior verdict > - NEVER reuse a sub-agent across rounds — every fresh round spawns a NEW `Agent` call > - Continue until a complete full review pass clears that round's exit bar per `SYNC:double-round-trip-review`: **rounds 1-2** → zero findings at any severity; **round 3+** → zero CRITICAL/HIGH/MEDIUM, so a round whose validated findings are ALL LOW ENDS the loop (list those LOWs as deferred instead of spawning another round). If the same blocker repeats 3 times with no progress, escalate via `AskUserQuestion` > - Track iteration count and repeated blockers in conversation context (session-scoped, no persistent files) > **Review Protocol Injection** — Every fresh sub-agent review prompt MUST embed 11 protocol blocks VERBATIM. The template below has ALL 11 bodies already expanded inline. Copy the template wholesale into the Agent call's `prompt` field at runtime, replacing only the `{placeholders}` in Task / Round / Reference Docs / Target Files / Output sections with context-specific values. Do NOT touch the embedded protocol sections. > > **Why inline expansion:** Placeholder markers would force file-read indirection at runtime. AI compliance drops significantly behind indirection (see `SYNC:shared-protocol-duplication-policy`). Therefore the template carries all 11 protocol bodies pre-embedded. ### Subagent Type Selection - `code-reviewer` — for code reviews (reviewing source files, git diffs, implementation) - `general-purpose` — for plan / doc / artifact reviews (reviewing markdown plans, docs, specs) ### Canonical Agent Call Template (Copy Verbatim) ``` Agent({ description: "Fresh Round {N} review", subagent_type: "code-reviewer", prompt: ` ## Task {review-specific task — e.g., "Review all uncommitted changes for code quality" | "Review plan files under {plan-dir}" | "Review integration tests in {path}"} ## Round Round {N}. You have ZERO memory of prior rounds. Re-read all target files from scratch via your own tool calls. Do NOT trust anything from the main agent beyond this prompt. ## Protocols (follow VERBATIM — these are non-negotiable) ### Spec ↔ Tests ↔ Code Triangulation DO THIS FIRST — before any per-protocol check below. The review target is the WHOLE PACKAGE, not the diff alone: load the behavior's spec (§3 ACs / §4 BRs / §8 TCs), its tests, and the changed code TOGETHER, and reason about their mutual consistency BEFORE judging any one in isolation. 1. Locate all three faces: the Feature Spec section(s) governing the changed behavior, the tests that guard it, and the production code that implements it. A missing face is itself a finding (SPEC-GAP / TEST-GAP / DEAD-SPEC). 2. Triangulate pairwise — every disagreement is a finding; classify which face is wrong: - code vs spec: behavior the code does that no §3/§4/§8 rule describes → CODE-EXTRA or SPEC-STALE; a [HARD] §4 rule or §5 invariant with no enforcing code path → CODE-WRONG. - tests vs spec: a §8 TC with no test, or a test asserting behavior no TC/rule names → TEST-GAP or SPEC-SILENT. - tests vs code: a changed code path with no covering test → TEST-GAP; a test that still passes against a deliberately broken invariant → WEAK-TEST (apply the mutation thinking in Bug Detection). 3. Hidden-rule capture: any invariant the code enforces but the spec never states (SPEC-SILENT) MUST be surfaced as a finding to add into §3/§4/§8 AND guarded with a test — the enrichment loop, never a silent pass. 4. Only after the three faces agree — or every disagreement is logged as a finding — proceed to the per-protocol checks below; when enrichment adds spec/test content, re-review the package against the enriched spec. NEVER mark review PASS while any spec/test/code face disagrees without a logged finding. The diff is the entry point; the package is the unit of judgment. ### 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) provided; 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: [...]." ### Bug Detection MUST check categories 1-4 for EVERY review. …(truncated)