Review

Code Review

$fw:review reviews code changes with a risk-first, structured workflow. It selects reviewers from diff evidence, dispatches them in parallel when the host supports it, keeps synthesis centralized, and keeps mutation bounded.

Use this skill before merge, after meaningful implementation work, or inside a larger Flywheel loop when code has changed and the next job is to find risk.

When directly invoked, always review. Do not downgrade a direct invocation into a casual summary or diff explanation. If the scope is unclear, establish it and continue the review workflow.

Interaction Method

Follow ../references/host-interaction-contract.md.

Call the exact host question tool named in ../references/host-interaction-contract.md when that tool is available. Do not ask for raw 1/2/3 replies when the host already offers a choice surface.

When the workflow spans multiple material steps, use the host task-tracking tool named in ../references/host-interaction-contract.md to create and maintain a short task list.

Ask one question at a time. In mode:autofix, mode:report-only, or mode:headless, skip interactive questions unless the mode contract explicitly requires a failure message instead.

When To Use

• Before creating a PR
• After completing a task during iterative implementation
• When feedback is needed on any code changes
• As a standalone branch review
• As a read-only or autofix review step inside a larger workflow

Argument Parsing

Parse $ARGUMENTS for the following optional tokens. Strip each recognized token before interpreting the remainder as the PR number, GitHub URL, or branch name.

All tokens are optional. Each one present means one less thing to infer.

Conflicting mode flags: If multiple mode tokens appear, stop and do not dispatch reviewers. If mode:headless is one of the conflicting tokens, emit:

Review failed (headless mode). Reason: conflicting mode flags — <mode_a> and <mode_b> cannot be combined.

Otherwise emit:

Review failed. Reason: conflicting mode flags — <mode_a> and <mode_b> cannot be combined.

Reference Loading Map

Do not preload every reference. Load only what the current phase needs:

• Read references/resolve-base.sh only during Stage 1 when branch or standalone scope detection needs a base branch.
• Always read references/reviewer-registry.yaml and references/persona-loading.md first when Stage 3 begins.
• Read references/stack-packs/index.yaml only when Stage 3 determines stack packs should be considered for this diff.
• After stack-pack selection, read only the matching pack files and only the stack-pack reference files those packs explicitly name.
• Read ../observability/references/service-readiness-matrix.md only when the diff changes runtime behavior, contracts, state, rollout posture, retries, queues, migrations, or other service-readiness-sensitive boundaries.
• Read only the selected persona files under references/personas/ after the registry and loading guide identify them.
• Read references/diff-scope.md and references/findings-schema.json immediately before reviewer dispatch or serial reviewer execution.
• Read references/subagent-template.md immediately before parallel reviewer dispatch.
• Read ../references/research/activation-heuristics.md and ../references/research/source-ranking-and-synthesis.md only when judging the diff depends on current published guidance, external API or framework behavior, standards, security guidance, or other facts not settled by repo truth alone.
• Read ../commit/references/evidence-bundle.md only when an existing shared evidence bundle is present or the review artifact should feed $fw:commit.
• Read references/review-output-template.md during synthesis and presentation.
• Read ../references/workflow-gates.md during synthesis when turning review verdict, blocking status, and evidence into the next handoff.

Host Compatibility

This skill is optimized for Codex and Claude Code style hosts:

• keep the stable orchestration scaffold and registry loading order intact
• keep dynamic diff and repo context later in the prompt
• keep reviewer prompts narrow, explicit, and evidence-bound
• prefer named context blocks such as <intent>, <files>, <diff>, <pr-context>, and <standards-paths> when building reviewer context
• avoid aggressive "always use every reviewer" wording; select reviewers by evidence so hosts do not overtrigger

Mode Detection

Mode Rules

Autofix

• Skip all user questions after scope is established.
• Apply only safe_auto -> review-fixer findings.
• Write a run artifact under .context/flywheel/review/<run-id>/.
• Create durable todo files only for unresolved actionable findings whose final owner is downstream-resolver.
• Never commit, push, or create a PR from autofix mode.

Report-only

