Design Review (Challenger Agent)

Design Review (Challenger Agent)

Overview

Specs and plans written by AI often contain hallucinations: references to APIs that don't exist, wrong column names, incorrect file paths, assumed config attributes that were never defined. These errors waste hours during implementation.

This skill dispatches an independent challenger agent that reads the spec or plan, identifies every concrete claim, and verifies each one against the actual codebase. The challenger has zero context from the authoring session — it trusts only grep, read, and the code.

Announce at start: "I'm using the design-review skill to dispatch a challenger agent for adversarial review."

When to Use

• After superpowers:brainstorming produces a spec → design-review spec <path>
• After superpowers:writing-plans produces a plan → design-review plan <path>
• When a spec/​plan references models, APIs, or config from an unfamiliar codebase
• When the document was written in a session that hit context limits (higher hallucination risk)
• User says "review the spec", "review the plan", "challenge this", "check for hallucinations"

Modes

Mode 1: Spec Review — design-review spec <path>

Triggered after a spec is written. Verifies:

Mode 2: Plan Review — design-review plan <path> [--spec <spec_path>]

Triggered after a plan is written. Two verification dimensions:

Dimension 1: Technical Reference Verification (same as original plan-review)

Dimension 2: Spec Coverage Verification (requires --spec parameter)

When a spec path is provided, the challenger also verifies plan ↔ spec alignment:

Usage: design-review plan <plan_path> --spec <spec_path> or design-review plan <plan_path> (spec-only review if spec auto-detected from same date prefix)

Graph Enhancement (optional, if graph available)

If .code-review-graph/​graph.db exists:

• Plan files → /​explore impact to check for missed affected modules
• Spec functions → query graph nodes to verify existence

Process

1. Identify the document path and type (spec or plan)
2. If plan review → auto-detect related spec (same date prefix in docs/​superpowers/​specs/) or use --spec
3. Dispatch challenger agent (general-purpose, in foreground)
4. Receive findings: BLOCKERs + WARNINGs + Coverage matrix (if spec provided)
5. If BLOCKERs exist → fix inline, re-verify
6. If only WARNINGs → present to user, fix if agreed
7. Report final status

Step 1: Identify Inputs

Determine the document type and path:

Spec locations:

• docs/​superpowers/​specs/​*.md
• User-specified path

Plan locations:

• docs/​superpowers/​plans/​*.md
• .harness/​plans/​*.md
• User-specified path

Step 2: Dispatch Challenger Agent

Use the Agent tool:

Agent:
  description: "Adversarial design review"
  subagent_type: general-purpose
  prompt: <see challenger-prompt.md — fill [DOC_PATH], [DOC_TYPE], [SPEC_PATH]>

Critical rules:

• MUST be general-purpose (needs Read, Grep, Glob tools)
• Do NOT use superpowers:code-reviewer — this is codebase verification, not code review
• Run in foreground (need results before proceeding)

Step 3-6: Same as plan-review

See the Process section above. Handle BLOCKERs (must fix) and WARNINGs (should fix) exactly as described in the original plan-review skill.

Severity Levels

BLOCKER (must fix before execution)

• Nonexistent attribute / field / column
• Wrong import path / module name
• Hallucinated API / function
• Wrong function signature
• Nonexistent file path

WARNING (should fix, won't crash)

• Stale patterns (codebase has better approach)
• Missing error handling that siblings have
• Field name cosmetic mismatch
• Missing data fetch

Anti-Patterns

Key Principle

The challenger trusts nothing from the authoring session. Every concrete reference is verified by reading the actual source.