All preferences are collected upfront to enable fully autonomous mode. If the user wants autonomous execution, they should not be interrupted after this phase.

0.1 Detect Escape Hatches

Parse the user's initial message for natural language escape hatches BEFORE asking questions.

If escape hatch detected, ask via AskUserQuestion:

## Existing Document Detected

I see you have an existing [design doc/impl plan] at <path>.

Header: "Document handling"
Question: "How should I handle this existing document?"

Options:
- Review first (Recommended)
  Description: Run the reviewer skill on this document before proceeding, addressing any findings
- Treat as ready
  Description: Accept this document as-is and proceed directly to [Phase 3/Phase 4]

Handle by choice:

Review first (design doc):

1. Skip Phase 2.1 (Create Design Document)
2. Load the existing design doc
3. Jump to Phase 2.2 (Review Design Document)
4. Continue normal flow from there (review → approval gate → fix → Phase 3)

Review first (impl plan):

1. Skip Phases 2.1-3.1 (assumes design is complete)
2. Load the existing impl plan
3. Jump to Phase 3.2 (Review Implementation Plan)
4. Continue normal flow from there (review → approval gate → fix → Phase 4)

Treat as ready (design doc):

1. Load the existing design doc
2. Skip entire Phase 2 (no creation, no review, no fixes)
3. Start at Phase 3

Treat as ready (impl plan):

1. Load the existing impl plan
2. Skip Phases 2-3 entirely
3. Start at Phase 4

0.2 Clarify the Feature (Lightweight)

Collect only the CORE essence. Detailed discovery happens in Phase 1.5 after research informs what questions to ask.

Ask via AskUserQuestion:

• What is the feature's core purpose? (1-2 sentences)
• Are there any resources, links, or docs to review during research?

Store answers in SESSION_CONTEXT.feature_essence.

0.3 Collect Workflow Preferences

## Configuration Wizard Questions

### Question 1: Autonomous Mode
Header: "Execution mode"
Question: "Should I run fully autonomous after this wizard, or pause for your approval at review checkpoints?"

Options:
- Fully autonomous (Recommended)
  Description: I proceed without pausing, automatically fix all issues including suggestions
- Interactive
  Description: Pause after each review phase for your explicit approval before proceeding
- Mostly autonomous
  Description: Only pause if I encounter blockers I cannot resolve on my own

### Question 2: Parallelization Strategy
Header: "Parallelization"
Question: "When tasks can run in parallel (researching multiple aspects, implementing independent components), how should I handle it?"

Options:
- Maximize parallel (Recommended)
  Description: Spawn parallel subagents whenever tasks are independent for faster execution
- Conservative
  Description: Default to sequential execution, only parallelize when clearly beneficial
- Ask each time
  Description: Present parallelization opportunities and let you decide case by case

### Question 3: Git Worktree Strategy
Header: "Worktree"
Question: "How should I handle git worktrees for this implementation?"

Options:
- Single worktree (Recommended for sequential)
  Description: Create one worktree; all tasks share it
- Worktree per parallel track
  Description: Create separate worktrees for each parallel group; smart merge after (auto-enables maximize parallel)
- No worktree
  Description: Work in current directory

### Question 4: Post-Implementation Handling
Header: "After completion"
Question: "After implementation completes successfully, how should I handle PR/merge?"

Options:
- Offer options (Recommended)
  Description: Use finishing-a-development-branch skill to present merge/PR/cleanup choices
- Create PR automatically
  Description: Push branch and create PR without asking
- Just stop
  Description: Stop after implementation, you handle PR manually

0.4 Store Preferences and Initialize Context

Store all collected preferences and initialize context containers. Reference them consistently throughout the session.

SESSION_PREFERENCES = {
    autonomous_mode: "autonomous" | "interactive" | "mostly_autonomous",
    parallelization: "maximize" | "conservative" | "ask",
    worktree: "single" | "per_parallel_track" | "none",
    worktree_paths: [],  # Filled during Phase 4.1 if per_parallel_track
    post_impl: "offer_options" | "auto_pr" | "stop",
    escape_hatch: null | {
        type: "design_doc" | "impl_plan",
        path: string,
        handling: "review_first" | "treat_as_ready"  # User's choice from 0.1
    }
}

SESSION_CONTEXT = {
    feature_essence: {},       # Filled in Phase 0.2
    research_findings: {},     # Filled in Phase 1
    design_context: {}         # Filled in Phase 1.5 - THE KEY CONTEXT FOR SUBAGENTS
}

# IMPORTANT: If worktree == "per_parallel_track", automatically set parallelization = "maximize"
# Parallel worktrees only make sense with parallel execution

# IMPORTANT: SESSION_CONTEXT.design_context is passed to ALL subagents after Phase 1.5
# This enables synthesis mode - subagents have full context and don't ask questions

Phase 1: Research & Ambiguity Detection

1.1 Research Strategy Planning

INPUT: User feature request OUTPUT: Research strategy with specific questions

Process:

1. Analyze feature request for technical domains
2. Generate codebase questions:
   • Which files/modules handle similar features?
   • What patterns exist for this type of work?
   • What integration points are relevant?
   • What edge cases have been handled before?
3. Identify knowledge gaps explicitly
4. Create research dispatch instructions

Example Questions:

Feature: "Add JWT authentication for mobile API"

Generated Questions:
1. Where is authentication currently handled in the codebase?
2. Are there existing JWT implementations we can reference?
3. What mobile API endpoints exist that will need auth?
4. How are other features securing API access?
5. What session management patterns exist?

1.2 Execute Structured Research (Subagent)

