Reflection Skill

Apply (spawn agent): code, architecture, PRD, specs, tests, plans, APIs, schemas. Skip: simple questions, status checks, file reading, clarifying questions, help.

The sub-agent gets NO conversation context. It evaluates purely on merit — inline evaluation shares your context, agrees with your reasoning, and trends to 10/10. The agent sees only output + request + WHY, and can verify claims in source files.

Process

1. Extract isolation variables (below).
2. Spawn reflection-agent with isolated inputs.
3. Parse JSON response.
4. If pass=false and revisions<3: apply guidance, re-evaluate.
5. Display Quality Check box.

Context Extraction (CRITICAL)

Extract these for the agent. Do NOT summarize or add context.

Variable	How to Extract
{{ORIGINAL_REQUEST}}	First user message that initiated this task - VERBATIM
{{STATED_WHY}}	The WHY established at conversation start - EXACT TEXT
{{PHASE_NUMBER}}	Read from .aid/state.json → current_phase
{{PHASE_NAME}}	Read from .aid/state.json → phase_name
{{OUTPUT_TO_EVALUATE}}	Your draft output (code, spec, etc.)
{{FILES_TO_VERIFY}}	Read content of all files your output references/modifies
{{PHASE_CRITERIA}}	Read from criteria/phase-{N}-{name}.yaml

DO: copy original request exactly as user wrote it; copy stated WHY exactly as established; include ALL files the output references (not just some); load criteria from the YAML file.

DO NOT: ❌ summarize the request; ❌ explain your decisions; ❌ include conversation history; ❌ mention previous attempts; ❌ add "helpful context".

Spawn Command

Task(
  subagent_type: "general-purpose",
  model: "opus",
  prompt: [Load ../../agents/reflection-agent.md, replace variables],
  description: "Objective quality evaluation"
)

Quality Check Display Format

After receiving agent response, display:

╭─────────────────────────────────────────────────────────────╮
│ 🔍 Quality Check                                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  [icon] WHY Alignment     X/10   [agent's note]             │
│  [icon] Phase Compliance  X/10   [agent's note]             │
│  [icon] Correctness       X/10   [agent's note]             │
│  [icon] Security          X/10   [agent's note]             │
│  [icon] Completeness      X/10   [agent's note]             │
│                                                             │
│  ══════════════════════════════════════════════════════     │
│  📊 Overall: X.X/10                                         │
│  STATUS: [agent's status]                                   │
│                                                             │
│  [If revised: 📝 Improvements: ...]                         │
│                                                             │
╰─────────────────────────────────────────────────────────────╯

Score Icons

Score	Icon
8-10	✅
6-7.9	⚠️
0-5.9	❌

Revision Handling

If agent returns pass: false:

1. Read revision_guidance.required_changes
2. Apply changes to your output
3. Re-spawn agent with updated output (max 3 attempts)
4. Track improvements: "Security 5→8/10 Fixed: Added input validation"

Session Review Mode

On project load or /good-morning, spawn session review instead:

Task(
  subagent_type: "general-purpose",
  model: "opus",
  prompt: [Load ../../agents/reflection-agent.md],
  description: "Session review - outside perspective"
)

Session review variables:

• {{STATE_JSON}} - Content of .aid/state.json
• {{CONTEXT_JSON}} - Content of .aid/context.json
• {{RECENT_CHANGES}} - Output of git log --oneline -10
• {{RECENT_FILES}} - Output of git diff --stat HEAD~5
• {{PHASE_CRITERIA}} - Current phase criteria YAML

Commands

Command	Action
/reflect	Show detailed breakdown of last evaluation
/reflect --session	Run session review
/reflect --strict	Run evaluation with threshold 8.0