• Skip all user questions.
• Never edit files or externalize work.
• Do not write .context/flywheel/review/<run-id>/.
• Safe for parallel read-only verification on the same checkout.
• Do not switch the shared checkout. If a caller wants another branch or PR in report-only mode, it must run from an isolated checkout or worktree.

Headless

• Skip all user questions and infer intent conservatively when needed.

• Require a determinable diff scope. If headless mode cannot determine one, emit:

  Review failed (headless mode). Reason: no diff scope detected. Re-invoke with a branch name, PR number, or base:<ref>.
  

• Apply only safe_auto -> review-fixer findings in a single pass.

• Return all non-auto findings as structured text output.

• Write a run artifact under .context/flywheel/review/<run-id>/.

• Do not create todo files.

• Do not switch the shared checkout. If a caller passes an explicit PR or branch target in headless mode on a shared checkout, emit:

  Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.
  

• End with Review complete as the terminal signal.

Severity Scale

All reviewers use P0-P3:

Action Routing

Severity answers urgency. Routing answers who acts next and whether this skill may mutate the checkout.

Routing rules:

• Synthesis owns the final route.
• On disagreement, choose the more conservative route.
• Only safe_auto -> review-fixer enters the in-skill fixer queue automatically.
• requires_verification: true means the fix is incomplete without targeted tests, focused re-review, or operational validation.

Reviewer Catalog

The initial Flywheel reviewer catalog is intentionally cross-cutting and language-agnostic. The core workflow does not depend on stack- or platform-specific reviewers being hardcoded into SKILL.md.

Every review starts with a bounded default budget:

• 2 baseline structured personas
• any relevant scale-up structured reviewers
• any relevant cross-cutting conditionals
• optional stack-pack extensions
• optional Flywheel agents only when the diff or repo evidence actually calls for them

Read references/reviewer-registry.yaml and references/persona-loading.md before reviewer selection. Do not invent new reviewer categories during synthesis. Add them through the registry and persona files instead.

The registry plus persona files are the extension surface. Keep SKILL.md generic, append new reviewers in the registry, and use stack packs only when a specialist truly depends on repo, stack, or platform evidence.

This deterministic loading order is mandatory. Do not skip straight to persona files or hardcode reviewer choices in the orchestrator body.

Protected Artifacts

The following paths are Flywheel pipeline artifacts and must never be flagged for deletion, removal, or gitignore:

