@fro.bot/systematic 2.0.3 → 2.1.0

package/skills/ce-review/SKILL.md

@@ -1,559 +1,520 @@
 ---
 name: ce:review
-description: Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and worktrees
-argument-hint: '[PR number, GitHub URL, branch name, or latest] [--serial]'
+description: Structured code review using tiered persona agents, confidence-gated findings, and a merge/dedup pipeline. Use when reviewing code changes before creating a PR.
+argument-hint: '[mode:autofix|mode:report-only] [PR number, GitHub URL, or branch name]'
 ---
 
-# Review Command
+# Code Review
 
-<command_purpose> Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and Git worktrees for deep local inspection. </command_purpose>
+Reviews code changes using dynamically selected reviewer personas. Spawns parallel sub-agents that return structured JSON, then merges and deduplicates findings into a single report.
 
-## Introduction
+## When to Use
 
-<role>Senior Code Review Architect with expertise in security, performance, architecture, and quality assurance</role>
+- Before creating a PR
+- After completing a task during iterative implementation
+- When feedback is needed on any code changes
+- Can be invoked standalone
+- Can run as a read-only or autofix review step inside larger workflows
 
-## Prerequisites
+## Mode Detection
 
-<requirements>
-- Git repository with GitHub CLI (`gh`) installed and authenticated
-- Clean main/master branch
-- Proper permissions to create worktrees and access the repository
-- For document reviews: Path to a markdown file or document
-</requirements>
+Check `$ARGUMENTS` for `mode:autofix` or `mode:report-only`. If either token is present, strip it from the remaining arguments before interpreting the rest as the PR number, GitHub URL, or branch name.
 
-## Main Tasks
+| Mode | When | Behavior |
+|------|------|----------|
+| **Interactive** (default) | No mode token present | Review, present findings, ask for policy decisions when needed, and optionally continue into fix/push/PR next steps |
+| **Autofix** | `mode:autofix` in arguments | No user interaction. Review, apply only policy-allowed `safe_auto` fixes, re-review in bounded rounds, write a run artifact, and emit residual downstream work when needed |
+| **Report-only** | `mode:report-only` in arguments | Strictly read-only. Review and report only, then stop with no edits, artifacts, todos, commits, pushes, or PR actions |
 
-### 1. Determine Review Target & Setup (ALWAYS FIRST)
+### Autofix mode rules
 
-<review_target> #$ARGUMENTS </review_target>
+- **Skip all user questions.** Never pause for approval or clarification once scope has been established.
+- **Apply only `safe_auto -> review-fixer` findings.** Leave `gated_auto`, `manual`, `human`, and `release` work unresolved.
+- **Write a run artifact** under `.context/systematic/ce-review/<run-id>/` summarizing findings, applied fixes, residual actionable work, and advisory outputs.
+- **Create durable todo files only for unresolved actionable findings** whose final owner is `downstream-resolver`. Load the `todo-create` skill for the canonical directory path and naming convention.
+- **Never commit, push, or create a PR** from autofix mode. Parent workflows own those decisions.
 
-<thinking>
-First, I need to determine the review target type and set up the code for analysis.
-</thinking>
+### Report-only mode rules
 
-#### Immediate Actions
+- **Skip all user questions.** Infer intent conservatively if the diff metadata is thin.
+- **Never edit files or externalize work.** Do not write `.context/systematic/ce-review/<run-id>/`, do not create todo files, and do not commit, push, or create a PR.
+- **Safe for parallel read-only verification.** `mode:report-only` is the only mode that is safe to run concurrently with browser testing on the same checkout.
+- **Do not switch the shared checkout.** If the caller passes an explicit PR or branch target, `mode:report-only` must run in an isolated checkout/worktree or stop instead of running `gh pr checkout` / `git checkout`.
+- **Do not overlap mutating review with browser testing on the same checkout.** If a future orchestrator wants fixes, run the mutating review phase after browser testing or in an isolated checkout/worktree.
 
-<task_list>
+## Severity Scale
 
-- [ ] Determine review type: PR number (numeric), GitHub URL, file path (.md), or empty (current branch)
-- [ ] Check current git branch
-- [ ] If ALREADY on the target branch (PR branch, requested branch name, or the branch already checked out for review) → proceed with analysis on current branch
-- [ ] If DIFFERENT branch than the review target → offer to use worktree: "Use git-worktree skill for isolated Call `skill: git-worktree` with branch name"
-- [ ] Fetch PR metadata using `gh pr view --json` for title, body, files, linked issues
-- [ ] Set up language-specific analysis tools
-- [ ] Prepare security scanning environment
-- [ ] Make sure we are on the branch we are reviewing. Use gh pr checkout to switch to the branch or manually checkout the branch.
+All reviewers use P0-P3:
 
-Ensure that the code is ready for analysis (either in worktree or on current branch). ONLY then proceed to the next step.
+| Level | Meaning | Action |
+|-------|---------|--------|
+| **P0** | Critical breakage, exploitable vulnerability, data loss/corruption | Must fix before merge |
+| **P1** | High-impact defect likely hit in normal usage, breaking contract | Should fix |
+| **P2** | Moderate issue with meaningful downside (edge case, perf regression, maintainability trap) | Fix if straightforward |
+| **P3** | Low-impact, narrow scope, minor improvement | User's discretion |
 
-</task_list>
+## Action Routing
 
-#### Protected Artifacts
+Severity answers **urgency**. Routing answers **who acts next** and **whether this skill may mutate the checkout**.
 
-<protected_artifacts>
-The following paths are systematic pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent:
+| `autofix_class` | Default owner | Meaning |
+|-----------------|---------------|---------|
+| `safe_auto` | `review-fixer` | Local, deterministic fix suitable for the in-skill fixer when the current mode allows mutation |
+| `gated_auto` | `downstream-resolver` or `human` | Concrete fix exists, but it changes behavior, contracts, permissions, or another sensitive boundary that should not be auto-applied by default |
+| `manual` | `downstream-resolver` or `human` | Actionable work that should be handed off rather than fixed in-skill |
+| `advisory` | `human` or `release` | Report-only output such as learnings, rollout notes, or residual risk |
 
-- `docs/brainstorms/*-requirements.md` — Requirements documents created by `/ce:brainstorm`. These are the product-definition artifacts that planning depends on.
-- `docs/plans/*.md` — Plan files created by `/ce:plan`. These are living documents that track implementation progress (checkboxes are checked off by `/ce:work`).
-- `docs/solutions/*.md` — Solution documents created during the pipeline.
+Routing rules:
 
-If a review agent flags any file in these directories for cleanup or removal, discard that finding during synthesis. Do not create a todo for it.
-</protected_artifacts>
+- **Synthesis owns the final route.** Persona-provided routing metadata is input, not the last word.
+- **Choose the more conservative route on disagreement.** A merged finding may move from `safe_auto` to `gated_auto` or `manual`, but never the other way without stronger evidence.
+- **Only `safe_auto -> review-fixer` enters the in-skill fixer queue automatically.**
+- **`requires_verification: true` means a fix is not complete without targeted tests, a focused re-review, or operational validation.**
 
