/arc:review

<arc_runtime> This workflow requires the full Arc bundle, not a prompts-only install.

Paths in this skill use these conventions:

• agents/..., references/..., disciplines/..., templates/..., scripts/..., rules/..., skills/<name>/... are Arc-owned files at the plugin root. Resolve the plugin root from this skill's filesystem location — it's the directory containing agents/ and skills/.
• ./... is local to this skill's directory.
• .ruler/..., docs/..., src/..., or any project-relative path refers to the user's project repository. </arc_runtime>

<scope_discipline>

Scope Discipline

Reviewers must respect the plan's scope. This is non-negotiable:

• Do not silently argue for less work. If you think the plan is overbuilt, raise it once in a "Scope Check" early in the review. After the user responds, commit to their decision.
• Do not sneak in additional scope. Don't suggest features, enhancements, or "while you're at it" additions beyond what the plan covers.
• Your job is to make this plan succeed, not to lobby for a different plan. Once scope is agreed, optimize within it — find bugs, catch edge cases, improve the architecture — but don't re-litigate what gets built.
• Include this principle in every reviewer prompt: "Respect the plan's scope. Flag scope concerns once, then commit to making the plan succeed." </scope_discipline>

Phase 0: Check for Specific Reviewer

If argument provided (e.g., daniel-product-engineer):

• Look for agents/review/{argument}.md
• If found → use only this reviewer, skip Phase 2 detection
• If not found → list available reviewers from agents/review/ and ask user to pick

Available reviewers:

• daniel-product-engineer — Type safety, UI completeness, React patterns
• lee-nextjs-engineer — Next.js App Router, server-first architecture
• senior-engineer — Asymmetric strictness, review discipline
• architecture-engineer — System design, component boundaries
• performance-engineer — Bottlenecks, scalability
• security-engineer — Vulnerabilities, OWASP
• data-engineer — Migrations, transactions
• mastra-agent-engineer — Mastra, agents, workflows, tools, memory/RAG, MCP, agent-readable surfaces

Phase 1: Find the Plan

Check if plan file path provided as argument:

• If yes → read that file and proceed to Phase 2
• If no → search for plans

Search strategy:

1. Check conversation context first — Look for Claude Code plan mode output

   • Look back through recent conversation messages
   • Search for plan structure markers:
     • "# Plan" or "## Plan" headings
     • "Implementation Steps" sections
     • Task lists with implementation details
     • Step-by-step procedures
   • If found → extract the plan content and proceed to Phase 2

2. Search Arc plan folders — Look for plan files

   Use Glob tool: docs/arc/plans/*.md Fallback: docs/plans/*.md

   • Sort results by modification time (newest first)
   • Show all plan/spec files (feature specs, implementation plans, etc.)

3. Present options if multiple found:

   • List up to 5 most recent plans
   • Show: filename, modification date, brief preview
   • Ask user: "Which plan should I review?"

4. If no plans found:

   • "I couldn't find a plan to review. Can you point me to a plan file, paste the plan, or describe the approach you'd like reviewed?"

Once plan located:

• Store the plan content
• Note the source (conversation, file path, or user-provided)
• Proceed to Phase 2

Phase 2: Detect Project Type

Skip if specific reviewer provided in Phase 0.

Detect project type for reviewer selection:

Use Grep tool on package.json:

• Pattern: "next" → nextjs
• Pattern: "react" → react

Use Glob tool:

• requirements.txt, pyproject.toml → python

Select reviewers based on project type:

TypeScript/React:

• agents/review/daniel-product-engineer.md
• agents/review/senior-engineer.md
• agents/review/architecture-engineer.md

Next.js:

• agents/review/lee-nextjs-engineer.md
• agents/review/daniel-product-engineer.md
• agents/review/senior-engineer.md

Python:

• agents/review/senior-engineer.md
• agents/review/performance-engineer.md
• agents/review/architecture-engineer.md

General/Unknown:

• agents/review/senior-engineer.md
• agents/review/architecture-engineer.md

Conditional addition (all UI project types):

• If plan involves UI components, forms, or user-facing features → add agents/review/accessibility-engineer.md

Conditional addition (all project types):

• If package.json includes @mastra/* or the plan involves agents, tools, workflows, memory, RAG, MCP, model routing, browser/sandbox capabilities, or agent-readable software surfaces → add agents/review/mastra-agent-engineer.md

Phase 3: Run Expert Review

If specific reviewer from Phase 0: Spawn single reviewer agent.

Otherwise: Spawn selected reviewer agents in parallel:

Task [reviewer-1] model: sonnet: "Review this plan for [specialty concerns].
Plan:
[plan content]

Focus on: [specific area based on reviewer type]"

Task [reviewer-2] model: sonnet: "Review this plan for [specialty concerns]..."

Task [reviewer-3] model: sonnet: "Review this plan for [specialty concerns]..."

Task [conditional-reviewer] model: sonnet: "Review this plan for [specialty concerns]..."

Phase 4: Consolidate and Present

Transform findings into Socratic questions:

See references/review-patterns.md for approach.

Instead of presenting critiques:

• Turn findings into exploratory questions
• "What if we..." not "You should..."
• Collaborative spirit, not adversarial

Example transformations:

• Reviewer: "This is overengineered" → "We have three layers here. What if we started with one?"
• Reviewer: "Missing error handling" → "What happens if the API call fails? Should we handle that now or later?"
• Reviewer: "Security concern" → "This stores the token in localStorage. Is that acceptable for this use case?"

Present questions one at a time:

• Wait for user response
• If user wants to keep something, they probably have context
• Track decisions as you go

Phase 5: Apply Decisions

For each decision:

• Note what was changed
• Note what was kept and why

If plan came from a file:

• Update the file with changes
• Leave git commit decisions to /arc:commit or the user.

Phase 6: Summary and Next Steps

## Review Summary

**Reviewed:** [plan name/source]
**Reviewers:** [list]

### Changes Made
- [Change 1]
- [Change 2]

### Kept As-Is
- [Decision 1]: [reason]

### Open Questions
- [Any unresolved items]

Show remaining arc:

/arc:ideate     → Feature spec ✓
     ↓
/arc:review     → Review ✓ YOU ARE HERE
     ↓
/arc:implement  → Plan + Execute task-by-task

Offer next steps based on what was reviewed:

If reviewed a feature spec:

• "Ready to implement?" → /arc:implement (which will create the plan internally)
• "Done for now" → end

If reviewed an implementation plan:

• "Ready to implement?" → /arc:implement
• "Done for now" → end