• docs/brainstorms/*
• docs/plans/*.md
• docs/solutions/*.md

Discard any cleanup finding that targets those directories.

Workflow

Stage 1: Determine Scope

Compute the diff range, file list, and diff.

If base: is provided

Use the provided value directly and skip base-branch detection:

BASE_ARG="{base_arg}"
BASE=$(git merge-base HEAD "$BASE_ARG" 2>/dev/null) || BASE="$BASE_ARG"
echo "BASE:$BASE" && echo "FILES:" && git diff --name-only "$BASE" && echo "DIFF:" && git diff -U10 "$BASE" && echo "UNTRACKED:" && git ls-files --others --exclude-standard

Do not combine base: with a PR number, GitHub URL, or explicit branch target. If both are present, stop with:

Cannot use `base:` with a PR number or branch target — `base:` implies the current checkout is already the correct branch. Pass `base:` alone, or pass the target alone and let scope detection resolve the base.

If a PR number or GitHub URL is provided

• Preflight gate: if mode:report-only or mode:headless is running on the shared checkout, stop here before any checkout logic. Do not continue to the remaining steps in this section.

• Only continue to gh pr checkout when the run is interactive or autofix, or when the review is already running in an isolated checkout or worktree.

• Verify the worktree is clean with git status --porcelain before switching. If it is dirty, stop and ask the user to stash or commit first.

• Check out the PR branch with:

  gh pr checkout <number-or-url>
  

• Fetch PR metadata:

  gh pr view <number-or-url> --json title,body,baseRefName,headRefName,url
  

• Resolve the base ref from the PR's actual base repository and compute the merge-base. Review against the local diff from that base so re-reviews include local fix commits and uncommitted edits.

• If the base ref cannot be resolved, stop rather than falling back to git diff HEAD.

If a branch name is provided

• Preflight gate: if mode:report-only or mode:headless is running on the shared checkout, stop here before any checkout logic. Do not continue to the remaining steps in this section.

• Only continue to git checkout <branch> when the run is interactive or autofix, or when the review is already running in an isolated checkout or worktree.

• Verify the worktree is clean before switching.

• Check out the named branch with:

  git checkout <branch>
  

• Run bash references/resolve-base.sh. If it outputs an error, stop rather than falling back to git diff HEAD.

• On success, produce:

  echo "BASE:$BASE" && echo "FILES:" && git diff --name-only "$BASE" && echo "DIFF:" && git diff -U10 "$BASE" && echo "UNTRACKED:" && git ls-files --others --exclude-standard
  

If no argument is provided

• Run bash references/resolve-base.sh.

• If it fails, stop instead of silently reviewing only working-copy changes.

• On success, review:

  echo "BASE:$BASE" && echo "FILES:" && git diff --name-only "$BASE" && echo "DIFF:" && git diff -U10 "$BASE" && echo "UNTRACKED:" && git ls-files --others --exclude-standard
  

Using git diff "$BASE" against the working tree includes committed, staged, and unstaged changes together.

Untracked file handling

Always inspect the UNTRACKED: list even when FILES: and DIFF: are non-empty.

• Interactive mode: tell the user which files are excluded. If any should be reviewed, stop and ask them to git add those files first.
• Autofix or headless: proceed with tracked changes only and note the excluded files in Coverage.

Stage 2: Intent Discovery

Understand what the change is trying to accomplish.

• PR mode: use the PR title, body, linked issues, and commit messages when needed.

• Branch mode: inspect git log --oneline ${BASE}..<branch>.

• Standalone mode: inspect:

  echo "BRANCH:" && git rev-parse --abbrev-ref HEAD && echo "COMMITS:" && git log --oneline "${BASE}..HEAD"
  

Write a 2-3 line intent summary and pass it to every reviewer.

If intent is ambiguous:

• Interactive mode: ask one targeted question using the exact host question tool named in the host interaction contract when that tool is available.
• Autofix, report-only, or headless: infer conservatively and note the uncertainty in Coverage or Verdict reasoning.

Stage 2b: Plan Discovery

Locate the plan document so requirements completeness can be checked later. Check these sources in order:

1. plan: argument
2. PR body for docs/plans/*.md
3. auto-discovery from branch-name keywords against docs/plans/*

Confidence tagging:

• caller-provided or single unambiguous PR-body match -> plan_source: explicit
• auto-discovery or ambiguous PR-body resolution -> plan_source: inferred

If a plan is found, read its Requirements Trace and Implementation Units. Do not block the review if no plan is found.

When implementation units include Test posture: tdd, extract the unit labels, changed files, Red signal, and Green signal. Use that expectation later to check whether the diff or evidence bundle shows a red-green-refactor path. A missing TDD proof is review evidence, not just a process nit, unless the plan or diff clearly records a valid exception.

Stage 2c: Build A Service-Readiness Frame When Needed

If the diff is runtime-risky, read ../observability/references/service-readiness-matrix.md and build a concise readiness frame from the dimensions that apply.

Use that frame to sharpen:

• reviewer selection, especially observability, reliability, performance, data-access, api-contract, data-migrations, and deployment verification
• verdict reasoning
• any final handoff into $fw:rollout or $fw:commit

Stage 2d: Discover Local Prior Learnings

If the active repo has docs/solutions/ and the diff touches an area that may already be documented:

• search solution frontmatter first by files_touched, module, tags, problem_type, component, and title
• prefer docs with doc_status: active
• if a strong hit has superseded_by, follow that path first and treat the older doc as historical context only
• read only the strongest hits

Use these local prior learnings to:

• sharpen reviewer selection when the diff revisits a known failure mode
• detect whether the current change appears to contradict established guidance
• seed the final "Learnings and past solutions" section with repo-local context
• avoid treating already-solved historical incidents as brand new discoveries

Stage 2e: Read Local Workflow Policy When Present

If .flywheel/config.local.yaml exists, read only the local policy keys that materially affect review-to-commit handoff, such as:

• review.require_review_before_commit
• runtime.require_operational_validation_for_runtime_changes
• browser-proof gates already relevant to the changed surface

Use these local policy gates to sharpen:

• verdict reasoning
• residual-work vs commit-readiness language
• final handoff into $fw:commit

Absent config is not a policy violation. Treat local policy as an explicit overlay, not a universal Flywheel default.

Stage 2f: Discover Shared Evidence Bundle When Present

If .context/flywheel/evidence/ exists, inspect only the newest summary.md that clearly matches the current branch, task, or plan.

Use that bundle to:

• avoid re-describing browser or verification proof that already exists
• sharpen commit-readiness reasoning
• decide whether this review should append its own verdict and artifact path for $fw:commit

Stage 2g: Gather Targeted External Context When Needed

If review correctness depends on current external knowledge that the repo does not authoritatively answer, gather only the smallest targeted context needed.

Typical triggers:

• framework or library behavior changed recently
• the diff relies on an external API contract or standards surface
• security, privacy, or compliance guidance materially affects the finding
• the review is checking whether the chosen approach matches current published guidance rather than only local style

Before broad browsing, look for a matching docs/research/ brief if one is likely to exist. If no strong local brief exists, use a narrow research pass:

• prefer official docs, primary sources, or authoritative standards
• gather only the source set needed to support or reject the candidate finding
• keep the notes compact and attach them to findings or verdict reasoning, including the recommendation or verdict they support
• do not turn review into a standalone research report or route away from review just because lookup was needed

Use this context to sharpen reviewer selection, severity, and final reasoning.

Stage 3: Select Reviewers

Read the diff and file list from Stage 1, then read references/reviewer-registry.yaml and references/persona-loading.md.

Always include the baseline reviewers from the registry.

Add scale-up structured reviewers and Flywheel agents only when the diff, standards paths, local learnings, or agent-workflow surface actually warrant them.

For each cross-cutting conditional reviewer, decide whether the diff warrants it. This is agent judgment, not keyword matching.

More reviewers is not automatically better. Prefer the smallest set that gives clear coverage of the actual risks in the diff.

If the repo and diff suggest stack- or platform-specific review would be useful:

• read references/stack-packs/index.yaml
• detect matching stack packs from changed files, nearby manifests, repo-root manifests, and applicable instruction files
• load only the matching stack-pack files
• read only the stack-pack reference files explicitly named by those matching pack files
• add the reviewer IDs named by those pack files

When multiple stack packs match, combine them additively into one selected reviewer set. Typical combinations include:

• typescript + react for typed React surfaces
• language pack + postgres when app code and PostgreSQL behavior both change
• language pack + kafka or redis only when the diff clearly touches those integrations
• language pack + otel or datadog when the diff changes telemetry, correlation, monitors, or runtime validation surfaces

Do not split synthesis by pack. Pack selection determines who reviews; the selected reviewers still flow through one shared dispatch, merge, and verdict pipeline.

Only after the selected reviewer IDs are known, load the corresponding persona files from references/personas/.

Selection rules:

• previous-comments is PR-only. Skip it when no PR metadata exists.
• Count executable code toward adversarial line-count thresholds. Pure instruction prose, schemas, and config do not automatically warrant adversarial review unless they describe or alter high-risk behavior.
• Do not bypass the registry by hardcoding reviewer files directly in the main workflow body.

Announce the team before spawning. Include one-line justifications for conditional reviewers.

Stage 3b: Discover Project Standards Paths

Before spawning reviewers, locate relevant AGENTS.md and CLAUDE.md files:

1. Find all **/AGENTS.md and **/CLAUDE.md.
2. Keep only those whose directory is an ancestor of at least one changed file.