-#### Load Review Agents
+## Reviewers
 
-Read `systematic.local.md` in the project root. If found, use `review_agents` from YAML frontmatter. If the markdown body contains review context, pass it to each agent as additional instructions.
+13 reviewer personas in layered conditionals, plus CE-specific agents. See [persona-catalog.md](./references/persona-catalog.md) for the full catalog.
 
-If no settings file exists, invoke the `setup` skill to create one. Then read the newly created file and continue.
+**Always-on (every review):**
 
-#### Choose Execution Mode
+| Agent | Focus |
+|-------|-------|
+| `systematic:review:correctness-reviewer` | Logic errors, edge cases, state bugs, error propagation |
+| `systematic:review:testing-reviewer` | Coverage gaps, weak assertions, brittle tests |
+| `systematic:review:maintainability-reviewer` | Coupling, complexity, naming, dead code, abstraction debt |
+| `systematic:review:agent-native-reviewer` | Verify new features are agent-accessible |
+| `systematic:research:learnings-researcher` | Search docs/solutions/ for past issues related to this PR |
 
-<execution_mode>
+**Cross-cutting conditional (selected per diff):**
 
-Before launching review agents, check for context constraints:
+| Agent | Select when diff touches... |
+|-------|---------------------------|
+| `systematic:review:security-reviewer` | Auth, public endpoints, user input, permissions |
+| `systematic:review:performance-reviewer` | DB queries, data transforms, caching, async |
+| `systematic:review:api-contract-reviewer` | Routes, serializers, type signatures, versioning |
+| `systematic:review:data-migrations-reviewer` | Migrations, schema changes, backfills |
+| `systematic:review:reliability-reviewer` | Error handling, retries, timeouts, background jobs |
 
-**If `--serial` flag is passed OR conversation is in a long session:**
+**Stack-specific conditional (selected per diff):**
 
-Run agents ONE AT A TIME in sequence. Wait for each agent to complete before starting the next. This uses less context but takes longer.
+| Agent | Select when diff touches... |
+|-------|---------------------------|
+| `systematic:review:dhh-rails-reviewer` | Rails architecture, service objects, session/auth choices, or Hotwire-vs-SPA boundaries |
+| `systematic:review:kieran-rails-reviewer` | Rails application code where conventions, naming, and maintainability are in play |
+| `systematic:review:kieran-python-reviewer` | Python modules, endpoints, scripts, or services |
+| `systematic:review:kieran-typescript-reviewer` | TypeScript components, services, hooks, utilities, or shared types |
+| `systematic:review:julik-frontend-races-reviewer` | Stimulus/Turbo controllers, DOM events, timers, animations, or async UI flows |
 
-**Default (parallel):**
+**CE conditional (migration-specific):**
 
-Run all agents simultaneously for speed. If you hit context limits, retry with `--serial` flag.
+| Agent | Select when diff includes migration files |
+|-------|------------------------------------------|
+| `systematic:review:schema-drift-detector` | Cross-references schema.rb against included migrations |
+| `systematic:review:deployment-verification-agent` | Produces deployment checklist with SQL verification queries |
 
-**Auto-detect:** If more than 5 review agents are configured, automatically switch to serial mode and inform the user:
-"Running review agents in serial mode (6+ agents configured). Use --parallel to override."
+## Review Scope
 
-</execution_mode>
+Every review spawns all 3 always-on personas plus the 2 CE always-on agents, then adds whichever cross-cutting and stack-specific conditionals fit the diff. The model naturally right-sizes: a small config change triggers 0 conditionals = 5 reviewers. A Rails auth feature might trigger security + reliability + kieran-rails + dhh-rails = 9 reviewers.
 
-#### Parallel Agents to review the PR
+## Protected Artifacts
 
-<parallel_tasks>
+The following paths are systematic pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any reviewer:
 
-**Parallel mode (default for ≤5 agents):**
+- `docs/brainstorms/*` -- requirements documents created by ce:brainstorm
+- `docs/plans/*.md` -- plan files created by ce:plan (living documents with progress checkboxes)
+- `docs/solutions/*.md` -- solution documents created during the pipeline
 
-Run all configured review agents in parallel using task tool. For each agent in the `review_agents` list:
+If a reviewer flags any file in these directories for cleanup or removal, discard that finding during synthesis.
 
-```
-Task {agent-name}(PR content + review context from settings body)
-```
-
-**Serial mode (--serial flag, or auto for 6+ agents):**
-
-Run configured review agents ONE AT A TIME. For each agent in the `review_agents` list, wait for it to complete before starting the next:
-
-```
-For each agent in review_agents:
-  1. Task {agent-name}(PR content + review context)
-  2. Wait for completion
-  3. Collect findings
-  4. Proceed to next agent
-```
-
-Always run these last regardless of mode:
-- task systematic:review:agent-native-reviewer(PR content) - Verify new features are agent-accessible
-- task systematic:research:learnings-researcher(PR content) - Search docs/solutions/ for past issues related to this PR's modules and patterns
-
-</parallel_tasks>
-
-#### Conditional Agents (Run if applicable)
-
-<conditional_agents>
-
-These agents are run ONLY when the PR matches specific criteria. Check the PR files list to determine if they apply:
-
-**MIGRATIONS: If PR contains database migrations, schema.rb, or data backfills:**
-
-- task systematic:review:schema-drift-detector(PR content) - Detects unrelated schema.rb changes by cross-referencing against included migrations (run FIRST)
-- task systematic:review:data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
-- task systematic:review:deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries
-
-**When to run:**
-- PR includes files matching `db/migrate/*.rb` or `db/schema.rb`
-- PR modifies columns that store IDs, enums, or mappings
-- PR includes data backfill scripts or rake tasks
-- PR title/body mentions: migration, backfill, data transformation, ID mapping
-
-**What these agents check:**
-- `schema-drift-detector`: Cross-references schema.rb changes against PR migrations to catch unrelated columns/indexes from local database state
-- `data-migration-expert`: Verifies hard-coded mappings match production reality (prevents swapped IDs), checks for orphaned associations, validates dual-write patterns
-- `deployment-verification-agent`: Produces executable pre/post-deploy checklists with SQL queries, rollback procedures, and monitoring plans
-
-</conditional_agents>
-
-### 2. Ultra-Thinking Deep Dive Phases
-
-<ultrathink_instruction> For each phase below, spend maximum cognitive effort. Think step by step. Consider all angles. Question assumptions. And bring all reviews in a synthesis to the user.</ultrathink_instruction>
+## How to Run
 
-<deliverable>
-Complete system context map with component interactions
-</deliverable>
+### Stage 1: Determine scope
 
