Host Compatibility

If you are running this skill in Codex, read ../references/codex-compatibility.md before following host-specific tool instructions. Claude Code should continue to use the Claude-specific tools and command wrappers described here.

Model posture (Soloship)

See the auto-loaded model-mode rule. Standard posture (the default): execute this skill exactly as written. Fable posture (model id contains fable/mythos): every gate this skill names — evidence to produce, verifications to run, dispatches it mandates, user checkpoints — remains binding; its step ordering and procedural scaffolding are method guidance you may adapt when the work is better served. Never skip a step that produces evidence; when ambiguous, treat it as a gate.

Review Command

<command_purpose> Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and Git worktrees for deep local inspection. </command_purpose>

Introduction

<role>Senior Code Review Architect with expertise in security, performance, architecture, and quality assurance</role>

Prerequisites

Main Tasks

1. Determine Review Target & Setup (ALWAYS FIRST)

<review_target> #$ARGUMENTS </review_target>

Immediate Actions:

<task_list>

• 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.

Ensure that the code is ready for analysis (either in worktree or on current branch). ONLY then proceed to the next step.

</task_list>

Protected Artifacts

<protected_artifacts> The following paths are compound-engineering pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent:

• docs/plans/*.md — Plan files created by /soloship:plan. These are living documents that track implementation progress (checkboxes are checked off by /soloship:implement).
• docs/solutions/*.md — Solution documents created during the pipeline.

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>

Run the Review Lenses

Review the PR across these lenses in parallel — each is a general-purpose subagent given the PR content plus the relevant Soloship checklist as its rubric:

This skill's mandated dispatches are the ceiling, not the floor — run the dispatches it names, and do not add discretionary subagents on top (no extra verification or review dispatches, no splitting one modest task across parallel workers); see references/delegation-discipline.md. The lens set below is that ceiling.

<parallel_tasks>

• Correctness & quality — rubric: references/code-review-axes.md
• Security — rubric: references/security-checklist.md
• Performance — rubric: references/performance-checklist.md
• Test coverage — rubric: references/testing-patterns.md
• Accessibility (only if the PR touches UI) — rubric: references/accessibility-checklist.md
• Component duplication (only if the PR adds/renames UI components):<!-- concern:component-reuse -->If docs/architecture/COMPONENTS.md exists, read it before creating or specifying UI components — reuse or extend an existing component on purpose match, cite what you found, and apply the rule of three (see references/component-inventory.md). The reviewer checks each new component in the diff against the inventory (and a name/prop-shape grep) and flags reintroduced duplicates as findings.

Additionally, always run this regardless of the above:

• Dispatch a general-purpose subagent with the prompt in references/agents/learnings-researcher.md, input: the PR content — searches docs/solutions/ for past issues related to this PR's modules and patterns

</parallel_tasks>

Conditional Agents (Run if applicable):

<conditional_agents>

Run these extra checks ONLY when the PR matches specific criteria. Check the PR files list to determine if they apply:

MIGRATIONS / DATA CHANGES: If the PR contains schema/data migrations or backfills (e.g. Cloudflare D1 SQL migrations, Drizzle/Prisma migrations, KV/R2/Durable Object data reshapes, or Apps Script Sheet-schema changes):

Dispatch a general-purpose subagent to review migration safety. Have it check:

• Drift: the migration changes only what the PR intends — no unrelated schema/column changes pulled in from local state.
• Mapping correctness: any hard-coded ID/enum/mapping values match production reality (the classic swapped-value bug); associations aren't orphaned; dual-write/backfill ordering is safe.
• Rollback: there's a documented rollback path, and a Go/No-Go pre/post-deploy checklist with the exact verification queries to run.

This is also where the billing/credit/rerun-window confirmation gate applies — if the migration touches any of that state, stop and confirm the data-model semantics first (see the project's billing-confirmation-gate rule).

When to run:

• PR includes migration files (D1 migrations/*.sql, Drizzle/Prisma migration dirs, etc.) or backfill scripts
• PR modifies columns/fields that store IDs, enums, or mappings
• PR title/body mentions: migration, backfill, data transformation, ID mapping

</conditional_agents>

4. 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>

Phase 3: Stakeholder Perspective Analysis

<thinking_prompt> ULTRA-THINK: Put yourself in each stakeholder's shoes. What matters to them? What are their pain points? </thinking_prompt>

<stakeholder_perspectives>

1. Developer Perspective <questions>

   • 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 4: 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>

6. Multi-Angle Review Perspectives

Technical Excellence Angle

• Code craftsmanship evaluation
• Engineering best practices
• Technical documentation quality
• Tooling and automation assessment

Business Value Angle

• Feature completeness validation
• Performance impact on users
• Cost-benefit analysis
• Time-to-market considerations

Risk Management Angle

• Security risk assessment
• Operational risk evaluation
• Compliance risk verification
• Technical debt accumulation

Team Dynamics Angle

• Code review etiquette
• Knowledge sharing effectiveness
• Collaboration patterns
• Mentoring opportunities

4. Simplification and Minimalism Review

Check whether the code can be simplified — dispatch a general-purpose subagent (or run /soloship:simplify) to look for over-engineering, premature abstraction, and dead code, judged against references/code-review-axes.md.

5. Findings Synthesis and Todo Creation Using file-todos Skill

<critical_requirement> All findings must be stored in the todos/ directory using the file-todos skill. Create todo files immediately after synthesis — do not present findings for user approval first. Use the skill for structured todo management. </critical_requirement>

Step 1: Synthesize All Findings

<synthesis_tasks>

• 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/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)

</synthesis_tasks>

Step 2: Create Todo Files Using file-todos Skill

<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>

Implementation Options:

Option A: Direct File Creation (Fast)

• Create todo files directly using Write tool
• All findings in parallel for speed
• Use standard template from .claude/skills/file-todos/assets/todo-template.md
• Follow naming convention: {issue_id}-pending-{priority}-{description}.md

Option B: Sub-Agents in Parallel (Recommended for Scale) For large PRs with 15+ findings, use sub-agents to create finding files in parallel:

# 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.

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

Execution Strategy:

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

Process (Using file-todos Skill):

1. For each finding:

   • 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

2. Use file-todos skill for structured todo management:

   skill: file-todos

   The skill provides:

   • Template location: .claude/skills/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.

3. Create todo files in parallel:

   {next_id}-pending-{priority}-{description}.md

4. Examples:

   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

5. Follow template structure from file-todos skill: .claude/skills/file-todos/assets/todo-template.md

Todo File Structure (from template):

Each todo must include:

• 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

File naming convention:

{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

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:

## ✅ Code Review Complete

**Review Target:** PR #XXXX - [PR Title] **Branch:** [branch-name]

### Findings Summary:

- **Total Findings:** [X]
- **🔴 CRITICAL (P1):** [count] - BLOCKS MERGE
- **🟡 IMPORTANT (P2):** [count] - Should Fix
- **🔵 NICE-TO-HAVE (P3):** [count] - Enhancements

### Created Todo Files:

**P1 - Critical (BLOCKS MERGE):**

- `001-pending-p1-{finding}.md` - {description}
- `002-pending-p1-{finding}.md` - {description}

**P2 - Important:**

- `003-pending-p2-{finding}.md` - {description}
- `004-pending-p2-{finding}.md` - {description}

**P3 - Nice-to-Have:**

- `005-pending-p3-{finding}.md` - {description}

### Review Lenses Applied:

- Correctness & quality (`references/code-review-axes.md`)
- Security (`references/security-checklist.md`)
- Performance (`references/performance-checklist.md`)
- Test coverage (`references/testing-patterns.md`)
- Accessibility, where UI is touched (`references/accessibility-checklist.md`)
- Prior-art / known patterns (`references/agents/learnings-researcher.md`)

### Next Steps:

1. **Address P1 Findings**: CRITICAL - must be fixed before merge

   - Review each P1 todo in detail
   - Implement fixes or request exemption
   - Verify fixes before merging PR

2. **Triage All Todos**:
   ```bash
   ls todos/*-pending-*.md  # View all pending todos
   /triage                  # Use slash command for interactive triage
   ```

3. Work on Approved Todos:

   /resolve_todo_parallel  # Fix all approved items efficiently

4. Track Progress:
   • Rename file when status changes: pending → ready → complete
   • Update Work Log as you work
   • Commit todos: git add todos/ && git commit -m "refactor: add code review findings"

Severity Breakdown:

🔴 P1 (Critical - Blocks Merge):

• Security vulnerabilities
• Data corruption risks
• Breaking changes
• Critical architectural issues

🟡 P2 (Important - Should Fix):

• Performance issues
• Significant architectural concerns
• Major code quality problems
• Reliability issues

🔵 P3 (Nice-to-Have):

• Minor improvements
• Code cleanup
• Optimization opportunities
• Documentation updates

### 7. End-to-End Testing (Optional)

<offer_testing>

If the PR touches UI (pages, components, views), after the Summary Report offer browser testing:

```markdown
**"Want to run browser tests on the affected pages?"**
1. Yes - drive `/soloship:browse` over the affected pages
2. No - skip

</offer_testing>

If User Accepts Web Testing:

Spawn a subagent to run browser tests (preserves main context):

Dispatch a general-purpose subagent to drive /soloship:browse: identify the pages affected by the PR, navigate to each, capture snapshots, and report issues.

The subagent will:

1. Identify pages affected by the PR
2. Navigate to each page and capture snapshots (using /soloship:browse)
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

Important: P1 Findings Block Merge

Any 🔴 P1 (CRITICAL) findings must be addressed before merging the PR. Present these prominently and ensure they're resolved before accepting the PR.