If project-standards was selected, pass the resulting path list to that reviewer inside a <standards-paths> block. The reviewer reads the files itself.

Stage 4: Execute Reviewer Passes

Execution Notes

This workflow uses model-tiered review orchestration when the host supports it:

• keep the orchestrator on the strongest available frontier model
• keep reviewer or fixer subagents on the fastest available frontier-capable model when the platform supports model overrides
• do not downgrade review quality to a cheap or small model unless the user explicitly asks for a cost- or latency-optimized pass
• keep reviewer prompts narrow and schema-bound
• keep returns compact to protect synthesis quality and context window health

If the platform has no model override mechanism, let reviewers inherit the default model rather than breaking dispatch.

When overrides are available, use frontier capability tiers. Prefer capability labels over provider branding, then bind them to the latest available GPT or Opus model family at dispatch time:

• frontier_orchestrator for synthesis, policy decisions, and complex merge work
• frontier_review_worker for narrow reviewer passes

Map those tiers to host-native model names only at dispatch time.

Run ID

In interactive, autofix, and headless modes, generate a run ID before dispatching reviewers:

RUN_ID=$(date +%Y%m%d-%H%M%S)-$(head -c4 /dev/urandom | od -An -tx1 | tr -d ' ')
mkdir -p ".context/flywheel/review/$RUN_ID"