-#### Phase 1: Stakeholder Perspective Analysis
+Compute the diff range, file list, and diff. Minimize permission prompts by combining into as few commands as possible.
 
-<thinking_prompt> ULTRA-THINK: Put yourself in each stakeholder's shoes. What matters to them? What are their pain points? </thinking_prompt>
+**If a PR number or GitHub URL is provided as an argument:**
 
-<stakeholder_perspectives>
+If `mode:report-only` is active, do **not** run `gh pr checkout <number-or-url>` on the shared checkout. Tell the caller: "mode:report-only cannot switch the shared checkout to review a PR target. Run it from an isolated worktree/checkout for that PR, or run report-only with no target argument on the already checked out branch." Stop here unless the review is already running in an isolated checkout.
 
-1. **Developer Perspective** <questions>
+First, verify the worktree is clean before switching branches:
 
-   - How easy is this to understand and modify?
-   - Are the APIs intuitive?
-   - Is debugging straightforward?
-   - Can I test this easily? </questions>
-
-2. **Operations Perspective** <questions>
-
-   - How do I deploy this safely?
-   - What metrics and logs are available?
-   - How do I troubleshoot issues?
-   - What are the resource requirements? </questions>
-
-3. **End User Perspective** <questions>
-
-   - Is the feature intuitive?
-   - Are error messages helpful?
-   - Is performance acceptable?
-   - Does it solve my problem? </questions>
-
-4. **Security Team Perspective** <questions>
-
-   - What's the attack surface?
-   - Are there compliance requirements?
-   - How is data protected?
-   - What are the audit capabilities? </questions>
-
-5. **Business Perspective** <questions>
-   - What's the ROI?
-   - Are there legal/compliance risks?
-   - How does this affect time-to-market?
-   - What's the total cost of ownership? </questions> </stakeholder_perspectives>
-
-#### Phase 2: Scenario Exploration
-
-<thinking_prompt> ULTRA-THINK: Explore edge cases and failure scenarios. What could go wrong? How does the system behave under stress? </thinking_prompt>
-
-<scenario_checklist>
-
-- [ ] **Happy Path**: Normal operation with valid inputs
-- [ ] **Invalid Inputs**: Null, empty, malformed data
-- [ ] **Boundary Conditions**: Min/max values, empty collections
-- [ ] **Concurrent Access**: Race conditions, deadlocks
-- [ ] **Scale Testing**: 10x, 100x, 1000x normal load
-- [ ] **Network Issues**: Timeouts, partial failures
-- [ ] **Resource Exhaustion**: Memory, disk, connections
-- [ ] **Security Attacks**: Injection, overflow, DoS
-- [ ] **Data Corruption**: Partial writes, inconsistency
-- [ ] **Cascading Failures**: Downstream service issues </scenario_checklist>
-
-### 3. Multi-Angle Review Perspectives
+```
+git status --porcelain
+```
 
-#### Technical Excellence Angle
+If the output is non-empty, inform the user: "You have uncommitted changes on the current branch. Stash or commit them before reviewing a PR, or use standalone mode (no argument) to review the current branch as-is." Do not proceed with checkout until the worktree is clean.
 
-- Code craftsmanship evaluation
-- Engineering best practices
-- Technical documentation quality
-- Tooling and automation assessment
+Then check out the PR branch so persona agents can read the actual code (not the current checkout):
 
-#### Business Value Angle
+```
+gh pr checkout <number-or-url>
+```
 
-- Feature completeness validation
-- Performance impact on users
-- Cost-benefit analysis
-- Time-to-market considerations
+Then fetch PR metadata. Capture the base branch name and the PR base repository identity, not just the branch name:
 
-#### Risk Management Angle
+```
+gh pr view <number-or-url> --json title,body,baseRefName,headRefName,url
+```
 
-- Security risk assessment
-- Operational risk evaluation
-- Compliance risk verification
-- Technical debt accumulation
+Use the repository portion of the returned PR URL as `<base-repo>` (for example, `marcusrbrown/systematic` from `https://github.com/marcusrbrown/systematic/pull/348`).
 
-#### Team Dynamics Angle
+Then compute a local diff against the PR's base branch so re-reviews also include local fix commits and uncommitted edits. Substitute the PR base branch from metadata (shown here as `<base>`) and the PR base repository identity derived from the PR URL (shown here as `<base-repo>`). Resolve the base ref from the PR's actual base repository, not by assuming `origin` points at that repo:
 
-- Code review etiquette
-- Knowledge sharing effectiveness
-- Collaboration patterns
-- Mentoring opportunities
+```
+PR_BASE_REMOTE=$(git remote -v | awk 'index($2, "github.com:<base-repo>") || index($2, "github.com/<base-repo>") {print $1; exit}')
+if [ -n "$PR_BASE_REMOTE" ]; then PR_BASE_REMOTE_REF="$PR_BASE_REMOTE/<base>"; else PR_BASE_REMOTE_REF=""; fi
+PR_BASE_REF=$(git rev-parse --verify "$PR_BASE_REMOTE_REF" 2>/dev/null || git rev-parse --verify <base> 2>/dev/null || true)
+if [ -z "$PR_BASE_REF" ]; then
+  if [ -n "$PR_BASE_REMOTE_REF" ]; then
+    git fetch --no-tags "$PR_BASE_REMOTE" <base>:refs/remotes/"$PR_BASE_REMOTE"/<base> 2>/dev/null || git fetch --no-tags "$PR_BASE_REMOTE" <base> 2>/dev/null || true
+    PR_BASE_REF=$(git rev-parse --verify "$PR_BASE_REMOTE_REF" 2>/dev/null || git rev-parse --verify <base> 2>/dev/null || true)
+  else
+    if git fetch --no-tags https://github.com/<base-repo>.git <base> 2>/dev/null; then
+      PR_BASE_REF=$(git rev-parse --verify FETCH_HEAD 2>/dev/null || true)
+    fi
+    if [ -z "$PR_BASE_REF" ]; then PR_BASE_REF=$(git rev-parse --verify <base> 2>/dev/null || true); fi
+  fi
+fi
+if [ -n "$PR_BASE_REF" ]; then BASE=$(git merge-base HEAD "$PR_BASE_REF" 2>/dev/null) || BASE=""; else BASE=""; fi
+```
 
-### 4. Simplification and Minimalism Review
+```
+if [ -n "$BASE" ]; then echo "BASE:$BASE" && echo "FILES:" && git diff --name-only $BASE && echo "DIFF:" && git diff -U10 $BASE && echo "UNTRACKED:" && git ls-files --others --exclude-standard; else echo "ERROR: Unable to resolve PR base branch <base> locally. Fetch the base branch and rerun so the review scope stays aligned with the PR."; fi
+```
 
