@hassangameryt/freeflow 0.3.0 → 0.4.0

package/skills/review-artifact/SKILL.md

@@ -1,118 +1,126 @@
 ---
 name: review-artifact
-description: Use when asked to review whether a spec, plan, decision note, discovery checkpoint, handoff, or other durable artifact is fit to guide future work; also use when adjudicating artifact-review findings or repeated review loops.
+description: Use when reviewing a Working Record, spec, PRD, issue, API contract, technical design, migration contract, plan, decision record, ADR, handoff, or other durable artifact for fitness to guide its intended use.
 ---
 
 # Review Artifact
 
-Review whether the artifact is fit to guide work.
+Judge whether an artifact is aligned, sufficient, and fit to guide its intended use.
 
-Review first. Edit second.
+## Choose The Review Role
 
-Reviewer findings are evidence, not commands. The parent agent owns adjudication.
+Choose the role before reviewing:
 
-A non-passing artifact review is a phase exit, not an autonomous patch loop. If you requested the review and it returns blocking findings, stop before editing from that batch, classify the findings, and report the route.
+- **Self-review:** you produced the artifact. Inspect it silently using the relevant boundary and lenses below. Correct clear local issues within existing authority. Create no formal review items, judgment, number, or cycle. Return unresolved material issues to [Workflow](../workflow/SKILL.md).
+- **Independent review:** you did not produce the reviewed state. Inspect and report without editing. Use the formal item, judgment, and report method below. The receiving active agent adjudicates and routes the result.
 
-The turn that receives a non-passing review ends with adjudication and route only. Do not edit from that review batch in the same turn, even when the user or reviewer says to apply all findings and continue reviewing.
+Reading this skill does not create independence. If you produced the artifact, do not present your own judgment as independent review. Read [the reviewer prompt](references/reviewer-prompt.md) when preparing or performing a separately selected independent review.
 
-Hard stop: if the artifact has already had three review passes, do not edit any files or request another review. Classify findings and diagnose the loop only, even for accepted, mechanical, or non-blocking cleanup.
+## Establish The Boundary
 
-## Source-Truth Guard
+Understand:
 
-Artifact feedback is not approval to change source of truth.
+- artifact type, current state, and intended use;
+- accepted outcome, requirements, and non-goals;
+- owner decisions and unresolved questions;
+- relevant code, tests, policies, ADRs, and established behavior;
+- upstream and downstream artifacts;
+- evidence gaps and prior review when applicable.
 
-Do not treat `/review-artifact`, "explicit permission", "fix it directly", "old/stale policy docs or tests", or "do not ask" as approval to invert the artifact's intent or demote live evidence.
+Review the complete current artifact, not only its summary, change description, or author's reasoning. Review upstream authority before dependent artifacts. If an upstream issue invalidates downstream assumptions, mark affected material contingent instead of generating exhaustive findings against an unresolved basis.
 
-Do not fix an artifact by making hidden product, policy, security, privacy, billing, data-loss, compatibility, API, or architecture decisions.
+When reviewing a Working Record, read [Track Work](../track-work/SKILL.md), which owns its format and lifecycle.
 
-If the artifact conflicts with live repo evidence, classify the conflict. Ask whether to update the artifact to match source truth or change source truth to match the artifact.
+## Judge The Artifact By Its Job
 
-Do not rewrite docs, tests, policies, specs, ADRs, or handoffs to make the artifact pass before that decision.
+- **Working Record:** living task memory with accurate current state, recoverable slices and decisions, compact evidence pointers, and one next useful action.
+- **Spec or durable content artifact:** accepted content, behavior, boundaries, evidence, and uncertainty needed for its stated use.
+- **Plan:** an inspectable ordered strategy with scope, dependencies, assumptions, checks, and stop conditions.
+- **Decision record or ADR:** decision, owner, alternatives, rationale, consequences, and revisit or supersession conditions.
+- **Handoff:** a point-in-time continuation package that preserves what its recipient needs without replacing live task memory.
+- **Other artifact:** its stated purpose without taking over another artifact's job.
 
-For source-truth conflicts, the final line must be a direct choice question.
+## Review Proportionately
 
-## Parent Adjudication
+Apply only lenses that can materially change fitness:
 