Report-only mode skips run-id generation and file writes.

Dispatch

Read:

• references/diff-scope.md
• references/findings-schema.json
• references/subagent-template.md

If the platform supports subagents or tasks and the active host policy permits delegated review work, dispatch the selected reviewers in parallel. When the host requires explicit delegation approval, only delegate after that approval is already present. Otherwise run the same reviewer passes serially yourself while preserving persona boundaries.

Parallelism is by reviewer, not by pack. Once the selected reviewer set is known, dispatch the baseline reviewers plus any selected scale-up, cross- cutting, and stack-pack reviewers in the same parallel review batch when the host allows it.

Keep each reviewer prompt compact:

• include only the selected persona file, not the full reviewer library
• include only the shared references needed for execution
• avoid repeating large diff-independent instructions inside every reviewer prompt

Each structured reviewer receives:

1. its persona definition
2. diff-scope rules
3. the findings schema
4. PR metadata when available
5. intent summary, file list, and diff
6. local prior-learnings summary when Stage 2d found any strong hits
7. run ID and reviewer name
8. standards-paths for project-standards only
9. stack-pack reference files only for stack- or platform-specific reviewers selected by a matching pack
10. TDD expectations from plan units when Stage 2b found any

Reviewer passes are read-only with respect to project code. The one permitted write is the reviewer artifact file under:

.context/flywheel/review/{run_id}/{reviewer_name}.json

Each reviewer writes full JSON to disk when a run ID exists and returns compact JSON with merge-tier fields only.

When delegated reviewer execution is permitted, dispatch only the selected Flywheel agents in parallel with the structured reviewers. Otherwise produce the equivalent advisory analysis inline and preserve those outputs for synthesis even though they do not use the structured findings schema.

Stage 5: Merge Findings

Convert multiple reviewer returns into one deduplicated, confidence-gated finding set. This is the coalescing step for the whole review, including any parallel stack-pack reviewers.

1. Validate compact returns against the compact-return field set: top-level reviewer, findings, residual_risks, and testing_gaps, plus per-finding merge-tier fields only. Do not apply artifact-only requirements such as why_it_matters or evidence at this stage. Drop malformed returns or findings and record the drop count.

2. Confidence gate findings below 0.60. Exception: P0 findings at 0.50+ survive.

3. Deduplicate using:

   normalize(file) + line_bucket(line, +/-3) + normalize(title)
   

4. Cross-reviewer agreement boosts merged confidence by 0.10, capped at 1.0.

5. Separate pre-existing findings into their own list.

6. Resolve disagreements by keeping the most conservative severity and route, while preserving reviewer disagreement notes.

7. Normalize routing so synthesis owns final autofix_class, owner, and requires_verification.

8. Partition the work into:

   • in-skill fixer queue: safe_auto -> review-fixer
   • residual actionable queue: unresolved gated_auto or manual findings owned by downstream-resolver
   • report-only queue: advisory findings and anything owned by human or release