-Run the task systematic:review:code-simplicity-reviewer() to see if we can simplify the code.
+Extract PR title/body, base branch, and PR URL from `gh pr view`, then extract the base marker, file list, diff content, and `UNTRACKED:` list from the local command. Do not use `gh pr diff` as the review scope after checkout -- it only reflects the remote PR state and will miss local fix commits until they are pushed. If the base ref still cannot be resolved from the PR's actual base repository after the fetch attempt, stop instead of falling back to `git diff HEAD`; a PR review without the PR base branch is incomplete.
 
-### 5. Findings Synthesis and Todo Creation Using file-todos Skill
+**If a branch name is provided as an argument:**
 
-<critical_requirement> ALL findings MUST be stored as todo files using the file-todos skill. Load the `file-todos` skill for the canonical directory path, naming convention, and template. Create todo files immediately after synthesis - do NOT present findings for user approval first. </critical_requirement>
+Check out the named branch, then diff it against the base branch. Substitute the provided branch name (shown here as `<branch>`).
 
-#### Step 1: Synthesize All Findings
+If `mode:report-only` is active, do **not** run `git checkout <branch>` on the shared checkout. Tell the caller: "mode:report-only cannot switch the shared checkout to review another branch. Run it from an isolated worktree/checkout for `<branch>`, or run report-only on the current checkout with no target argument." Stop here unless the review is already running in an isolated checkout.
 
-<thinking>
-Consolidate all agent reports into a categorized list of findings.
-Remove duplicates, prioritize by severity and impact.
-</thinking>
+First, verify the worktree is clean before switching branches:
 
-<synthesis_tasks>
+```
+git status --porcelain
+```
 
-- [ ] Collect findings from all parallel agents
-- [ ] Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files
-- [ ] Discard any findings that recommend deleting or gitignoring files in `docs/brainstorms/`, `docs/plans/`, or `docs/solutions/` (see Protected Artifacts above)
-- [ ] Categorize by type: security, performance, architecture, quality, etc.
-- [ ] Assign severity levels: 🔴 CRITICAL (P1), 🟡 IMPORTANT (P2), 🔵 NICE-TO-HAVE (P3)
-- [ ] Remove duplicate or overlapping findings
-- [ ] Estimate effort for each finding (Small/Medium/Large)
+If the output is non-empty, inform the user: "You have uncommitted changes on the current branch. Stash or commit them before reviewing another branch, or provide a PR number instead." Do not proceed with checkout until the worktree is clean.
 
-</synthesis_tasks>
+```
+git checkout <branch>
+```
 
-#### Step 2: Create Todo Files Using file-todos Skill
+Then detect the review base branch before computing the merge-base. When the branch has an open PR, resolve the base ref from the PR's actual base repository (not just `origin`), mirroring the PR-mode logic for fork safety. Fall back to `origin/HEAD`, GitHub metadata, then common branch names:
 
-<critical_instruction> Use the file-todos skill to create todo files for ALL findings immediately. Do NOT present findings one-by-one asking for user approval. Create all todo files in parallel using the skill, then summarize results to user. </critical_instruction>
+```
+REVIEW_BASE_BRANCH=""
+PR_BASE_REPO=""
+if command -v gh >/dev/null 2>&1; then
+  PR_META=$(gh pr view --json baseRefName,url 2>/dev/null || true)
+  if [ -n "$PR_META" ]; then
+    REVIEW_BASE_BRANCH=$(echo "$PR_META" | jq -r '.baseRefName // empty')
+    PR_BASE_REPO=$(echo "$PR_META" | jq -r '.url // empty' | sed -n 's#https://github.com/\([^/]*/[^/]*\)/pull/.*#\1#p')
+  fi
+fi
+if [ -z "$REVIEW_BASE_BRANCH" ]; then REVIEW_BASE_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##'); fi
+if [ -z "$REVIEW_BASE_BRANCH" ] && command -v gh >/dev/null 2>&1; then REVIEW_BASE_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null); fi
+if [ -z "$REVIEW_BASE_BRANCH" ]; then
+  for candidate in main master develop trunk; do
+    if git rev-parse --verify "origin/$candidate" >/dev/null 2>&1 || git rev-parse --verify "$candidate" >/dev/null 2>&1; then
+      REVIEW_BASE_BRANCH="$candidate"
+      break
+    fi
+  done
+fi
+if [ -n "$REVIEW_BASE_BRANCH" ]; then
+  if [ -n "$PR_BASE_REPO" ]; then
+    PR_BASE_REMOTE=$(git remote -v | awk "index(\$2, \"github.com:$PR_BASE_REPO\") || index(\$2, \"github.com/$PR_BASE_REPO\") {print \$1; exit}")
+    if [ -n "$PR_BASE_REMOTE" ]; then
+      git rev-parse --verify "$PR_BASE_REMOTE/$REVIEW_BASE_BRANCH" >/dev/null 2>&1 || git fetch --no-tags "$PR_BASE_REMOTE" "$REVIEW_BASE_BRANCH" 2>/dev/null || true
+      BASE_REF=$(git rev-parse --verify "$PR_BASE_REMOTE/$REVIEW_BASE_BRANCH" 2>/dev/null || true)
+    fi
+  fi
+  if [ -z "$BASE_REF" ]; then
+    git rev-parse --verify "origin/$REVIEW_BASE_BRANCH" >/dev/null 2>&1 || git fetch --no-tags origin "$REVIEW_BASE_BRANCH" 2>/dev/null || true
+    BASE_REF=$(git rev-parse --verify "origin/$REVIEW_BASE_BRANCH" 2>/dev/null || git rev-parse --verify "$REVIEW_BASE_BRANCH" 2>/dev/null || true)
+  fi
+  if [ -n "$BASE_REF" ]; then BASE=$(git merge-base HEAD "$BASE_REF" 2>/dev/null) || BASE=""; else BASE=""; fi
+else BASE=""; fi
+```
 
-**Implementation Options:**
+```
+if [ -n "$BASE" ]; then echo "BASE:$BASE" && echo "FILES:" && git diff --name-only $BASE && echo "DIFF:" && git diff -U10 $BASE && echo "UNTRACKED:" && git ls-files --others --exclude-standard; else echo "ERROR: Unable to resolve review base branch locally. Fetch the base branch and rerun, or provide a PR number so the review scope can be determined from PR metadata."; fi
+```
 
-**Option A: Direct File Creation (Fast)**
+If the branch has an open PR, the detection above uses the PR's base repository to resolve the merge-base, which handles fork workflows correctly. You may still fetch additional PR metadata with `gh pr view` for title, body, and linked issues, but do not fail if no PR exists. If the base branch still cannot be resolved after the detection and fetch attempts, stop instead of falling back to `git diff HEAD`; a branch review without the base branch would only show uncommitted changes and silently miss all committed work.
 
-- Create todo files directly using write tool
-- All findings in parallel for speed
-- Use standard template from the `file-todos` skill's [todo-template.md](../file-todos/assets/todo-template.md)
-- Follow naming convention: `{issue_id}-pending-{priority}-{description}.md`
+**If no argument (standalone on current branch):**
 