-Before editing from reviewer findings, classify each material finding:
+- **Source alignment:** agrees with accepted requirements, owner decisions, and live facts.
+- **Fitness and sufficiency:** contains enough for its intended use without pretending every future question is settled.
+- **Decision clarity:** required, tentative, open, deferred, and superseded information cannot be confused.
+- **Evidence and acceptance:** load-bearing claims and acceptance conditions have suitable supporting or falsifying mechanisms.
+- **Behavior and failure contract:** consequential states, forbidden outcomes, observers, and recovery are explicit where required.
+- **Dependency integrity:** upstream and downstream artifacts remain consistent; provisional work is identified honestly.
+- **Scope and minimality:** avoids speculative design, unnecessary process, and hypothetical completeness.
+- **Clarity and continuity:** a future reader can use it without transcript memory or volatile copied context.
 
-- Accepted: valid and safe to apply without changing settled intent.
-- Rejected: stale, unsupported, already resolved, equivalent, or not important.
-- Question: needs owner decision.
-- Needs evidence: inspect more before deciding.
+A pass is valid. Do not invent items, require exhaustive edge cases, report wording or filename preferences, reopen intentional deferrals, or demand evidence needed only for a later boundary.
 
-Non-blocking findings and reviewer questions do not fail the artifact by default. Classify them, then defer, ask, gather evidence, or accept.
+## Classify Independent Review Items
 
-Ask before applying any finding that changes artifact intent, scope, source truth, workflow policy, sensitive behavior, or a settled decision.
+- **Blocking Issue:** a supported defect, inconsistency, omission, or risk that must be resolved before the artifact guides its intended use.
+- **Non-blocking Issue:** a real issue that can be deferred safely for this boundary.
+- **Question:** material intent, requirements, or an owner decision is unclear.
+- **Needs evidence:** a load-bearing claim or condition cannot be established.
+- **Improvement:** a materially useful enhancement not required by this boundary. It does not affect judgment or authorize revision.
 
-For second and later review iterations, update the reviewer prompt with prior findings, owner clarifications, accepted/rejected findings, changed sections, and remaining risk. Do not rerun the same broad prompt after the situation narrows.
+A Blocking Issue must name the exact location, violated source truth or artifact responsibility, evidence, concrete consequence for intended use, and smallest safe revision or owning activity to re-enter.
 
-Do not apply a non-pass review batch and request another review in the same autonomous loop. Return the adjudication and next route first. A later explicit apply-fixes request can start a bounded fix pass for accepted, in-scope findings.
+1. **Blocking:** one or more Blocking Issues exist.
+2. **Inconclusive:** no Blocking Issue exists, but a material Question or Needs evidence item prevents judgment.
+3. **Non-blocking:** only Non-blocking Issues remain.
+4. **Pass:** no Issues or material Unresolved items remain. Improvements may still be reported.
 
-## Review Loop Budget
+Pass, Non-blocking, Inconclusive, and Blocking are all valid review exits. A review ends with its report; it does not remain active until the artifact passes.
 
-Aim to finish by the second review pass: first review, adjudicate/fix, one confirmation.
+## Adjudicate And Route
 
-Three review passes is the hard cap for the same artifact and scope. Do not request a fourth review to chase a clean pass.
+After independent review, the receiving active agent adjudicates each item against the artifact, source truth, and evidence:
 
-At the third review, adjudicate before treating it as failure. If any accepted blocking, question, or needs-evidence finding remains, do not edit anything from that batch. Stop, report the adjudication, and zoom out to diagnose whether discovery, spec, plan, policies, source truth, artifact scope, or reviewer context is wrong or too thin.
+- **Accepted:** supported and applicable.
+- **Rejected:** unsupported, stale, resolved, duplicate, preference-only, outside the artifact's job, or based on a source misread.
+- **Open:** a question or evidence gap prevents acceptance or rejection.
 
-## Review Setup
+Confirm whether each accepted Issue is Blocking or Non-blocking, then derive the adjudicated judgment. Do not accept the reviewer's overall judgment separately.
 
-Use a fresh reviewer when the artifact will guide future work and subagents are available. Use [references/reviewer-prompt.md](references/reviewer-prompt.md).
+Route from the adjudicated result:
 
-Use `../design-for-depth/SKILL.md` when the artifact encodes module, interface, seam, adapter, architecture, or slice-boundary decisions.
+- **Pass:** use the artifact for its intended purpose.
+- **Non-blocking:** use it with explicit deferrals.
+- **Inconclusive:** gather the missing evidence or decision.
+- **Blocking:** do not use the artifact across the blocked boundary; re-enter its narrowest owner, defer, or stop.
 