9. Sort by severity, then confidence descending, then file path, then line.

10. Collect coverage data by unioning residual risks and testing gaps.

11. Track internal quality dimensions across merged findings for simplicity, maintainability, architecture fit, and pattern justification. Use this metadata to sharpen synthesis only. Do not turn it into a user-facing scorecard.

12. Preserve Flywheel agent artifacts alongside the merged findings.

Stage 6: Synthesize And Present

Read references/review-output-template.md. Read ../references/workflow-gates.md and apply the Review-Ready gate before declaring the next stage.

Use pipe-delimited markdown tables for interactive findings output. Do not present findings as prose blocks.

Keep any internal quality-dimension tracking out of the interactive score surface unless the user explicitly asks for it.

Interactive output should contain:

1. Header with scope, intent, mode, and reviewer team
2. Findings grouped by severity
3. Requirements completeness, only when a plan was found
4. Applied fixes, only if a fix phase ran
5. Residual actionable work, when applicable
6. Pre-existing issues
7. Learnings and past solutions
8. Agent-native gaps
9. Service readiness notes, when Stage 2c ran
10. Schema drift check, when that agent ran
11. Deployment notes, when that agent ran
12. Coverage
13. Verdict
14. Flywheel handoff using Stage, Artifact, Ready, Open decisions, Evidence, and Next

Requirements completeness

When a plan was found:

• explicit plan source: unaddressed requirements become P1 manual -> downstream-resolver findings
• inferred plan source: unaddressed requirements become P3 advisory -> human findings
• missing red/green/refactor evidence for a plan unit marked tdd becomes a testing or requirements-completeness finding unless an explicit exception was recorded

Omit the section entirely when no plan was found.

Format verification