SUBAGENT DISPATCH: YES REASON: Exploration with uncertain scope. Subagent reads N files, returns synthesis.

Dispatch Instructions:

Task(
  "Research Agent - Codebase Patterns",
  `You are a research agent. Your job is to answer these specific questions about
the codebase. For each question:

1. Search systematically (Glob + Grep patterns)
2. Read relevant files
3. Extract patterns, conventions, precedents
4. FLAG any ambiguities or conflicting patterns
5. EXPLICITLY state 'UNKNOWN' if evidence is insufficient

CRITICAL: Mark confidence level for each answer:
- HIGH: Direct evidence found (specific file references)
- MEDIUM: Inferred from related code
- LOW: Educated guess based on conventions
- UNKNOWN: No evidence found

QUESTIONS TO ANSWER:
[Insert questions from Phase 1.1]

RETURN FORMAT (strict JSON):
{
  "findings": [
    {
      "question": "...",
      "answer": "...",
      "confidence": "HIGH|MEDIUM|LOW|UNKNOWN",
      "evidence": ["file:line", ...],
      "ambiguities": ["..."]
    }
  ],
  "patterns_discovered": [
    {
      "name": "...",
      "files": ["..."],
      "description": "..."
    }
  ],
  "unknowns": ["..."]
}`,
  "researcher"
)

ERROR HANDLING:

• If subagent fails: Retry once with same instructions
• If second failure: Return findings with all items marked UNKNOWN
• Note: "Research failed after 2 attempts: [error]"
• Do NOT block progress - user chooses to proceed or retry

TIMEOUT: 120 seconds per subagent

1.3 Ambiguity Extraction

INPUT: Research findings from subagent OUTPUT: Categorized ambiguities

Process:

1. Extract all MEDIUM/LOW/UNKNOWN confidence items
2. Extract all flagged ambiguities from findings
3. Categorize by type:
   • Technical: How it works (e.g., "Two auth patterns found - which to use?")
   • Scope: What to include (e.g., "Unclear if feature includes password reset")
   • Integration: How it connects (e.g., "Multiple integration points - which is primary?")
   • Terminology: What terms mean (e.g., "'Session' used inconsistently")
4. Prioritize by impact on design (HIGH/MEDIUM/LOW)

Example Output:

Categorized Ambiguities:

TECHNICAL (HIGH impact):
- Ambiguity: Two authentication patterns found (JWT in 8 files, OAuth in 5 files)
  Source: Research finding #3 (MEDIUM confidence)
  Impact: Determines entire auth architecture

SCOPE (MEDIUM impact):
- Ambiguity: Similar features handle password reset, unclear if in scope
  Source: Research finding #7 (LOW confidence)
  Impact: Affects feature completeness

INTEGRATION (HIGH impact):
- Ambiguity: Three possible integration points found (event emitter, direct calls, message queue)
  Source: Research finding #5 (MEDIUM confidence)
  Impact: Determines coupling and testability

1.4 Research Quality Score

SCORING FORMULAS:

1. COVERAGE SCORE:

   • Numerator: Count of findings with confidence = "HIGH"
   • Denominator: Total count of research questions
   • Formula: (HIGH_count / total_questions) * 100
   • Edge case: If total_questions = 0, score = 100

2. AMBIGUITY RESOLUTION SCORE:

   • Numerator: Count of ambiguities with category + impact assigned
   • Denominator: Total count of ambiguities detected
   • Formula: (categorized_count / total_ambiguities) * 100
   • Edge case: If total_ambiguities = 0, score = 100

3. EVIDENCE QUALITY SCORE:

   • Numerator: Count of findings with non-empty evidence array
   • Denominator: Count of findings with confidence != "UNKNOWN"
   • Formula: (findings_with_evidence / answerable_findings) * 100
   • Edge case: If all UNKNOWN, score = 0

4. UNKNOWN DETECTION SCORE:

   • Numerator: Count of explicitly flagged unknowns
   • Denominator: Count of findings with UNKNOWN or LOW confidence
   • Formula: (flagged_unknowns / (UNKNOWN_count + LOW_count)) * 100
   • Edge case: If no UNKNOWN/LOW, score = 100

OVERALL SCORE:

• Aggregation: MIN(Coverage, Ambiguity Resolution, Evidence Quality, Unknown Detection)
• Rationale: Weakest link determines quality (all must be 100%)

DISPLAY FORMAT:

Research Quality Score: [X]%

Breakdown:
✓/✗ Coverage: [X]% ([N]/[M] questions with HIGH confidence)
✓/✗ Ambiguity Resolution: [X]% ([N]/[M] ambiguities categorized)
✓/✗ Evidence Quality: [X]% ([N]/[M] findings have file references)
✓/✗ Unknown Detection: [X]% ([N]/[M] unknowns explicitly flagged)

Overall: [X]% (minimum of all criteria)

GATE BEHAVIOR:

IF SCORE < 100%:

• BLOCK progress
• Display score breakdown
• Offer options:

  Research Quality Score: [X]% - Below threshold
  
  OPTIONS:
  A) Continue anyway (bypass gate, accept risk)
  B) Iterate: Add more research questions and re-dispatch
  C) Skip ambiguous areas (reduce scope, remove low-confidence items)
  
  Your choice: ___
  

IF SCORE = 100%:

• Display: "✓ Research Quality Score: 100% - All criteria met"
• Proceed immediately to Phase 1.5

ITERATION LOGIC (for choice B):

1. Analyze gaps: Which criteria < 100%?
2. Generate targeted questions based on gaps
3. Re-dispatch research subagent
4. Re-calculate scores
5. Loop until 100% or user chooses A/C