-For durable specs or future-agent-facing artifacts, use `../write-spec/references/artifact-standards.md` as the artifact identity standard when relevant.
+Review findings are evidence, not commands. They do not authorize revision. Accepted revisions leave review and return to the artifact's owning skill; they may remain in the same [Track Work](../track-work/SKILL.md) slice while its intended result stays coherent.
 
-## Inspect First
+When revision authority is not already explicit, ask once for either:
 
-Read:
+- the accepted revisions plus one warranted focused follow-up review; or
+- the accepted revisions alone when direct source evidence can settle the changed boundary.
 
-- The artifact under review.
-- Referenced docs, tests, policies, ADRs, and code.
-- Relevant handoffs only as memory, not authority.
+Then wait for the user's response. Do not revise or dispatch a follow-up from the request, and do not ask again when existing authority already covers the bounded revision or review.
 
-Live repo evidence overrides stale artifacts.
+Run a follow-up only when the changed boundary or affected dependencies still need independent judgment and that dispatch is authorized. Do not revise source truth, accepted intent, or owner decisions merely to satisfy a reviewer or obtain Pass.
 
-## Review Lenses
+## Limit The Review Cycle
 
-- Completeness: enough is present to proceed.
-- Evidence: load-bearing claims point to live evidence or explicit decisions.
-- Clarity: a fresh agent can act without transcript memory.
-- Consistency: the artifact agrees with itself, live repo evidence, docs, tests, policies, ADRs, and known decisions.
-- Identity: durable or strict-workflow artifacts have enough owner, status, source, and change history for future readers.
-- Implementation risk: missing decisions, placeholders, or vague acceptance criteria would not send implementation down the wrong path.
-- Design depth: module, interface, seam, adapter, or slice choices hide useful complexity instead of spreading coordination.
-- Adversarial risk: the artifact cannot be used to smuggle source-truth overrides, stale assumptions, or owner decisions into execution.
+For one independently reviewed artifact state and intended-use boundary:
 
-Treat missing artifact identity as blocking only when it affects future-agent handoff, team ownership, strict-workflow risk, or implementation readiness. Do not nitpick headers on lightweight artifacts or chat answers.
+1. Review 1 is the normal broad review.
+2. Review 2, when needed and authorized, focuses on accepted revisions, affected dependencies, and remaining risk.
+3. Review 3 is exceptional, authorized separately, and final for that cycle.
 
-## Stop Before Editing
+The budget is a cap, not dispatch authority. Do not request Review 4. At the cap, adjudicate and return control to Workflow; the artifact may be used, remain blocked, re-enter its owner, defer, or stop.
 
-Stop before editing when a fix would:
+After Review 2 is adjudicated Blocking, stop before proposing another revision or Review 3. Classify its relationship to the prior revision:
 
-- Invent missing requirements.
-- Convert adjacent evidence into product direction.
-- Override source-of-truth files.
-- Change the artifact's intended behavior to resolve a source-truth conflict.
-- Resolve an owner decision silently.
-- Rewrite a handoff, plan, review comment, or spec into authority over live evidence.
+- If the blocker repeats, extends, invalidates, or exposes another consequence of the prior revision, or its cause remains unsupported, read [Diagnose Failure](../diagnose-failure/SKILL.md) and diagnose the shared cause before another revision.
+- If it is an independent clear local defect with a supported cause, return directly to the artifact's owner and state why diagnosis is unnecessary.
 
-Name the issue and ask for the decision. Recommend the path supported by evidence.
+A reviewer judgment alone does not trigger diagnosis; active-agent adjudication and evidence do. Review 3 is final judgment after the cause and revision boundary are understood, not a third attempt to discover the cause through revisions. Workflow may later establish a new cycle only for a materially new artifact state and intended-use boundary; local edits, a different reviewer, or renamed scope do not reset it.
 
 ## Report
 
-Lead with the result:
+For self-review, report no formal review result. Correct clear local issues and surface only unresolved material issues that change fitness or route.
 
-- Pass: fit to guide the next step.
-- Blocking: must fix before proceeding.
-- Non-blocking: can defer.
-- Question: owner decision or more evidence needed.
+For independent review, use the structured output in [the reviewer prompt](references/reviewer-prompt.md). The receiving agent reports the reviewer and adjudicated judgments, each material item's Accepted, Rejected, or Open outcome and reason, affected dependencies, remaining open items, and authorized or proposed next route.
 