Before delivering the interactive report, verify the findings sections use pipe-delimited table rows (| # | File | Issue | ... |).

Headless Output Format

In mode:headless, replace the interactive report with this structured text envelope:

Code review complete (headless mode).

Scope: <scope-line>
Intent: <intent-summary>
Reviewers: <reviewer-list with conditional justifications>
Verdict: <Ready to merge | Ready with fixes | Not ready>
Artifact: .context/flywheel/review/<run-id>/

Applied N safe_auto fixes.

Gated-auto findings (concrete fix, changes behavior/contracts):

[P1][gated_auto -> downstream-resolver][needs-verification] File: <file:line> -- <title> (<reviewer>, confidence <N>)
  Why: <why_it_matters>
  Suggested fix: <suggested_fix or "none">
  Evidence: <evidence[0]>
  Evidence: <evidence[1]>

Manual findings (actionable, needs handoff):

[P1][manual -> downstream-resolver] File: <file:line> -- <title> (<reviewer>, confidence <N>)
  Why: <why_it_matters>
  Evidence: <evidence[0]>

Advisory findings (report-only):

[P2][advisory -> human] File: <file:line> -- <title> (<reviewer>, confidence <N>)
  Why: <why_it_matters>

Pre-existing issues:
[P2][gated_auto -> downstream-resolver] File: <file:line> -- <title> (<reviewer>, confidence <N>)
  Why: <why_it_matters>

Residual risks:
- <risk>

Learnings & Past Solutions:
- <learning>

Agent-Native Gaps:
- <gap description>

Service Readiness Notes:
- <readiness note>

Schema Drift Check:
- <drift status>

Deployment Notes:
- <deployment note>

Testing gaps:
- <gap>

Coverage:
- Suppressed: <N> findings below 0.60 confidence (P0 at 0.50+ retained)
- Untracked files excluded: <file1>, <file2>
- Failed reviewers: <reviewer>

Review complete

Headless detail enrichment rules:

• Why: and Evidence: come from reviewer artifact files on disk.
• Suggested fix: comes from the compact reviewer return.
• Match artifact detail by file + line_bucket(line, +/-3) and then by normalized title as a tiebreaker.
• If no artifact match exists, omit Why: and Evidence: for that finding and note the gap in Coverage.

Quality Gates

Before delivering the review, verify:

1. every finding is actionable
2. each finding was checked against surrounding code rather than skimmed
3. severity is calibrated
4. cited line numbers are accurate
5. protected artifacts are respected
6. findings do not duplicate obvious linter or formatter output

After Review

Step 1: Build Action Sets

• Clean review: zero findings after suppression and pre-existing separation
• Fixer queue: final findings routed to safe_auto -> review-fixer
• Residual actionable queue: unresolved gated_auto or manual findings owned by downstream-resolver
• Report-only queue: advisory findings and anything owned by human or release

Step 2: Choose Policy By Mode

Interactive

• Apply safe_auto -> review-fixer findings automatically.
• Ask a policy question by calling the exact host question tool named in the host interaction contract only when that tool is available and gated_auto or manual findings remain.
• If only manual findings remain, offer residual-work vs report-only choices.
• If gated_auto findings remain, offer approval, residual-work, or report-only choices.

Autofix

• Ask no questions.
• Apply only safe_auto -> review-fixer.
• Leave everything else unresolved.

Report-only

• Ask no questions.
• Build no fixer queue.
• Stop after synthesis.

Headless

• Ask no questions.
• Apply only safe_auto -> review-fixer in a single pass.
• Stop after artifact emission and structured text output.

Step 3: Apply Fixes With One Fixer And Bounded Rounds

• Use exactly one fixer subagent for the current fixer queue only when the platform supports delegated fixing and the active host policy permits it. Otherwise apply the same approved fixer queue inline before re-review.
• Re-review only the changed scope after fixes land.
• Bound the loop with max_rounds: 2.
• If any applied finding has requires_verification: true, the round is not complete until the targeted verification runs.

Step 4: Emit Artifacts And Downstream Handoff

In interactive, autofix, and headless modes, write a per-run artifact under:

.context/flywheel/review/<run-id>/

Include:

• synthesized findings
• applied fixes
• residual actionable work
• advisory-only outputs

Also write metadata.json with at least:

{
  "run_id": "<run-id>",
  "branch": "<git branch --show-current at dispatch time>",
  "head_sha": "<git rev-parse HEAD at dispatch time>",
  "verdict": "<Ready to merge | Ready with fixes | Not ready>",
  "completed_at": "<ISO 8601 UTC timestamp>"
}

In autofix mode, create durable todo files only for unresolved actionable findings whose final owner is downstream-resolver.

If a shared evidence bundle already exists, or if this review is clearly feeding $fw:commit, read ../commit/references/evidence-bundle.md and append one short review entry to:

.context/flywheel/evidence/<bundle-id>/summary.md

Record only what later stages need:

• review verdict
• review artifact path
• any PR-safe summary of blocking or residual findings

Keep full reviewer detail in .context/flywheel/review/<run-id>/ and link to it from the shared bundle instead of duplicating large findings payloads.

Step 5: Final Next Steps

Interactive mode only:

• PR mode: offer $fw:commit to push and refresh the PR, or Exit
• Feature-branch mode: offer $fw:commit, Continue without finishing the branch, or Exit
• Base/default-branch mode: offer Continue or Exit
• If the diff changes browser-visible behavior and no fresh acceptance proof was captured yet, offer $fw:browser-test before $fw:commit.
• If the diff is runtime-risky and rollout posture is still unresolved, offer $fw:rollout before $fw:commit.
• If the dominant residual work is performance, throughput, build-time, or cost tuning rather than correctness, offer $fw:optimize as the next handoff.

Autofix, report-only, and headless modes stop after report, artifact emission, and residual-work handoff.

Fallback

If the platform does not support parallel subagents, run reviewers sequentially. Keep the same stages, merge pipeline, and output format.

Included References

Reviewer Registry

@./references/reviewer-registry.yaml

Persona Loading Guide

@./references/persona-loading.md

Stack Pack Index

@./references/stack-packs/index.yaml

Subagent Template

@./references/subagent-template.md

Diff Scope Rules

@./references/diff-scope.md

Findings Schema

@./references/findings-schema.json

Review Output Template

@./references/review-output-template.md

Evidence Bundle

@../commit/references/evidence-bundle.md