Phase 1.5: Informed Discovery & Validation

Reference: See ~/.claude/patterns/adaptive-response-handler.md for ARH pattern

1.5.0 Disambiguation Session

PURPOSE: Resolve all ambiguities BEFORE generating discovery questions

MANDATORY_TEMPLATE (enforced):

For each ambiguity from Phase 1.3, present using this exact structure:

AMBIGUITY: [description from Phase 1.3]

CONTEXT FROM RESEARCH:
[Relevant research findings with evidence]

IMPACT ON DESIGN:
[Why this matters / what breaks if we guess wrong]

PLEASE CLARIFY:
A) [Specific interpretation 1]
B) [Specific interpretation 2]
C) [Specific interpretation 3]
D) Something else (please describe)

Your choice: ___

PROCESSING (ARH Pattern):

1. Detect response type using ARH patterns from ~/.claude/patterns/adaptive-response-handler.md

2. Handle by type:

   • DIRECT_ANSWER (A-D): Update disambiguation_results, continue
   • RESEARCH_REQUEST ("research this"): Dispatch subagent, regenerate ALL disambiguation questions
   • UNKNOWN ("I don't know"): Dispatch research subagent, rephrase question with findings
   • CLARIFICATION ("what do you mean"): Rephrase with more context, re-ask
   • SKIP ("skip"): Mark as out-of-scope, document in explicit_exclusions
   • USER_ABORT ("stop"): Save state, exit cleanly

3. After research dispatch:

   • Wait for subagent results
   • Regenerate ALL disambiguation questions with new context
   • Present updated questions to user

4. Continue until: All ambiguities have disambiguation_results entries

Example Flow:

Question: "Research found JWT (8 files) and OAuth (5 files). Which should we use?"
User: "What's the difference? I don't know which is better."

ARH Processing:
→ Detect: UNKNOWN type
→ Action: Dispatch research subagent
  "Research: Compare JWT vs OAuth in our codebase
   Context: User unsure of differences
   Return: Pros/cons of each pattern"