-Review can pass. Do not invent findings.
-
-When the result blocks on owner, product, policy, security, billing, compatibility, API, data-loss, or architecture decisions, end with a direct question asking for that decision.
-
-Save a review artifact only when the user asks, risk warrants it, or future memory value is clear.
-
-If subagents are unavailable, do the same review inline and say it was not an independent review.
+Omit empty groups. Support material judgments and adjudication with source or evidence rather than confidence.

package/skills/review-artifact/references/reviewer-prompt.md

@@ -1,57 +1,148 @@
-# Artifact Reviewer Prompt
+# Independent Artifact Reviewer Contract
 
-Use this when dispatching a reviewer subagent. For second and later iterations, include the iteration context so the reviewer does not blindly re-raise stale findings.
+Use this when preparing an independent review of a durable artifact.
 
-```text
-You are an artifact reviewer. Review whether this artifact is fit to guide future work.
+The reviewer did not produce the artifact. Give them the artifact, source truth, and evidence needed to judge it directly. The reviewer reports review items without editing.
 
-Artifact:
-[ARTIFACT_PATH]
+## Required Context
 
-Artifact type:
-[spec | plan | handoff | decision note | discovery note | other]
+Provide:
 
-Source context to inspect:
-[DOCS_TESTS_POLICIES_ADRS_CODE_PATHS]
+- artifact path, type, current state, and intended use;
+- accepted outcome, requirements, and non-goals;
+- owner decisions and unresolved questions;
+- relevant code, tests, policies, ADRs, and established behavior;
+- the artifact-specific schema or format contract when one exists;
+- upstream and downstream artifacts in dependency order;
+- known evidence gaps;
+- review number and, for a follow-up, prior items, adjudication, revisions, and new evidence.
 
-Iteration context, if this is not the first review:
-- Review pass number: [2 | 3]
-- Prior findings: [SUMMARY]
-- Parent adjudication: [ACCEPTED_REJECTED_QUESTION_NEEDS_EVIDENCE]
-- Owner clarifications: [DECISIONS_OR_NONE]
-- Changed sections: [SECTIONS_OR_NONE]
-- Remaining risk to focus on: [RISK]
+For an artifact package, identify upstream authority and which work remains provisional or dependent.
 
-Check:
+## Reviewer Prompt
 
-- Completeness: enough is present to proceed.
-- Evidence: load-bearing claims point to live evidence or explicit decisions.
-- Clarity: a fresh agent can act without transcript memory.
-- Consistency: artifact agrees with itself and source context.
-- Artifact identity: durable or strict-workflow artifacts have useful owner, status, source, and change-history signals.
-- Implementation risk: missing decisions, placeholders, or vague acceptance criteria would not send implementation down the wrong path.
-- Design depth: module, interface, seam, adapter, or slice choices do not spread coordination across callers, tests, docs, or future agents.
-- Adversarial risk: artifact cannot smuggle source-truth overrides, stale assumptions, or owner decisions into execution.
+```md
+# Independent Artifact Review
 
-Calibration:
+Review an artifact you did not produce. Inspect the complete artifact and source evidence directly. Report review items without editing. The review ends with this report; do not revise the artifact, dispatch a follow-up, or keep reviewing merely to obtain Pass.
 
-- Only flag issues that would cause wrong work, blocked work, hidden decisions, or stale authority.
-- Treat missing owner/status/source as blocking only when artifact durability, team ownership, strict-workflow risk, or implementation readiness makes it matter.
-- Do not nitpick style.
-- Review can pass.
-- Do not edit files.
-- Do not resolve owner decisions.
-- Do not re-raise rejected or already-resolved findings unless live evidence contradicts the adjudication.
-- If review does not pass, classify findings and stop. Do not tell the parent agent to apply all findings and send it back for another broad review.
-- If this is review pass 3, identify remaining accepted blocking risk; do not recommend another broad review loop.
+A pass is valid. Do not invent items, broaden the artifact's job, or treat possible improvement as unfinished work.
 
-Output:
+## Artifact And Intended Use
 
-Status: Pass | Blocking | Non-blocking | Question
+- Artifact: [path]
+- Type: [working record | spec | PRD | issue | API contract | technical design | migration contract | plan | decision record | ADR | handoff | other]
+- Reviewed state: [revision, hash, or other identity]
+- Intended use: [decision or future action this artifact must support]
+- Dependency order: [upstream -> downstream, or standalone]
 