-**Option B: Sub-Agents in Parallel (Recommended for Scale)** For large PRs with 15+ findings, use sub-agents to create finding files in parallel:
+Detect the review base branch before computing the merge-base. When the current branch has an open PR, resolve the base ref from the PR's actual base repository (not just `origin`), mirroring the PR-mode logic for fork safety. Fall back to `origin/HEAD`, GitHub metadata, then common branch names:
 
-```bash
-# Launch multiple finding-creator agents in parallel
-task() - Create todos for first finding
-task() - Create todos for second finding
-task() - Create todos for third finding
-etc. for each finding.
+```
+REVIEW_BASE_BRANCH=""
+PR_BASE_REPO=""
+if command -v gh >/dev/null 2>&1; then
+  PR_META=$(gh pr view --json baseRefName,url 2>/dev/null || true)
+  if [ -n "$PR_META" ]; then
+    REVIEW_BASE_BRANCH=$(echo "$PR_META" | jq -r '.baseRefName // empty')
+    PR_BASE_REPO=$(echo "$PR_META" | jq -r '.url // empty' | sed -n 's#https://github.com/\([^/]*/[^/]*\)/pull/.*#\1#p')
+  fi
+fi
+if [ -z "$REVIEW_BASE_BRANCH" ]; then REVIEW_BASE_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##'); fi
+if [ -z "$REVIEW_BASE_BRANCH" ] && command -v gh >/dev/null 2>&1; then REVIEW_BASE_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null); fi
+if [ -z "$REVIEW_BASE_BRANCH" ]; then
+  for candidate in main master develop trunk; do
+    if git rev-parse --verify "origin/$candidate" >/dev/null 2>&1 || git rev-parse --verify "$candidate" >/dev/null 2>&1; then
+      REVIEW_BASE_BRANCH="$candidate"
+      break
+    fi
+  done
+fi
+if [ -n "$REVIEW_BASE_BRANCH" ]; then
+  if [ -n "$PR_BASE_REPO" ]; then
+    PR_BASE_REMOTE=$(git remote -v | awk "index(\$2, \"github.com:$PR_BASE_REPO\") || index(\$2, \"github.com/$PR_BASE_REPO\") {print \$1; exit}")
+    if [ -n "$PR_BASE_REMOTE" ]; then
+      git rev-parse --verify "$PR_BASE_REMOTE/$REVIEW_BASE_BRANCH" >/dev/null 2>&1 || git fetch --no-tags "$PR_BASE_REMOTE" "$REVIEW_BASE_BRANCH" 2>/dev/null || true
+      BASE_REF=$(git rev-parse --verify "$PR_BASE_REMOTE/$REVIEW_BASE_BRANCH" 2>/dev/null || true)
+    fi
+  fi
+  if [ -z "$BASE_REF" ]; then
+    git rev-parse --verify "origin/$REVIEW_BASE_BRANCH" >/dev/null 2>&1 || git fetch --no-tags origin "$REVIEW_BASE_BRANCH" 2>/dev/null || true
+    BASE_REF=$(git rev-parse --verify "origin/$REVIEW_BASE_BRANCH" 2>/dev/null || git rev-parse --verify "$REVIEW_BASE_BRANCH" 2>/dev/null || true)
+  fi
+  if [ -n "$BASE_REF" ]; then BASE=$(git merge-base HEAD "$BASE_REF" 2>/dev/null) || BASE=""; else BASE=""; fi
+else BASE=""; fi
 ```
 
-Sub-agents can:
-
-- Process multiple findings simultaneously
-- Write detailed todo files with all sections filled
-- Organize findings by severity
-- Create comprehensive Proposed Solutions
-- Add acceptance criteria and work logs
-- Complete much faster than sequential processing
+```
+if [ -n "$BASE" ]; then echo "BASE:$BASE" && echo "FILES:" && git diff --name-only $BASE && echo "DIFF:" && git diff -U10 $BASE && echo "UNTRACKED:" && git ls-files --others --exclude-standard; else echo "ERROR: Unable to resolve review base branch locally. Fetch the base branch and rerun, or provide a PR number so the review scope can be determined from PR metadata."; fi
+```
 
-**Execution Strategy:**
+Parse: `BASE:` = merge-base SHA, `FILES:` = file list, `DIFF:` = diff, `UNTRACKED:` = files excluded from review scope because they are not staged. Using `git diff $BASE` (without `..HEAD`) diffs the merge-base against the working tree, which includes committed, staged, and unstaged changes together. If the base branch cannot be resolved after the detection and fetch attempts, stop instead of falling back to `git diff HEAD`; a standalone review without the base branch would only show uncommitted changes and silently miss all committed work on the branch.
 
-1. Synthesize all findings into categories (P1/P2/P3)
-2. Group findings by severity
-3. Launch 3 parallel sub-agents (one per severity level)
-4. Each sub-agent creates its batch of todos using the file-todos skill
-5. Consolidate results and present summary
+**Untracked file handling:** Always inspect the `UNTRACKED:` list, even when `FILES:`/`DIFF:` are non-empty. Untracked files are outside review scope until staged. If the list is non-empty, tell the user which files are excluded. If any of them should be reviewed, stop and tell the user to `git add` them first and rerun. Only continue when the user is intentionally reviewing tracked changes only.
 
-**Process (Using file-todos Skill):**
+### Stage 2: Intent discovery
 
-1. For each finding:
+Understand what the change is trying to accomplish. The source of intent depends on which Stage 1 path was taken:
 
-   - Determine severity (P1/P2/P3)
-   - Write detailed Problem Statement and Findings
-   - Create 2-3 Proposed Solutions with pros/cons/effort/risk
-   - Estimate effort (Small/Medium/Large)
-   - Add acceptance criteria and work log
+**PR/URL mode:** Use the PR title, body, and linked issues from `gh pr view` metadata. Supplement with commit messages from the PR if the body is sparse.
 
-2. Use file-todos skill for structured todo management:
+**Branch mode:** Run `git log --oneline ${BASE}..<branch>` using the resolved merge-base from Stage 1.
 
-   ```bash
-   skill: file-todos
-   ```
+**Standalone (current branch):** Run:
 
-   The skill provides:
+```
+echo "BRANCH:" && git rev-parse --abbrev-ref HEAD && echo "COMMITS:" && git log --oneline ${BASE}..HEAD
+```
 
-   - Template location: the `file-todos` skill's [todo-template.md](../file-todos/assets/todo-template.md)
-   - Naming convention: `{issue_id}-{status}-{priority}-{description}.md`
-   - YAML frontmatter structure: status, priority, issue_id, tags, dependencies
-   - All required sections: Problem Statement, Findings, Solutions, etc.
+Combined with conversation context (plan section summary, PR description, caller-provided description), write a 2-3 line intent summary:
 
-3. Create todo files in parallel:
+```
+Intent: Simplify tax calculation by replacing the multi-tier rate lookup
+with a flat-rate computation. Must not regress edge cases in tax-exempt handling.
+```
 
-   ```bash
-   {next_id}-pending-{priority}-{description}.md
-   ```
+Pass this to every reviewer in their spawn prompt. Intent shapes *how hard each reviewer looks*, not which reviewers are selected.
 
-4. Examples:
+**When intent is ambiguous:**
 
-   ```
-   001-pending-p1-path-traversal-vulnerability.md
-   002-pending-p1-api-response-validation.md
-   003-pending-p2-concurrency-limit.md
-   004-pending-p3-unused-parameter.md
-   ```
+- **Interactive mode:** Ask one question using the platform's interactive question tool (question in OpenCode, request_user_input in Codex): "What is the primary goal of these changes?" Do not spawn reviewers until intent is established.
+- **Autofix/report-only modes:** Infer intent conservatively from the branch name, diff, PR metadata, and caller context. Note the uncertainty in Coverage or Verdict reasoning instead of blocking.
 
-5. Follow template structure from file-todos skill: the `file-todos` skill's [todo-template.md](../file-todos/assets/todo-template.md)
+### Stage 3: Select reviewers
 
-**Todo File Structure (from template):**
+Read the diff and file list from Stage 1. The 3 always-on personas and 2 CE always-on agents are automatic. For each cross-cutting and stack-specific conditional persona in [persona-catalog.md](./references/persona-catalog.md), decide whether the diff warrants it. This is agent judgment, not keyword matching.
 
-Each todo must include:
+Stack-specific personas are additive. A Rails UI change may warrant `kieran-rails` plus `julik-frontend-races`; a TypeScript API diff may warrant `kieran-typescript` plus `api-contract` and `reliability`.
 
-- **YAML frontmatter**: status, priority, issue_id, tags, dependencies
-- **Problem Statement**: What's broken/missing, why it matters
-- **Findings**: Discoveries from agents with evidence/location
-- **Proposed Solutions**: 2-3 options, each with pros/cons/effort/risk
-- **Recommended Action**: (Filled during triage, leave blank initially)
-- **Technical Details**: Affected files, components, database changes
-- **Acceptance Criteria**: Testable checklist items
-- **Work Log**: Dated record with actions and learnings
-- **Resources**: Links to PR, issues, documentation, similar patterns
+For CE conditional agents, check if the diff includes files matching `db/migrate/*.rb`, `db/schema.rb`, or data backfill scripts.
 
-**File naming convention:**
+Announce the team before spawning:
 
 ```
-{issue_id}-{status}-{priority}-{description}.md
-
-Examples:
-- 001-pending-p1-security-vulnerability.md
-- 002-pending-p2-performance-optimization.md
-- 003-pending-p3-code-cleanup.md
+Review team:
+- correctness (always)
+- testing (always)
+- maintainability (always)
+- agent-native-reviewer (always)
+- learnings-researcher (always)
+- security -- new endpoint in routes.rb accepts user-provided redirect URL
+- kieran-rails -- controller and Turbo flow changed in app/controllers and app/views
+- dhh-rails -- diff adds service objects around ordinary Rails CRUD
+- data-migrations -- adds migration 20260303_add_index_to_orders
+- schema-drift-detector -- migration files present
 ```
 
-**Status values:**
-
-- `pending` - New findings, needs triage/decision
-- `ready` - Approved by manager, ready to work
-- `complete` - Work finished
-
-**Priority values:**
-
-- `p1` - Critical (blocks merge, security/data issues)
-- `p2` - Important (should fix, architectural/performance)
-- `p3` - Nice-to-have (enhancements, cleanup)
-
-**Tagging:** Always add `code-review` tag, plus: `security`, `performance`, `architecture`, `rails`, `quality`, etc.
-
-#### Step 3: Summary Report
-
-After creating all todo files, present comprehensive summary:
-
-````markdown
-## ✅ Code Review Complete
+This is progress reporting, not a blocking confirmation.
 
-**Review Target:** PR #XXXX - [PR Title] **Branch:** [branch-name]
+### Stage 4: Spawn sub-agents
 
-### Findings Summary:
+Spawn each selected persona reviewer as a parallel sub-agent using the template in [subagent-template.md](./references/subagent-template.md). Each persona sub-agent receives:
 
-- **Total Findings:** [X]
-- **🔴 CRITICAL (P1):** [count] - BLOCKS MERGE
-- **🟡 IMPORTANT (P2):** [count] - Should Fix
-- **🔵 NICE-TO-HAVE (P3):** [count] - Enhancements
+1. Their persona file content (identity, failure modes, calibration, suppress conditions)
+2. Shared diff-scope rules from [diff-scope.md](./references/diff-scope.md)
+3. The JSON output contract from [findings-schema.json](./references/findings-schema.json)
+4. Review context: intent summary, file list, diff
 
-### Created Todo Files:
+Persona sub-agents are **read-only**: they review and return structured JSON. They do not edit files or propose refactors.
 
-**P1 - Critical (BLOCKS MERGE):**
+Read-only here means **non-mutating**, not "no shell access." Reviewer sub-agents may use non-mutating inspection commands when needed to gather evidence or verify scope, including read-oriented `git` / `gh` usage such as `git diff`, `git show`, `git blame`, `git log`, and `gh pr view`. They must not edit files, change branches, commit, push, create PRs, or otherwise mutate the checkout or repository state.
 
-- `001-pending-p1-{finding}.md` - {description}
-- `002-pending-p1-{finding}.md` - {description}
+Each persona sub-agent returns JSON matching [findings-schema.json](./references/findings-schema.json):
 
-**P2 - Important:**
+```json
+{
+  "reviewer": "security",
+  "findings": [...],
+  "residual_risks": [...],
+  "testing_gaps": [...]
+}
+```
 
-- `003-pending-p2-{finding}.md` - {description}
-- `004-pending-p2-{finding}.md` - {description}
+**CE always-on agents** (agent-native-reviewer, learnings-researcher) are dispatched as standard Agent calls in parallel with the persona agents. Give them the same review context bundle the personas receive: entry mode, any PR metadata gathered in Stage 1, intent summary, review base branch name when known, `BASE:` marker, file list, diff, and `UNTRACKED:` scope notes. Do not invoke them with a generic "review this" prompt. Their output is unstructured and synthesized separately in Stage 6.
 
-**P3 - Nice-to-Have:**
+**CE conditional agents** (schema-drift-detector, deployment-verification-agent) are also dispatched as standard Agent calls when applicable. Pass the same review context bundle plus the applicability reason (for example, which migration files triggered the agent). For schema-drift-detector specifically, pass the resolved review base branch explicitly so it never assumes `main`. Their output is unstructured and must be preserved for Stage 6 synthesis just like the CE always-on agents.
 
-- `005-pending-p3-{finding}.md` - {description}
+### Stage 5: Merge findings
 
-### Review Agents Used:
+Convert multiple reviewer JSON payloads into one deduplicated, confidence-gated finding set.
 
-- kieran-rails-reviewer
-- security-sentinel
-- performance-oracle
-- architecture-strategist
-- agent-native-reviewer
-- [other agents]
+1. **Validate.** Check each output against the schema. Drop malformed findings (missing required fields). Record the drop count.
+2. **Confidence gate.** Suppress findings below 0.60 confidence. Record the suppressed count. This matches the persona instructions: findings below 0.60 are noise and should not survive synthesis.
+3. **Deduplicate.** Compute fingerprint: `normalize(file) + line_bucket(line, +/-3) + normalize(title)`. When fingerprints match, merge: keep highest severity, keep highest confidence with strongest evidence, union evidence, note which reviewers flagged it.
+4. **Separate pre-existing.** Pull out findings with `pre_existing: true` into a separate list.
+5. **Normalize routing.** For each merged finding, set the final `autofix_class`, `owner`, and `requires_verification`. If reviewers disagree, keep the most conservative route. Synthesis may narrow a finding from `safe_auto` to `gated_auto` or `manual`, but must not widen it without new evidence.
+6. **Partition the work.** Build three sets:
+   - in-skill fixer queue: only `safe_auto -> review-fixer`
+   - residual actionable queue: unresolved `gated_auto` or `manual` findings whose owner is `downstream-resolver`
+   - report-only queue: `advisory` findings plus anything owned by `human` or `release`
+7. **Sort.** Order by severity (P0 first) -> confidence (descending) -> file path -> line number.
+8. **Collect coverage data.** Union residual_risks and testing_gaps across reviewers.
+9. **Preserve CE agent artifacts.** Keep the learnings, agent-native, schema-drift, and deployment-verification outputs alongside the merged finding set. Do not drop unstructured agent output just because it does not match the persona JSON schema.
 
-### Next Steps:
+### Stage 6: Synthesize and present
 
-1. **Address P1 Findings**: CRITICAL - must be fixed before merge
+Assemble the final report using the template in [review-output-template.md](./references/review-output-template.md):
 
-   - Review each P1 todo in detail
-   - Implement fixes or request exemption
-   - Verify fixes before merging PR
+1. **Header.** Scope, intent, mode, reviewer team with per-conditional justifications.
+2. **Findings.** Grouped by severity (P0, P1, P2, P3). Each finding shows file, issue, reviewer(s), confidence, and synthesized route.
+3. **Applied Fixes.** Include only if a fix phase ran in this invocation.
+4. **Residual Actionable Work.** Include when unresolved actionable findings were handed off or should be handed off.
+5. **Pre-existing.** Separate section, does not count toward verdict.
+6. **Learnings & Past Solutions.** Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files.
+7. **Agent-Native Gaps.** Surface agent-native-reviewer results. Omit section if no gaps found.
+8. **Schema Drift Check.** If schema-drift-detector ran, summarize whether drift was found. If drift exists, list the unrelated schema objects and the required cleanup command. If clean, say so briefly.
+9. **Deployment Notes.** If deployment-verification-agent ran, surface the key Go/No-Go items: blocking pre-deploy checks, the most important verification queries, rollback caveats, and monitoring focus areas. Keep the checklist actionable rather than dropping it into Coverage.
+10. **Coverage.** Suppressed count, residual risks, testing gaps, failed/timed-out reviewers, and any intent uncertainty carried by non-interactive modes.
+11. **Verdict.** Ready to merge / Ready with fixes / Not ready. Fix order if applicable.
 
-2. **Triage All Todos**:
-   ```bash
-   ls .context/systematic/todos/*-pending-*.md todos/*-pending-*.md 2>/dev/null  # View all pending todos
-   /triage                  # Use slash command for interactive triage
-   ```
+Do not include time estimates.
 
-3. **Work on Approved Todos**:
+## Quality Gates
 
-   ```bash
-   /resolve-todo-parallel  # Fix all approved items efficiently
-   ```
+Before delivering the review, verify:
 
-4. **Track Progress**:
-   - Rename file when status changes: pending → ready → complete
-   - Update Work Log as you work
-   - Commit review findings and status updates
+1. **Every finding is actionable.** Re-read each finding. If it says "consider", "might want to", or "could be improved" without a concrete fix, rewrite it with a specific action. Vague findings waste engineering time.
+2. **No false positives from skimming.** For each finding, verify the surrounding code was actually read. Check that the "bug" isn't handled elsewhere in the same function, that the "unused import" isn't used in a type annotation, that the "missing null check" isn't guarded by the caller.
+3. **Severity is calibrated.** A style nit is never P0. A SQL injection is never P3. Re-check every severity assignment.
+4. **Line numbers are accurate.** Verify each cited line number against the file content. A finding pointing to the wrong line is worse than no finding.
+5. **Protected artifacts are respected.** Discard any findings that recommend deleting or gitignoring files in `docs/brainstorms/`, `docs/plans/`, or `docs/solutions/`.
+6. **Findings don't duplicate linter output.** Don't flag things the project's linter/formatter would catch (missing semicolons, wrong indentation). Focus on semantic issues.
 
-### Severity Breakdown:
+## Language-Aware Conditionals
 
-**🔴 P1 (Critical - Blocks Merge):**
+This skill uses stack-specific reviewer agents when the diff clearly warrants them. Keep those agents opinionated. They are not generic language checkers; they add a distinct review lens on top of the always-on and cross-cutting personas.
 
-- Security vulnerabilities
-- Data corruption risks
-- Breaking changes
-- Critical architectural issues
+Do not spawn them mechanically from file extensions alone. The trigger is meaningful changed behavior, architecture, or UI state in that stack.
 
-**🟡 P2 (Important - Should Fix):**
+## After Review
 
-- Performance issues
-- Significant architectural concerns
-- Major code quality problems
-- Reliability issues
+### Mode-Driven Post-Review Flow
 
-**🔵 P3 (Nice-to-Have):**
+After presenting findings and verdict (Stage 6), route the next steps by mode. Review and synthesis stay the same in every mode; only mutation and handoff behavior changes.
 
-- Minor improvements
-- Code cleanup
-- Optimization opportunities
-- Documentation updates
-````
+#### Step 1: Build the action sets
 
-### 6. End-to-End Testing (Optional)
+- **Clean review** means zero findings after suppression and pre-existing separation. Skip the fix/handoff phase when the review is clean.
+- **Fixer queue:** final findings routed to `safe_auto -> review-fixer`.
+- **Residual actionable queue:** unresolved `gated_auto` or `manual` findings whose final owner is `downstream-resolver`.
+- **Report-only queue:** `advisory` findings and any outputs owned by `human` or `release`.
+- **Never convert advisory-only outputs into fix work or todos.** Deployment notes, residual risks, and release-owned items stay in the report.
 
-<detect_project_type>
+#### Step 2: Choose policy by mode
 
-**First, detect the project type from PR files:**
+**Interactive mode**
 
-| Indicator | Project Type |
-|-----------|--------------|
-| `*.xcodeproj`, `*.xcworkspace`, `Package.swift` (iOS) | iOS/macOS |
-| `Gemfile`, `package.json`, `app/views/*`, `*.html.*` | Web |
-| Both iOS files AND web files | Hybrid (test both) |
+- Ask a single policy question only when actionable work exists.
+- Recommended default:
 
-</detect_project_type>
+  ```
+  What should I do with the actionable findings?
+  1. Apply safe_auto fixes and leave the rest as residual work (Recommended)
+  2. Apply safe_auto fixes only
+  3. Review report only
+  ```
 
-<offer_testing>
+- Tailor the prompt to the actual action sets. If the fixer queue is empty, do not offer "Apply safe_auto fixes" options. Ask whether to externalize the residual actionable work or keep the review report-only instead.
+- Only include `gated_auto` findings in the fixer queue after the user explicitly approves the specific items. Do not widen the queue based on severity alone.
 
-After presenting the Summary Report, offer appropriate testing based on project type:
+**Autofix mode**
 
-**For Web Projects:**
-```markdown
-**"Want to run browser tests on the affected pages?"**
-1. Yes - run `/test-browser`
-2. No - skip
-```
+- Ask no questions.
+- Apply only the `safe_auto -> review-fixer` queue.
+- Leave `gated_auto`, `manual`, `human`, and `release` items unresolved.
+- Prepare residual work only for unresolved actionable findings whose final owner is `downstream-resolver`.
 
-**For iOS Projects:**
-```markdown
-**"Want to run Xcode simulator tests on the app?"**
-1. Yes - run `/xcode-test`
-2. No - skip
-```
+**Report-only mode**
 
-**For Hybrid Projects (e.g., Rails + Hotwire Native):**
-```markdown
-**"Want to run end-to-end tests?"**
-1. Web only - run `/test-browser`
-2. iOS only - run `/xcode-test`
-3. Both - run both commands
-4. No - skip
-```
+- Ask no questions.
+- Do not build a fixer queue.
+- Do not create residual todos or `.context` artifacts.
+- Stop after Stage 6. Everything remains in the report.
 
-</offer_testing>
+#### Step 3: Apply fixes with one fixer and bounded rounds
 
-#### If User Accepts Web Testing
+- Spawn exactly one fixer subagent for the current fixer queue in the current checkout. That fixer applies all approved changes and runs the relevant targeted tests in one pass against a consistent tree.
+- Do not fan out multiple fixers against the same checkout. Parallel fixers require isolated worktrees/branches and deliberate mergeback.
+- Re-review only the changed scope after fixes land.
+- Bound the loop with `max_rounds: 2`. If issues remain after the second round, stop and hand them off as residual work or report them as unresolved.
+- If any applied finding has `requires_verification: true`, the round is incomplete until the targeted verification runs.
+- Do not start a mutating review round concurrently with browser testing on the same checkout. Future orchestrators that want both must either run `mode:report-only` during the parallel phase or isolate the mutating review in its own checkout/worktree.
 
-Spawn a subagent to run browser tests (preserves main context):
+#### Step 4: Emit artifacts and downstream handoff
 
-```
-Task general-purpose("Run /test-browser for PR #[number]. Test all affected pages, check for console errors, handle failures by creating todos and fixing.")
-```
-
-The subagent will:
-1. Identify pages affected by the PR
-2. Navigate to each page and capture snapshots (using Playwright MCP or agent-browser CLI)
-3. Check for console errors
-4. Test critical interactions
-5. Pause for human verification on OAuth/email/payment flows
-6. Create P1 todos for any failures
-7. Fix and retry until all tests pass
+- In interactive and autofix modes, write a per-run artifact under `.context/systematic/ce-review/<run-id>/` containing:
+  - synthesized findings
+  - applied fixes
+  - residual actionable work
+  - advisory-only outputs
+- In autofix mode, create durable todo files only for unresolved actionable findings whose final owner is `downstream-resolver`. Load the `todo-create` skill for the canonical directory path, naming convention, YAML frontmatter structure, and template. Each todo should map the finding's severity to the todo priority (`P0`/`P1` -> `p1`, `P2` -> `p2`, `P3` -> `p3`) and set `status: ready` since these findings have already been triaged by synthesis.
+- Do not create todos for `advisory` findings, `owner: human`, `owner: release`, or protected-artifact cleanup suggestions.
+- If only advisory outputs remain, create no todos.
+- Interactive mode may offer to externalize residual actionable work after fixes, but it is not required to finish the review.
 
-**Standalone:** `/test-browser [PR number]`
+#### Step 5: Final next steps
 
-#### If User Accepts iOS Testing
+**Interactive mode only:** after the fix-review cycle completes (clean verdict or the user chose to stop), offer next steps based on the entry mode. Reuse the resolved review base/default branch from Stage 1 when known; do not hard-code only `main`/`master`.
 
-Spawn a subagent to run Xcode tests (preserves main context):
+- **PR mode (entered via PR number/URL):**
+  - **Push fixes** -- push commits to the existing PR branch
+  - **Exit** -- done for now
+- **Branch mode (feature branch with no PR, and not the resolved review base/default branch):**
+  - **Create a PR (Recommended)** -- push and open a pull request
+  - **Continue without PR** -- stay on the branch
+  - **Exit** -- done for now
+- **On the resolved review base/default branch:**
+  - **Continue** -- proceed with next steps
+  - **Exit** -- done for now
 
-```
-Task general-purpose("Run /xcode-test for scheme [name]. Build for simulator, install, launch, take screenshots, check for crashes.")
-```
+If "Create a PR": first publish the branch with `git push --set-upstream origin HEAD`, then use `gh pr create` with a title and summary derived from the branch changes.
+If "Push fixes": push the branch with `git push` to update the existing PR.
 
-The subagent will:
-1. Verify XcodeBuildMCP is installed
-2. Discover project and schemes
-3. Build for iOS Simulator
-4. Install and launch app
-5. Take screenshots of key screens
-6. Capture console logs for errors
-7. Pause for human verification (Sign in with Apple, push, IAP)
-8. Create P1 todos for any failures
-9. Fix and retry until all tests pass
+**Autofix and report-only modes:** stop after the report, artifact emission, and residual-work handoff. Do not commit, push, or create a PR.
 
-**Standalone:** `/xcode-test [scheme]`
+## Fallback
 
-### Important: P1 Findings Block Merge
+If the platform doesn't support parallel sub-agents, run reviewers sequentially. Everything else (stages, output format, merge pipeline) stays the same.
 
-Any **🔴 P1 (CRITICAL)** findings must be addressed before merging the PR. Present these prominently and ensure they're resolved before accepting the PR.