→ Subagent returns comparison
→ Regenerate question:
  "Research shows:
   - JWT: Stateless, used in API endpoints (src/api/*), mobile-friendly
   - OAuth: Third-party integration (src/integrations/*), complex setup

   For mobile API auth, which fits better?
   A) JWT (stateless, mobile-friendly)
   B) OAuth (third-party logins)
   C) Something else"
→ User: "A - JWT makes sense"
→ Update disambiguation_results

1.5.1 Generate Deep Discovery Questions

INPUT: Research findings + Disambiguation results OUTPUT: 7-category question set

GENERATION RULES:

1. Use research findings to make questions specific (not generic)
2. Reference concrete codebase patterns in questions
3. Include assumption checks in every category
4. Generate 3-5 questions per category

7 CATEGORIES:

1. Architecture & Approach

• How should [feature] integrate with [discovered pattern]?
• Should we follow [pattern A from file X] or [pattern B from file Y]?
• ASSUMPTION CHECK: Does [discovered constraint] apply here?

2. Scope & Boundaries

• Research shows [N] similar features. Should this match their scope?
• Explicit exclusions: What should this NOT do?
• MVP definition: What's the minimum for success?
• ASSUMPTION CHECK: Are we building for [discovered use case]?

3. Integration & Constraints

• Research found [integration points]. Which are relevant?
• Interface verification: Should we match [discovered interface]?
• ASSUMPTION CHECK: Must this work with [discovered dependency]?

4. Failure Modes & Edge Cases

• Research shows [N] edge cases in similar code. Which apply?
• What happens if [dependency] fails?
• How should we handle [boundary condition]?
• ASSUMPTION CHECK: Can we ignore [edge case] found in research?

5. Success Criteria & Observability

• Measurable thresholds: What numbers define success?
• How will we know this works in production?
• What metrics should we track?
• ASSUMPTION CHECK: Is [performance target] realistic?

6. Vocabulary & Definitions

• Research uses terms [X, Y, Z]. What do they mean in this context?
• Are [term A] and [term B] synonyms here?
• Build glossary incrementally

7. Assumption Audit

• I assume [X] based on [research finding]. Correct?
• I assume [Y] because [pattern]. Confirm?
• Explicit validation of ALL research-based assumptions

Example Questions (Architecture category):

Feature: "Add JWT authentication for mobile API"

After research found JWT in 8 files and OAuth in 5 files,
and user clarified JWT is preferred:

1. Research shows JWT implementation in src/api/auth.ts using jose library.
   Should we follow this pattern or use a different JWT library?
   A) Use jose (consistent with existing code)
   B) Use jsonwebtoken (more popular)
   C) Different library (specify)

2. Existing JWT implementations store tokens in Redis (src/cache/tokens.ts).
   Should we use the same storage approach?
   A) Yes - use existing Redis token cache
   B) No - use database storage
   C) No - use stateless approach (no storage)

3. ASSUMPTION CHECK: I assume mobile clients will store JWT in secure storage
   and send via Authorization header. Is this correct?
   A) Yes, that's the plan
   B) Partially - clarify the approach
   C) No, different method

1.5.2 Conduct Discovery Wizard (with ARH)

PROCESS:

1. Present questions one category at a time (7 iterations)
2. Use ARH pattern for response processing
3. Update design_context object after each answer
4. Allow iteration within categories

Structure:

## Discovery Wizard (Research-Informed)

Based on research findings and disambiguation, I have questions in 7 categories.

### Category 1/7: Architecture & Approach

[Present 3-5 questions]

[Wait for responses, process with ARH]

### Category 2/7: Scope & Boundaries

[Present 3-5 questions]

[etc...]

ARH INTEGRATION:

For each user response:

1. Detect type using ARH regex patterns

2. Handle by type:

   • DIRECT_ANSWER: Update design_context, continue
   • RESEARCH_REQUEST: Dispatch subagent, regenerate questions in current category
   • UNKNOWN: Dispatch subagent, rephrase with findings
   • CLARIFICATION: Rephrase with more context
   • SKIP: Mark as out-of-scope
   • OPEN_ENDED: Parse intent, confirm interpretation

3. After research dispatch:

   • Regenerate ALL questions in current category
   • New research may improve question quality
   • Present updated questions to user

4. Progress tracking:

   • Show: "[Category N/7]: X/Y questions answered"
   • No iteration limit - user controls when to proceed

1.5.3 Build Glossary

PROCESS:

1. Extract domain terms from discovery answers (during wizard)
2. Build glossary incrementally
3. After wizard completes, show full glossary
4. Ask user ONCE about persistence

GLOSSARY FORMAT:

{
  "term": {
    "definition": "...",
    "source": "user | research | codebase",
    "context": "feature-specific | project-wide",
    "aliases": [...]
  }
}

PERSISTENCE (ask ONCE for entire glossary):

I've built a glossary with [N] terms:

[Show glossary preview]

Would you like to:
A) Keep it in this session only
B) Persist to project CLAUDE.md (all team members benefit)

Your choice: ___

IF B SELECTED - Append to CLAUDE.md:

Location: End of CLAUDE.md file (after all existing content)

Format:

---

## Feature Glossary: [Feature Name]

**Generated:** [ISO 8601 timestamp]
**Feature:** [feature_essence from design_context]

### Terms

**[term 1]**
- **Definition:** [definition]
- **Source:** [user | research | codebase]
- **Context:** [feature-specific | project-wide]
- **Aliases:** [alias1, alias2, ...]

**[term 2]**
[...]

---

Write Operation:

1. Read current CLAUDE.md content
2. Append formatted glossary (as above)
3. Write back to CLAUDE.md
4. Verify write succeeded

ERROR HANDLING:

• If write fails: Fallback to ~/.claude/glossary-[feature-slug].md
• Show location: "Glossary saved to: [path]"
• Suggest: "Manually append to CLAUDE.md when ready"

COLLISION HANDLING:

• If term exists in CLAUDE.md: Check for duplicate feature glossary
• If same feature: Skip, warn "Glossary already exists"
• If different feature: Append as new section

1.5.4 Synthesize Context Document

PURPOSE: Create comprehensive design_context object from all prior phases

DATA TRANSFORMATION (from design doc Appendix A - lines 2006-2131):

Build design_context object with these fields:

interface DesignContext {
  feature_essence: string;  // From user request

  research_findings: {
    patterns: [...],  // From research subagent
    integration_points: [...],
    constraints: [...],
    precedents: [...]
  };

  disambiguation_results: {
    [ambiguity]: {clarification, source, confidence}
  };

  discovery_answers: {
    architecture: {chosen_approach, rationale, alternatives, validated_assumptions},
    scope: {in_scope, out_of_scope, mvp_definition, boundary_conditions},
    integration: {integration_points, dependencies, interfaces},
    failure_modes: {edge_cases, failure_scenarios},
    success_criteria: {metrics, observability},
    vocabulary: {...},
    assumptions: {validated: [...]}
  };

  glossary: {
    [term]: {definition, source, context, aliases}
  };

  validated_assumptions: string[];
  explicit_exclusions: string[];
  mvp_definition: string;
  success_metrics: [{name, threshold}];

  quality_scores: {
    research_quality: number,
    completeness: number,
    overall_confidence: number
  };
}

Validation:

• No null values allowed (except devils_advocate_critique which is optional)
• No "TBD" or "unknown" strings
• All arrays with content or explicit "N/A"

1.5.5 Apply Completeness Checklist

11 VALIDATION FUNCTIONS:

// FUNCTION 1: Research quality validated
function research_quality_validated() {
  return quality_scores.research_quality === 100 || override_flag === true;
}

// FUNCTION 2: Ambiguities resolved
function ambiguities_resolved() {
  const allAmbiguities = categorized_ambiguities;
  return allAmbiguities.every(amb =>
    disambiguation_results.hasOwnProperty(amb.description)
  );
}

// FUNCTION 3: Architecture chosen
function architecture_chosen() {
  return discovery_answers.architecture.chosen_approach !== null &&
         discovery_answers.architecture.rationale !== null;
}

// FUNCTION 4: Scope defined
function scope_defined() {
  return discovery_answers.scope.in_scope.length > 0 &&
         discovery_answers.scope.out_of_scope.length > 0;
}

// FUNCTION 5: MVP stated
function mvp_stated() {
  return mvp_definition !== null && mvp_definition.length > 10;
}

// FUNCTION 6: Integration verified
function integration_verified() {
  const points = discovery_answers.integration.integration_points;
  return points.length > 0 && points.every(p => p.validated === true);
}

// FUNCTION 7: Failure modes identified
function failure_modes_identified() {
  return discovery_answers.failure_modes.edge_cases.length > 0 ||
         discovery_answers.failure_modes.failure_scenarios.length > 0;
}

// FUNCTION 8: Success criteria measurable
function success_criteria_measurable() {
  const metrics = discovery_answers.success_criteria.metrics;
  return metrics.length > 0 && metrics.every(m => m.threshold !== null);
}

// FUNCTION 9: Glossary complete
function glossary_complete() {
  const uniqueTermsInAnswers = extractUniqueTerms(discovery_answers);
  return Object.keys(glossary).length >= uniqueTermsInAnswers.length ||
         user_said_no_glossary_needed === true;
}

// FUNCTION 10: Assumptions validated
function assumptions_validated() {
  const validated = discovery_answers.assumptions.validated;
  return validated.length > 0 && validated.every(a => a.confidence !== null);
}

// FUNCTION 11: No TBD items
function no_tbd_items() {
  const contextJSON = JSON.stringify(design_context);
  const forbiddenTerms = [
    /\bTBD\b/i,
    /\bto be determined\b/i,
    /\bfigure out later\b/i,
    /\bwe'll decide\b/i,
    /\bunknown\b/i  // except in confidence fields
  ];

  // Filter out confidence field occurrences
  const filtered = contextJSON.replace(/"confidence":\s*"[^"]*"/g, '');

  return !forbiddenTerms.some(regex => regex.test(filtered));
}

VALIDATION STATE DATA STRUCTURE:

interface ValidationState {
  results: {
    research_quality_validated: boolean;
    ambiguities_resolved: boolean;
    architecture_chosen: boolean;
    scope_defined: boolean;
    mvp_stated: boolean;
    integration_verified: boolean;
    failure_modes_identified: boolean;
    success_criteria_measurable: boolean;
    glossary_complete: boolean;
    assumptions_validated: boolean;
    no_tbd_items: boolean;
  };

  failures: {
    [functionName: string]: {
      reason: string;
      remediation: string;
      category: string;  // Maps to discovery category
    };
  };

  score: number;  // (checked_count / 11) * 100
}

SCORE CALCULATION:

const checked_count = Object.values(validation_results).filter(v => v === true).length;
const completeness_score = (checked_count / 11) * 100;

DISPLAY FORMAT:

Completeness Checklist:

[✓/✗] All research questions answered with HIGH confidence
[✓/✗] All ambiguities disambiguated
[✓/✗] Architecture approach explicitly chosen and validated
[✓/✗] Scope boundaries defined with explicit exclusions
[✓/✗] MVP definition stated
[✓/✗] Integration points verified against codebase
[✓/✗] Failure modes and edge cases identified
[✓/✗] Success criteria defined with measurable thresholds
[✓/✗] Glossary complete for all domain terms
[✓/✗] All assumptions validated with user
[✓/✗] No "we'll figure it out later" items remain

Completeness Score: [X]% ([N]/11 items complete)

GATE BEHAVIOR:

IF completeness_score < 100:

• BLOCK progress
• Highlight unchecked items
• Offer options:

  Completeness Score: [X]% - Below threshold
  
  OPTIONS:
  A) Return to discovery wizard for missing items (specify which)
  B) Return to research for new questions
  C) Proceed anyway (bypass gate, accept risk)
  
  Your choice: ___
  

IF completeness_score == 100:

• Display: "✓ Completeness Score: 100% - All items validated"
• Proceed to Phase 1.5.6

ITERATION LOGIC:

• Map failed validation to discovery category
• Re-run specific categories only
• Re-validate checklist after updates
• Loop until 100% or user chooses C

1.5.6 Understanding Document Validation Gate

FILE PATH:

• Base: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/understanding/ (defaults to ~/.claude/docs/<project-encoded>/understanding/)
• Format: understanding-[feature-slug]-[timestamp].md

PROJECT ENCODED PATH GENERATION:

# Find outermost git repo (handles nested repos like submodules/vendor)
# Returns "NO_GIT_REPO" if not in any git repository
_outer_git_root() {
  local root=$(git rev-parse --show-toplevel 2>/dev/null)
  [ -z "$root" ] && { echo "NO_GIT_REPO"; return 1; }
  local parent
  while parent=$(git -C "$(dirname "$root")" rev-parse --show-toplevel 2>/dev/null) && [ "$parent" != "$root" ]; do
    root="$parent"
  done
  echo "$root"
}
PROJECT_ROOT=$(_outer_git_root)

If PROJECT_ROOT is "NO_GIT_REPO": Ask user if they want to run git init. If no, use fallback: ~/.claude/docs/_no-repo/$(basename "$PWD")/understanding/

PROJECT_ENCODED=$(echo "$PROJECT_ROOT" | sed 's|^/||' | tr '/' '-')

FEATURE SLUG GENERATION:

1. Take feature_essence
2. Lowercase, replace spaces with hyphens
3. Remove special chars (keep a-z, 0-9, hyphens)
4. Truncate to 50 chars
5. Remove trailing hyphens

TIMESTAMP: ISO 8601 compact (YYYYMMDD-HHMMSS)

DIRECTORY CREATION:

1. Check if directory exists
2. If not: mkdir -p $CLAUDE_CONFIG_DIR/docs/${PROJECT_ENCODED}/understanding/
3. If fails: Fallback to /tmp/understanding-[slug]-[timestamp].md

GENERATE UNDERSTANDING DOCUMENT:

# Understanding Document: [Feature Name]

## Feature Essence
[1-2 sentence summary]

## Research Summary
- Patterns discovered: [...]
- Integration points: [...]
- Constraints identified: [...]

## Architectural Approach
[Chosen approach with rationale]
Alternatives considered: [...]

## Scope Definition
IN SCOPE:
- [...]

EXPLICITLY OUT OF SCOPE:
- [...]

MVP DEFINITION:
[Minimum viable implementation]

## Integration Plan
- Integrates with: [...]
- Follows patterns: [...]
- Interfaces: [...]

## Failure Modes & Edge Cases
- [...]

## Success Criteria
- Metric 1: [threshold]
- Metric 2: [threshold]

## Glossary
[Full glossary from Phase 1.5.3]

## Validated Assumptions
- [assumption]: [validation]

## Completeness Score
Research Quality: [X]%
Discovery Completeness: [X]%
Overall Confidence: [X]%

---

## design_context Serialization

**For downstream subagents:**

[If design_context < 50KB]
Pass via JSON in prompt

[If design_context >= 50KB]
Write to: /tmp/design-context-[slug]-[timestamp].json
Pass file path in prompt

FILE WRITE:

1. Generate markdown content
2. Write to file path
3. Verify write (read back first 100 chars)
4. If fails: Show inline, don't block
5. Store path in design_context.understanding_document_path

VALIDATION GATE:

Present to user:

I've synthesized our research and discovery into the Understanding Document above.

The complete design_context object has been validated and is ready for downstream phases.

Please review the Understanding Document and:
A) Approve (proceed to Devil's Advocate review)
B) Request changes (specify what to revise)
C) Return to discovery (need more information)

Your choice: ___

BLOCK design phase until user approves (A).

Phase 1.6: Devil's Advocate Review

1.6.1 Check Devil's Advocate Availability

Verify skill exists:

test -f ~/.claude/skills/devils-advocate/SKILL.md

IF SKILL MISSING:

ERROR: devils-advocate skill not found

The Devil's Advocate review is REQUIRED for quality assurance.

OPTIONS:
A) Install skill (run install.sh or create manually)
B) Skip review for this session (not recommended)
C) Manual review (I'll present Understanding Document for your critique)

Your choice: ___

Handle user choice:

• A: Exit with instructions: "Run install.sh then restart"
• B: Set skip_devils_advocate flag, proceed to Phase 2
• C: Present Understanding Document, collect manual critique, proceed

1.6.2 Prepare Understanding Document for Review

Determine invocation method:

const understandingDocSize = understandingDocContent.length;

if (understandingDocSize < 10 * 1024) { // < 10KB
  // Inline content (primary method)
  invocationMethod = "inline";
} else {
  // File path (fallback for large docs)
  invocationMethod = "file";
  tempFilePath = `/tmp/understanding-doc-${featureSlug}-${timestamp}.md`;
  writeFile(tempFilePath, understandingDocContent);
}

1.6.3 Invoke Devil's Advocate Skill

Primary (inline content):

Invoke devils-advocate skill using Skill tool, then provide Understanding Document below:

[Insert full Understanding Document from Phase 1.5.6]

Fallback (file path):

Skill("devils-advocate", args: "--understanding-doc /tmp/understanding-doc-[slug]-[timestamp].md")

Wait for critique: Skill returns structured critique with 5 categories

1.6.4 Present Critique to User

Display full critique from devils-advocate skill

Format:

## Devil's Advocate Critique

[Full critique output from skill]

---

This critique identifies potential gaps and risks in our understanding.

Please review and choose next steps:
A) Address critical issues (return to discovery for specific gaps)
B) Document as known limitations (add to Understanding Document)
C) Revise scope to avoid risky areas (return to scope questions)
D) Proceed to design (accept identified risks)

Your choice: ___

1.6.5 Process User Decision

Handle by choice:

A) Address issues:

1. Identify which critique categories need work:
   • Missing Edge Cases -> Return to Phase 1.5.1 (Failure Modes category)
   • Implicit Assumptions -> Return to Phase 1.5.1 (Assumption Audit category)
   • Integration Risks -> Return to Phase 1.5.1 (Integration category)
   • Scope Gaps -> Return to Phase 1.5.1 (Scope category)
   • Oversimplifications -> Return to specific category based on context
2. Pass critique context to discovery regeneration
3. After updated discovery, regenerate Understanding Document
4. Re-run Devil's Advocate (optional, ask user)

B) Document limitations:

1. Update Understanding Document with new section:

   ## Known Limitations (from Devil's Advocate)
   
   [List critique items accepted as limitations]
   

2. Re-save Understanding Document
3. Proceed to Phase 2

C) Revise scope:

1. Return to Phase 1.5.1 (Scope & Boundaries category)
2. Pass critique context
3. Regenerate scope questions to avoid risky areas
4. After updated scope, regenerate Understanding Document
5. Re-run Devil's Advocate to verify

D) Proceed:

1. Set devils_advocate_reviewed flag
2. Optionally add critique to design_context:

   design_context.devils_advocate_critique = {
     missing_edge_cases: [...],
     implicit_assumptions: [...],
     integration_risks: [...],
     scope_gaps: [...],
     oversimplifications: [...]
   };
   

3. Proceed to Phase 2 (Design)

Phase 2: Design

Task (general-purpose):
  description: "Design [feature name]"
  prompt: |
    First, invoke the brainstorming skill using the Skill tool.

    IMPORTANT: This is SYNTHESIS MODE - all discovery is complete.
    DO NOT ask questions. Use the comprehensive context below to produce the design.

    ## Autonomous Mode Context

    **Mode:** AUTONOMOUS - Proceed without asking questions
    **Protocol:** See docs/autonomous-mode-protocol.md
    **Circuit breakers:** Only pause for security-critical decisions or contradictory requirements

    ## Pre-Collected Discovery Context

    [Insert complete SESSION_CONTEXT.design_context from Phase 1.5]

    ## Task

    Using the brainstorming skill in synthesis mode:
    1. Skip the "Understanding the idea" phase - context is complete
    2. Skip the "Exploring approaches" questions - decisions are made
    3. Go directly to "Presenting the design" - write the full design
    4. Do NOT ask "does this look right so far" - proceed through all sections
    5. Save to: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-design.md
    6. Commit the design document when done

    If you encounter a circuit breaker condition (security-critical, contradictory requirements),
    stop and report using the Circuit Breaker Format from the protocol.

Task (general-purpose):
  description: "Review design doc"
  prompt: |
    First, invoke the design-doc-reviewer skill using the Skill tool.
    Then follow its complete workflow to review the design document.

    ## Context for the Skill

    Design document location: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-design.md

    Return the complete findings report with remediation plan.

1. Log the review findings for the record
2. If findings exist: proceed directly to 2.4 Fix Design Doc
3. If no findings: proceed directly to Phase 3

1. Present the review findings summary to the user
2. If ANY findings exist (critical, important, OR minor/suggestions):
   - Display: "The design review found [N] items to address."
   - Display: "Type 'continue' when ready for me to fix these issues."
   - WAIT for user input before proceeding
3. If ZERO findings:
   - Display: "Design review complete - no issues found."
   - Display: "Ready to proceed to implementation planning?"
   - WAIT for user acknowledgment before proceeding

1. If CRITICAL findings exist:
   - Present the critical blockers to the user
   - WAIT for user input
2. If only important/minor findings:
   - Proceed automatically to fix
3. If no findings:
   - Proceed automatically to Phase 3

Task (general-purpose):
  description: "Fix design doc"
  prompt: |
    First, invoke the superpowers:executing-plans skill using the Skill tool.
    Then use its workflow to systematically fix the design document.

    ## Context for the Skill

    Review findings to address:
    [Paste complete findings report and remediation plan]

    Design document location: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-design.md

    Address ALL items - critical, important, AND minor.
    Commit changes when done.

Task (general-purpose):
  description: "Create impl plan for [feature name]"
  prompt: |
    First, invoke the superpowers:writing-plans skill using the Skill tool.
    Then follow its complete workflow to create the implementation plan.

    ## Context for the Skill

    Design document: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-design.md

    User's parallelization preference: [maximize/conservative/ask]
    - If maximize: group independent tasks into parallel groups
    - If conservative: default to sequential

    Save implementation plan to: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md

Task (general-purpose):
  description: "Review impl plan"
  prompt: |
    First, invoke the implementation-plan-reviewer skill using the Skill tool.
    Then follow its complete workflow to review the implementation plan.

    ## Context for the Skill

    Implementation plan location: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
    Parent design document: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-design.md

    Return the complete findings report with remediation plan.

Task (general-purpose):
  description: "Fix impl plan"
  prompt: |
    First, invoke the superpowers:executing-plans skill using the Skill tool.
    Then use its workflow to systematically fix the implementation plan.

    ## Context for the Skill

    Review findings to address:
    [Paste complete findings report and remediation plan]

    Implementation plan location: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
    Parent design document: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-design.md

    Pay special attention to interface contracts between parallel work.
    Commit changes when done.

Task (general-purpose):
  description: "Create worktree for [feature name]"
  prompt: |
    First, invoke the superpowers:using-git-worktrees skill using the Skill tool.
    Then follow its workflow to create an isolated workspace.

    ## Context for the Skill

    Feature name: [feature-slug]
    Purpose: Isolated implementation of [feature description]

    Return the worktree path when done.

Task (general-purpose):
  description: "Execute setup/skeleton tasks"
  prompt: |
    First, invoke the superpowers:test-driven-development skill using the Skill tool.
    Execute ONLY the setup/skeleton tasks from the implementation plan.

    ## Context for the Skill

    Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
    Tasks to execute: [list setup tasks by number]

    These tasks create shared interfaces, type definitions, and stubs that parallel
    work will build against. They MUST be committed before creating parallel worktrees.

    Commit all setup work when done.

Example from plan:
  Parallel Group 1: Tasks 3, 4 (both depend on setup, independent of each other)
  Parallel Group 2: Task 5 (depends on Tasks 3 and 4)

Creates:
  worktree_paths = [
    { path: "[repo]-group-1-task-3", tasks: [3], depends_on: [] },
    { path: "[repo]-group-1-task-4", tasks: [4], depends_on: [] },
    { path: "[repo]-group-2-task-5", tasks: [5], depends_on: ["group-1-task-3", "group-1-task-4"] }
  ]

Task (general-purpose):
  description: "Create worktree for parallel group N"
  prompt: |
    First, invoke the superpowers:using-git-worktrees skill using the Skill tool.
    Create a worktree for this parallel work track.

    ## Context for the Skill

    Feature name: [feature-slug]-group-N
    Branch from: [current branch with setup work committed]
    Purpose: Parallel track for [task descriptions]

    Return the worktree path when done.

For each worktree in SESSION_PREFERENCES.worktree_paths:

  # Skip worktrees whose dependencies haven't completed yet
  if worktree.depends_on not all completed:
    continue (will process in next round)

  Task (general-purpose):
    description: "Execute tasks in [worktree.path]"
    run_in_background: true  # Run parallel worktrees concurrently
    prompt: |
      First, invoke the superpowers:subagent-driven-development skill using the Skill tool.
      Execute the assigned tasks in this worktree.

      ## Context for the Skill

      Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
      Tasks to execute: [worktree.tasks]
      Working directory: [worktree.path]

      IMPORTANT: Work ONLY in this worktree directory.
      Do NOT modify files outside this worktree.

      After each task:
      1. Run code review (invoke superpowers:code-reviewer)
      2. Run claim validation (invoke factchecker)
      3. Commit changes

      Report when all tasks complete: files changed, test results, commit hashes.

  # Dispatch all independent worktrees in parallel
  # Wait for all to complete before processing dependent worktrees

Task (general-purpose):
  description: "Execute parallel implementation"
  prompt: |
    First, invoke the superpowers:dispatching-parallel-agents skill using the Skill tool.
    Then use its workflow to execute the implementation plan with parallel task groups.

    ## Context for the Skill

    Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
    Working directory: [worktree path or current directory]

    Group tasks by their "Parallel Group" field.
    After each group completes, trigger code review and claim validation.

Task (general-purpose):
  description: "Execute sequential implementation"
  prompt: |
    First, invoke the superpowers:subagent-driven-development skill using the Skill tool.
    Then use its workflow to execute the implementation plan sequentially.

    ## Context for the Skill

    Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
    Working directory: [worktree path or current directory]

    Execute tasks one at a time with code review after each.

Task (general-purpose):
  description: "Smart merge parallel worktrees"
  prompt: |
    First, invoke the smart-merge skill using the Skill tool.
    Then follow its workflow to merge all parallel worktrees.

    ## Context for the Skill

    Base branch: [branch where setup/skeleton was committed]

    Worktrees to merge:
    [For each worktree in SESSION_PREFERENCES.worktree_paths:]
    - Path: [worktree.path]
    - Tasks implemented: [worktree.tasks]
    - Depends on: [worktree.depends_on]

    Interface contracts: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
    (See "Interface Contracts" section of the implementation plan)

    After successful merge:
    1. All worktrees should be deleted
    2. Single unified branch should contain all work
    3. All tests should pass
    4. All interface contracts should be verified

Task (general-purpose):
  description: "Implement Task N: [task name]"
  prompt: |
    First, invoke the superpowers:test-driven-development skill using the Skill tool.
    Then use its workflow to implement this task.

    ## Context for the Skill

    Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
    Task number: N
    Working directory: [worktree path or current directory]

    Follow TDD strictly as the skill instructs.
    Commit when done.

    Report: files changed, test results, commit hash, any issues.

Task (general-purpose):
  description: "Review Task N implementation"
  prompt: |
    First, invoke the superpowers:code-reviewer skill using the Skill tool.
    Then follow its workflow to review the implementation.

    ## Context for the Skill

    What was implemented: [from implementation subagent's report]
    Plan/requirements: Task N from $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md
    Base SHA: [commit before task]
    Head SHA: [commit after task]

    Return assessment with any issues found.

Task (general-purpose):
  description: "Validate claims in Task N"
  prompt: |
    First, invoke the factchecker skill using the Skill tool.
    Then follow its workflow to validate claims in the code just written.

    ## Context for the Skill

    Scope: Files created/modified in Task N only
    [List the specific files]

    Focus on: docstrings, comments, test names, type hints, error messages.

    Return findings with any false claims that must be fixed.

# Run the appropriate test command for the project
pytest  # or npm test, cargo test, etc.

Task (general-purpose):
  description: "Audit test quality"
  prompt: |
    First, invoke the green-mirage-audit skill using the Skill tool.
    Then follow its workflow to verify tests actually validate correctness.

    ## Context for the Skill

    Test files to audit: [List of test files created/modified in this feature]
    Implementation files: [List of implementation files created/modified]

    Focus on the new code added by this feature.

Task (general-purpose):
  description: "Comprehensive claim validation"
  prompt: |
    First, invoke the factchecker skill using the Skill tool.
    Then follow its workflow for comprehensive claim validation.

    ## Context for the Skill

    Scope: All files created/modified in this feature
    [Complete list of all files]

    Design document: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-design.md
    Implementation plan: $CLAUDE_CONFIG_DIR/docs/<project-encoded>/plans/YYYY-MM-DD-[feature-slug]-impl.md

    This is the final claim validation gate.
    Cross-reference claims against design doc and implementation plan.
    Catch any claims that slipped through per-task validation.

Task (general-purpose):
  description: "Pre-PR claim validation"
  prompt: |
    First, invoke the factchecker skill using the Skill tool.
    Then follow its workflow for pre-PR validation.

    ## Context for the Skill

    Scope: Branch changes (all commits since merge-base with main)

    This is the absolute last line of defense.
    Nothing ships with false claims.

Task (general-purpose):
  description: "Finish development branch"
  prompt: |
    First, invoke the superpowers:finishing-a-development-branch skill using the Skill tool.
    Then follow its workflow to complete this development work.

    ## Context for the Skill

    Feature: [feature name]
    Branch: [current branch]
    All tests passing: yes
    All claims validated: yes

    Present options to user: merge, create PR, cleanup.

1. Push branch to remote
2. Create PR using gh CLI
3. Return PR URL to user

1. Announce implementation complete
2. Summarize what was built
3. List any remaining TODOs or known issues

def handle_review_checkpoint(findings, mode):
    """
    Determines whether to pause for user approval at review checkpoints.
    """

    if mode == "autonomous":
        # Never pause - proceed automatically
        if findings:
            dispatch_fix_subagent(findings)
        return "proceed"

    if mode == "interactive":
        # Always pause - wait for user
        if len(findings) > 0:
            present_findings_summary(findings)
            display("Type 'continue' when ready for me to fix these issues.")
            wait_for_user_input()
            dispatch_fix_subagent(findings)
        else:
            display("Review complete - no issues found.")
            display("Ready to proceed to next phase?")
            wait_for_user_acknowledgment()
        return "proceed"

    if mode == "mostly_autonomous":
        # Only pause for critical blockers
        critical_findings = [f for f in findings if f.severity == "critical"]
        if critical_findings:
            present_critical_blockers(critical_findings)
            wait_for_user_input()
        if findings:
            dispatch_fix_subagent(findings)
        return "proceed"