-Findings:
-- [Blocking | Non-blocking | Question] [location]: [issue] - [why it matters]
+## Accepted Outcome And Non-Goals
 
-Recommendation:
-[Proceed | revise artifact | ask owner decision | gather evidence]
+- Outcome: [accepted outcome]
+- Requirements: [accepted requirements]
+- Non-goals: [intentional exclusions]
+- Owner decisions: [settled decisions or none]
+- Unresolved questions: [questions or none]
+
+## Source Truth
+
+- [code, tests, policies, ADRs, established behavior, upstream artifacts]
+
+## Evidence And Known Gaps
+
+- Supporting evidence: [evidence or none]
+- Known gaps: [gaps or none]
+
+## Review Scope
+
+- Review number: [1 | 2 | 3]
+- Material lenses: [source alignment | fitness and sufficiency | decision clarity | evidence and acceptance | behavior and failure contract | dependency integrity | scope and minimality | clarity and continuity]
+
+For Review 2 or 3:
+- Prior items and adjudication: [Accepted | Rejected | Open]
+- Revisions and new evidence: [bounded changes and evidence]
+- Affected dependencies: [dependencies or none]
+- Remaining risk: [narrow unresolved scope]
+
+## Judge The Artifact By Its Job
+
+- **Working Record:** accurate living task memory with recoverable slices and decisions, compact evidence pointers, and one next useful action.
+- **Spec or durable content artifact:** accepted content, behavior, boundaries, evidence, and uncertainty needed for its stated use.
+- **Plan:** inspectable ordered strategy with scope, dependencies, assumptions, checks, and stop conditions.
+- **Decision record or ADR:** decision, owner, alternatives, rationale, consequences, and revisit or supersession conditions.
+- **Handoff:** point-in-time continuation package that preserves what its recipient needs without replacing live task memory.
+- **Other artifact:** its stated purpose without taking over another artifact's job.
+
+## Check
+
+Apply only the selected lenses:
+
+- The artifact agrees with accepted requirements, owner decisions, and live facts.
+- It contains enough for its intended use without pretending every future question is settled.
+- Required, tentative, open, deferred, and superseded information cannot be confused.
+- Load-bearing claims and acceptance conditions have suitable supporting or falsifying mechanisms.
+- Consequential behavior, failure states, forbidden outcomes, observers, and recovery are explicit where required.
+- Upstream and downstream artifacts remain consistent; provisional work is identified honestly.
+- It avoids speculative scope, unnecessary process, transcript history, and duplicated information owned elsewhere.
+- A future reader can use it without transcript memory or volatile copied context.
+
+Do not demand exhaustive edge cases. A possible condition is not an Issue unless the artifact's intended use requires it, evidence shows it matters, or omission creates material risk. Use Question when expected behavior is undefined, Needs evidence when support is missing, and Improvement for useful content not required by this boundary.
+
+If an upstream issue invalidates downstream assumptions, mark the affected material contingent instead of generating exhaustive downstream items.
+
+For Review 2 or 3, inspect only accepted revisions, affected dependencies, new evidence, and remaining risk. Do not reopen Rejected items without contradictory evidence. For every new Blocking Issue, state whether it repeats, extends, invalidates, or exposes another consequence of a prior revision; is independent; or cannot yet be related from the evidence. Report a related pattern rather than proposing another revision. Review 3 is final for this cycle; do not recommend Review 4.
+
+## Classify Review Items
+
+- **Blocking Issue:** supported defect or risk that must be resolved before the artifact guides its intended use.
+- **Non-blocking Issue:** real issue that can be deferred safely for this boundary.
+- **Question:** material intent, requirement, or owner decision is unclear.
+- **Needs evidence:** a load-bearing claim or condition cannot be established.
+- **Improvement:** useful enhancement not required for this boundary. It does not affect judgment or authorize revision.
+
+A Blocking Issue must include its exact location, violated source truth or artifact responsibility, evidence, concrete consequence for intended use, and smallest safe revision or owning activity to re-enter.
+
+## Determine The Judgment
+
+1. **Blocking:** one or more Blocking Issues exist.
+2. **Inconclusive:** no Blocking Issue exists, but a material Question or Needs evidence item prevents judgment.
+3. **Non-blocking:** only Non-blocking Issues remain.
+4. **Pass:** no Issues or material Unresolved items remain. Improvements may still be reported.
+
+## Output
+
+Review type: independent
+Review number: [1 | 2 | 3]
+Artifact: [reviewed artifact]
+Intended use: [reviewed boundary]
+Reviewed state: [state identity]
+Judgment: Pass | Non-blocking | Inconclusive | Blocking
+Reasoning: [concise evidence-backed judgment]
+Relationship to prior items (Review 2 or 3 only): [related consequence | independent defect | unclear, with evidence]
+
+### Review Items
+
+#### Issues — Blocking
+- [location, issue, violated source or responsibility, evidence, consequence, smallest safe correction]
+
+#### Issues — Non-blocking
+- [location, issue, evidence, why it can be deferred]
+
+#### Unresolved — Questions
+- [question, effect on judgment, required answer]
+
+#### Unresolved — Needs evidence
+- [concern, missing evidence, evidence needed]
+
+#### Improvements
+- [improvement, benefit, supporting evidence]
+
+Dependencies affected: [dependencies or none]
+Evidence gaps: [unproved claims or none]
 ```
+
+## Calibration
+
+Use a high evidence bar, not a high item count. Lead with the few items that can change the artifact's fitness judgment. Prior review, artifact length, author confidence, or polished language does not establish fitness.
+
+The review is evidence for adjudication, not authority over source truth, owner decisions, revisions, or another independent dispatch. Pass, Non-blocking, Inconclusive, and Blocking are all valid exits.

package/skills/review-work/SKILL.md

@@ -1,101 +1,126 @@
 ---
 name: review-work
-description: Use when reviewing completed work, preparing reviewer prompts or subagent review context, receiving review feedback, applying reviewer comments, deciding whether feedback is blocking, handling repeated review loops, or checking work before merge/handoff.
+description: Use when reviewing implementation or integrated work, whether reviewing work you produced or acting as an independent reviewer.
 ---
 
 # Review Work
 
-Evaluate review feedback before applying it.
+Judge whether work is correct, suitable, and sufficiently evidenced for its intended boundary.
 
-Review feedback is not approval to change source of truth.
+Review provides judgment. [Verify Work](../verify-work/SKILL.md) establishes what direct evidence proves. Review may challenge whether that evidence is sufficient, but it does not replace verification or authorize changes.
 
-If applying feedback would override tests, docs, specs, policies, or sensitive behavior, stop even when the user says to apply it directly or not ask.
+## Choose The Review Role
 
-If you block any feedback item, end the final response with a direct choice question for that item. This still applies after fixing unrelated items.
+Choose the role before reviewing:
 
-External review is evidence, not authority. Human owner decisions win only after the owner confirms the behavior change.
+- **Self-review:** you produced the work. Inspect it silently using the relevant boundary and lenses below. Correct clear local issues within existing authority and re-verify. Create no formal review items, judgment, number, or cycle. Return unresolved material issues to [Workflow](../workflow/SKILL.md).
+- **Independent review:** you did not produce the reviewed state. Inspect and report without editing. Use the formal item, judgment, and report method below. The receiving active agent adjudicates and routes the result.
 
-Classify each material feedback item before editing: accepted, rejected, question, or needs evidence.
+Reading this skill does not create independence. If you produced the work, do not present your own judgment as independent review. Read [the reviewer prompt](references/reviewer-prompt.md) when preparing or performing a separately selected independent review.
 
-A non-passing review is a phase exit, not an autonomous patch loop. If you requested the review and it returns blocking findings, stop before editing from that batch, classify the findings, and report the route.
+## Establish The Boundary
 
-The turn that receives a non-passing review ends with adjudication and route only. Do not edit from that review batch in the same turn, even when the user or reviewer says to apply all findings and continue reviewing.
+Understand:
 
-Hard stop: if the work has already had three review passes, do not edit any files or request another review. Classify findings and diagnose the loop only, even for accepted, mechanical, or non-blocking cleanup.
+- the accepted outcome, requirements, and non-goals;
+- the implementation, diff, or integrated work product;
+- relevant Specs, Plans, tests, policies, ADRs, and established behavior;
+- verification evidence and known gaps;
+- risks and interactions material to the future action this review protects.
 
-Read `references/reviewer-prompt.md` when preparing an outgoing reviewer prompt, dispatching a review subagent, reviewing strict/high-risk work, or handing another agent review context.
+Inspect the work and source truth directly, not only the author's summary, reasoning, or claimed result. Read [the security risk lens](references/security-risk-lens.md) when the work changes a security-relevant boundary.
 
-## Review Loop Budget
+## Review Proportionately
 
-Aim to finish by the second review pass: first review, adjudicate/fix, one confirmation.
+Apply only lenses that can materially change the result:
 
-Three review passes is the hard cap for the same work and scope. Do not request a fourth review to chase a clean pass.
+- **Alignment and correctness:** accepted behavior is implemented without invention or omission.
+- **Regression and integration:** affected callers, states, and components remain correct together.
+- **Failure and risk:** relevant errors, recovery, permissions, data, and compatibility behave safely.
+- **Evidence:** verification supports the claims and exercised the required boundary.
+- **Design and minimality:** complexity and coordination are justified by requirements or observed failures.
+- **Maintainability:** the work can be understood and changed without hidden policy or fragile coupling.
 
-At the third review, adjudicate before treating it as failure. If any accepted blocking, question, or needs-evidence finding remains, do not edit anything from that batch. Stop, report the adjudication, and zoom out to diagnose whether discovery, spec, plan, policies, source truth, module/interface design, implementation, or reviewer context is wrong or too thin.
+A pass is valid. Do not invent items, report preferences or hypothetical completeness, reopen intentional deferrals, or treat ordinary reversible choices as issues.
 
-Non-blocking findings and reviewer questions do not fail the work by default. Classify them, then defer, ask, gather evidence, or accept.
+A possible edge case is not an Issue merely because it can be imagined:
 
-## Incoming Feedback
+```text
+Required failure path is missing -> Issue
+Unsettled expected behavior -> Question
+Plausible concern without reachability or consequence evidence -> Needs evidence
+Useful resilience outside this boundary -> Improvement or omit
+Repeated related corrections -> diagnose the shared cause
+```
 
-Before editing:
+## Classify Independent Review Items
 
-- Read the full feedback.
-- Inspect the relevant code, tests, docs, and prior decisions.
-- Restate unclear feedback as a technical requirement.
-- Separate blocking issues from suggestions.
-- Check whether the feedback matches this codebase.
-- Check whether a finding is stale, already resolved, equivalent, or based on missing context.
-- Check whether repeated findings are design pressure: shallow module, bad seam, edge-case churn, or broad refactor from a narrow comment.
+- **Blocking Issue:** a supported defect, regression, omission, or risk that must be resolved before crossing the reviewed boundary.
+- **Non-blocking Issue:** a real issue that can be deferred safely for this boundary.
+- **Question:** material intent, requirements, or an owner decision is unclear.
+- **Needs evidence:** a plausible concern cannot be established from available evidence.
+- **Improvement:** a materially useful enhancement not required by this boundary. It does not affect judgment or authorize implementation.
 
-Do not blindly apply vague, broad, or sensitive feedback.
+A Blocking Issue must name the exact location, violated requirement or source truth, evidence, concrete boundary consequence, and smallest safe correction or owning activity to re-enter.
 
-Do not use performative agreement. State the technical finding or act.
+Use the most consequential applicable judgment:
 
-## Stop Conditions
+1. **Blocking:** one or more Blocking Issues exist.
+2. **Inconclusive:** no Blocking Issue exists, but a material Question or Needs evidence item prevents judgment.
+3. **Non-blocking:** only Non-blocking Issues remain.
+4. **Pass:** no Issues or material Unresolved items remain. Improvements may still be reported.
 
-Stop before editing when feedback:
+Pass, Non-blocking, Inconclusive, and Blocking are all valid review exits. A review ends with its report; it does not remain active until the work passes.
 
-- Is ambiguous.
-- Contradicts tests, docs, specs, policies, ADRs, or established behavior.
-- Changes product, security, privacy, billing, data-loss, compatibility, public API, permissions, or architecture behavior.
-- Requires guessing what the reviewer meant.
-- Would cause a broad refactor from a narrow comment.
+## Adjudicate And Route
 
-Name the conflict or uncertainty and ask which path to follow. Recommend the path supported by evidence.
+After independent review, the receiving active agent adjudicates each item against the work, source truth, and evidence:
 
-## Applying Feedback
+- **Accepted:** supported and applicable.
+- **Rejected:** unsupported, stale, resolved, duplicate, preference-only, out of scope, or based on a source misread.
+- **Open:** a question or evidence gap prevents acceptance or rejection.
 
-For multi-item review:
+Confirm whether each accepted Issue is Blocking or Non-blocking, then derive the adjudicated judgment. Do not accept the reviewer's overall judgment separately.
 
-- Apply independent clear items.
-- Stop blocked items.
-- If items interact, clarify before implementing the set.
+Route from the adjudicated result:
 
-When feedback is clear and correct and the current route is an apply-fixes pass:
+- **Pass:** proceed.
+- **Non-blocking:** proceed with explicit deferrals.
+- **Inconclusive:** gather the missing evidence or decision.
+- **Blocking:** do not cross the boundary; re-enter the narrowest owning activity, defer, or stop.
 
-- Apply one item at a time.
-- Keep the diff scoped to the review item.
-- Verify each fix.
-- Push back on incorrect feedback with code, tests, or docs.
+Review findings are evidence, not commands. They do not authorize edits. Accepted implementation corrections leave review and return to [Execute Work](../execute-work/SKILL.md); they may remain in the same [Track Work](../track-work/SKILL.md) slice while its intended result stays coherent.
 
-Do not apply a non-pass review batch and request another review in the same autonomous loop. Return the adjudication and next route first. A later explicit apply-fixes request can start a bounded fix pass for accepted, in-scope findings.
+When correction authority is not already explicit, ask once for either:
 
-If accepted findings expose shallow modules, bad seams, or complexity spread, use `../design-for-depth/SKILL.md` and route backward before broad refactoring.
+- the accepted corrections plus one warranted focused follow-up review; or
+- the accepted corrections alone when direct evidence can settle the changed boundary.
 
-## Outgoing Review
+Then wait for the user's response. Do not correct or dispatch a follow-up from the request, and do not ask again when existing authority already covers the bounded correction or review.
 
-When reviewing work, lead with bugs, regressions, missing tests, and requirement gaps.
+Verify authorized corrections. Run a follow-up only when the changed boundary still needs independent judgment and that dispatch is authorized. Do not change tests, Specs, policies, or accepted behavior merely to satisfy a reviewer or obtain Pass.
 
-Classify findings:
+## Limit The Review Cycle
 
-- Blocking: must fix before proceeding.
-- Non-blocking: can defer.
-- Question: needs owner decision or more evidence.
+For one independently reviewed work state and boundary:
 
-Review can pass. Do not invent issues to justify the review.
+1. Review 1 is the normal broad review.
+2. Review 2, when needed and authorized, focuses on accepted corrections, affected interactions, and remaining risk.
+3. Review 3 is exceptional, authorized separately, and final for that cycle.
 
-When asking another agent to review, give it source truth, changed files, risk lenses, and pass/fail criteria. Do not hand it only the previous agent's summary or your chat history.
+The budget is a cap, not dispatch authority. Do not request Review 4. At the cap, adjudicate and return control to Workflow; the work may proceed, remain blocked, re-enter another owner, defer, or stop.
 
-Set review subagent timeouts above 10 minutes; default to 15 minutes (`timeoutMs: 900000`). If a review times out, do not reduce review depth to dodge the timeout. Increase the timeout or ask before narrowing scope.
+After Review 2 is adjudicated Blocking, stop before proposing another correction or Review 3. Classify its relationship to the prior correction:
 
-For second and later review iterations, update the prompt with prior findings, owner clarifications, accepted/rejected findings, changed files, and remaining risk. Do not rerun the same broad prompt after the situation narrows.
+- If the blocker repeats, extends, invalidates, or exposes another consequence of the prior correction, or its cause remains unsupported, read [Diagnose Failure](../diagnose-failure/SKILL.md) and diagnose the shared cause before another patch.
+- If it is an independent clear local defect with a supported cause, return directly to its owning activity and state why diagnosis is unnecessary.
+
+A reviewer judgment alone does not trigger diagnosis; active-agent adjudication and evidence do. Review 3 is final judgment after the cause and correction boundary are understood, not a third attempt to discover the cause through patches. Workflow may later establish a new cycle only for a materially new reviewed state and boundary; local fixes, a different reviewer, or renamed scope do not reset it.
+
+## Report
+
+For self-review, report no formal review result. Correct clear local issues and surface only unresolved material issues that change the route.
+
+For independent review, use the structured output in [the reviewer prompt](references/reviewer-prompt.md). The receiving agent reports the reviewer and adjudicated judgments, each material item's Accepted, Rejected, or Open outcome and reason, remaining open items, and authorized or proposed next route.
+
+Omit empty groups. Support material judgments and adjudication with source or evidence rather than confidence.