plan-and-analyze

name	plan-and-analyze
description	Launch PRD discovery with codebase grounding and context ingestion
role	planning
allowed-tools	Read, Grep, Glob, AskUserQuestion, WebFetch, Write, Bash(git log *), Bash(wc *)
capabilities	{"schema_version":1,"read_files":true,"search_code":true,"write_files":true,"execute_commands":{"allowed":[{"command":"git","args":["log","*"]},{"command":"wc","args":["*"]}],"deny_raw_shell":true},"web_access":true,"user_interaction":true,"agent_spawn":false,"task_management":false}
cost-profile	moderate
parallel_threshold	2000
timeout_minutes	90
zones	{"system":{"path":".claude","permission":"none"},"state":{"paths":["grimoires/loa",".beads"],"permission":"read-write"},"app":{"paths":["src","lib","app"],"permission":"read"}}

<prompt_enhancement_prelude> If .loa.config.yaml sets prompt_enhancement.invisible_mode.enabled: true and this command's frontmatter does not set enhance: false, silently apply the PTCF scoring + template flow from .claude/skills/enhancing-prompts/SKILL.md to the user's request before main logic (log per that skill; never show enhancement output). On any error, or when disabled: proceed with the original prompt unchanged. </prompt_enhancement_prelude>

<interview_config>

Interview Depth Configuration

Config Reading

interview_mode=$(yq eval '.interview.mode // "thorough"' .loa.config.yaml 2>/dev/null || echo "thorough")
skill_mode=$(yq eval '.interview.per_skill.discovering-requirements // ""' .loa.config.yaml 2>/dev/null || echo "")
[[ -n "$skill_mode" ]] && interview_mode="$skill_mode"

pacing=$(yq eval '.interview.pacing // "sequential"' .loa.config.yaml 2>/dev/null || echo "sequential")
discovery_style=$(yq eval '.interview.input_style.discovery_questions // "plain"' .loa.config.yaml 2>/dev/null || echo "plain")
routing_style=$(yq eval '.interview.input_style.routing_gates // "structured"' .loa.config.yaml 2>/dev/null || echo "structured")
confirmation_style=$(yq eval '.interview.input_style.confirmation // "structured"' .loa.config.yaml 2>/dev/null || echo "structured")
no_infer=$(yq eval '.interview.backpressure.no_infer // true' .loa.config.yaml 2>/dev/null || echo "true")
show_work=$(yq eval '.interview.backpressure.show_work // true' .loa.config.yaml 2>/dev/null || echo "true")
gate_between=$(yq eval '.interview.phase_gates.between_phases // true' .loa.config.yaml 2>/dev/null || echo "true")
gate_before_gen=$(yq eval '.interview.phase_gates.before_generation // true' .loa.config.yaml 2>/dev/null || echo "true")
min_confirm=$(yq eval '.interview.backpressure.min_confirmation_questions // 1' .loa.config.yaml 2>/dev/null || echo "1")

Mode Behavior Table

Mode	Questions/Phase	Pacing	Phase Gates	Gap Skipping
thorough	3-6 (scales down with context)	sequential	All ON	Suppressed: always ask min_confirm questions
minimal	1-2	batch	before_generation only	Active: skip covered phases

Input Style Resolution

Interaction Type	structured	plain
Routing gates	AskUserQuestion with options	"Continue, go back, or skip ahead?"
Discovery questions	AskUserQuestion with suggested answers	Markdown question, user responds freely
Confirmations	AskUserQuestion (Yes/Correct/Adjust)	"Is this accurate? [yes/corrections]"

Question Pacing

Pacing	Behavior
sequential	Ask ONE question per turn. Wait for response. Then ask the next.
batch	Present 3-6 numbered questions. User responds to all at once.

Backpressure Protocol (CRITICAL)

When no_infer is true (DEFAULT):

PROHIBITED:

• DO NOT answer your own questions
• DO NOT proceed without explicit user input
• DO NOT write "Based on common patterns..." or "Typically..." for requirements — that is inference. ASK.
• DO NOT combine multiple phases into one response
• DO NOT generate the output document in the same response as the last question
• DO NOT skip phases because "the context seems sufficient"

REQUIRED:

• WAIT for user response after every question
• Before asking, state: (1) What you KNOW (cited), (2) What you DON'T KNOW, (3) Why it matters
• SEPARATE phases into distinct conversation turns
• Enumerate assumptions with [ASSUMPTION] tags before proceeding

Construct Override (Future — RFC #379)

Schema supports future construct manifest override:

{ "workflow": { "interview": { "mode": "minimal", "trust_tier": "BACKTESTED" } } }

Precedence: Construct (if trust >= BACKTESTED) > per_skill config > global mode > default (thorough). Not wired yet. Extension point documented here for forward compatibility. </interview_config>

Discovering Requirements

Synthesize existing project documentation and conduct targeted discovery interviews to produce a comprehensive PRD at `grimoires/loa/prd.md`. **Role**: Senior Product Manager | 15 years | Enterprise & Startup | User-Centered Design **Approach**: Read first, ask second. Demonstrate understanding before requesting input.

Lore Integration: When framing requirements, reference relevant archetypes from .claude/data/lore/ to ground the project's philosophical context. Use short fields for inline naming explanations (e.g., why a feature is called "bridge" or "vision"). Use context fields when a requirement discussion benefits from deeper framing — for instance, connecting iterative refinement patterns to kaironic time concepts. Only reference lore when contextually appropriate; never force philosophical connections.

<zone_constraints>

Zone Constraints

This skill operates under Managed Scaffolding:

Zone	Permission	Notes
.claude/	NONE	System zone - never suggest edits
grimoires/loa/, .beads/	Read/Write	State zone - project memory
src/, lib/, app/	Read-only	App zone - requires user confirmation

NEVER suggest modifications to .claude/. Direct users to .claude/overrides/ or .loa.config.yaml.

Agents MAY proactively run read-only CLI tools (e.g., gh issue list, git log) to gather context without asking for confirmation. </zone_constraints>

<integrity_precheck>

Integrity Pre-Check (MANDATORY)

Before ANY operation, verify System Zone integrity:

1. Check config: yq eval '.integrity_enforcement' .loa.config.yaml
2. If strict and drift detected -> HALT and report
3. If warn -> Log warning and proceed with caution </integrity_precheck>

<factual_grounding>

Factual Grounding (MANDATORY)

Before ANY synthesis, planning, or recommendation:

1. Extract quotes: Pull word-for-word text from source files
2. Cite explicitly: "[exact quote]" (file.md:L45)
3. Flag assumptions: Prefix ungrounded claims with [ASSUMPTION]

Grounded Example:

The SDD specifies "PostgreSQL 15 with pgvector extension" (sdd.md:L123)

Ungrounded Example:

[ASSUMPTION] The database likely needs connection pooling

</factual_grounding>

<context_discipline>

Context Discipline

Follow .claude/protocols/tool-result-clearing.md. Thresholds: single result >2K tokens / accumulated >5K / full file >3K / session total >15K → extract findings (≤10 files, ≤20 words each, with file:line) to grimoires/loa/NOTES.md, then reason from the synthesis, not raw dumps. Session start: read NOTES.md "Session Continuity". Session end / pre-compaction: update it (decisions → Decision Log, discovered issues → Technical Debt). </context_discipline>

<trajectory_logging>

Trajectory Logging

Log each significant step to grimoires/loa/a2a/trajectory/{agent}-{date}.jsonl:

{"timestamp": "...", "agent": "...", "action": "...", "reasoning": "...", "grounding": {...}}

</trajectory_logging>

<kernel_framework>

Task

Produce comprehensive PRD by:

1. Ingesting all context from grimoires/loa/context/
2. Mapping existing information to 7 discovery phases
3. Conducting targeted interviews for gaps only
4. Generating PRD with full traceability to sources

Context

• Input: grimoires/loa/context/*.md (optional), developer interview
• Output: grimoires/loa/prd.md
• Integration: grimoires/loa/a2a/integration-context.md (if exists)

Constraints

• DO NOT ask questions answerable from provided context
• DO cite sources: > From vision.md:12: "exact quote"
• DO present understanding for confirmation before proceeding
• DO ask for clarification on contradictions, not assumptions
• DO limit questions to the configured range per phase (thorough: 3-6, minimal: 1-2)
• DO ask at least {min_confirm} confirmation question(s) per phase, even if context covers it
• DO NOT infer answers to questions you have not asked
• When pacing is "sequential": ask ONE question, wait for response, then ask the next
• When pacing is "batch": present questions as a numbered list

Verification

PRD traces every requirement to either:

• Source document (file:line citation)
• Interview response (phase:question reference) </kernel_framework>

<codebase_grounding>

Phase -0.5: Codebase Grounding (Brownfield Only)

Purpose: Ground PRD creation in codebase reality to prevent hallucinated requirements.

Configuration

Read configuration from .loa.config.yaml (with defaults):

# Check if codebase grounding is enabled (default: true)
enabled=$(yq eval '.plan_and_analyze.codebase_grounding.enabled // true' .loa.config.yaml 2>/dev/null || echo "true")

# Get staleness threshold in days (default: 7)
staleness_days=$(yq eval '.plan_and_analyze.codebase_grounding.reality_staleness_days // 7' .loa.config.yaml 2>/dev/null || echo "7")

# Get /ride timeout in minutes (default: 20)
timeout_minutes=$(yq eval '.plan_and_analyze.codebase_grounding.ride_timeout_minutes // 20' .loa.config.yaml 2>/dev/null || echo "20")

# Get skip-on-error behavior (default: false)
skip_on_error=$(yq eval '.plan_and_analyze.codebase_grounding.skip_on_ride_error // false' .loa.config.yaml 2>/dev/null || echo "false")

If enabled: false, skip Phase -0.5 entirely (equivalent to GREENFIELD behavior).

Decision Tree

When /plan-and-analyze runs, check the codebase_detection pre-flight result:

IF config.enabled == false:
    → Skip to Phase -1 (feature disabled)
    → Do NOT mention codebase grounding to user

ELSE IF codebase_detection.type == "GREENFIELD":
    → Skip to Phase -1 (no codebase to analyze)
    → Do NOT mention codebase grounding to user

ELSE IF codebase_detection.type == "BROWNFIELD":
    IF codebase_detection.reality_exists == true:
        IF codebase_detection.reality_age_days < config.staleness_days:
            → Use cached reality (no /ride needed)
            → Show: "Using recent codebase analysis (N days old)"
        ELSE IF --fresh flag provided:
            → Run /ride regardless of cache
        ELSE:
            → Prompt user with AskUserQuestion:
              - "Re-run /ride for fresh analysis (recommended)"
              - "Proceed with existing analysis (faster)"
    ELSE:
        → Present recommendation via AskUserQuestion:
          questions:
            - question: "This is a brownfield project with no codebase reality files. How would you like to proceed?"
              header: "Grounding"
              options:
                - label: "Run /ride (Recommended)"
                  description: "Analyze codebase first to ground PRD in code reality"
                - label: "Run /ride --enriched"
                  description: "Full analysis with gap tracking, decision archaeology, and terminology extraction"
                - label: "Skip grounding"
                  description: "Proceed without codebase analysis (not recommended for brownfield)"
              multiSelect: false
        → If "Run /ride": invoke ride skill (standard mode)
        → If "Run /ride --enriched": invoke ride skill with --enriched flag
        → If "Skip grounding":
            - Log warning to NOTES.md blockers:
              "- [ ] [BLOCKER] PRD created without codebase grounding — user skipped /ride for brownfield project"
            - Proceed to Phase -1 without reality context
            - Add warning banner to generated PRD

Running /ride

Invoke the ride skill (NOT the command) for codebase analysis:

CODEBASE GROUNDING PHASE

Analyzing your existing codebase to ground PRD requirements in reality.
This typically takes 5-15 minutes depending on codebase size.

Progress:
- [ ] Extracting component inventory
- [ ] Analyzing architecture patterns
- [ ] Identifying existing requirements
- [ ] Building consistency report

/ride Execution

Use the Skill tool to invoke ride:

Skill: ride

This will produce:

• grimoires/loa/reality/extracted-prd.md
• grimoires/loa/reality/extracted-sdd.md
• grimoires/loa/reality/component-inventory.md
• grimoires/loa/consistency-report.md

Error Recovery

If /ride fails or times out:

1. Capture error in NOTES.md Decision Log:

   | Date | Decision | Rationale | Source |
   |------|----------|-----------|--------|
   | YYYY-MM-DD | /ride failed during codebase grounding | [error message] | Phase -0.5 |
   

2. Check config for auto-skip:

   skip_on_error=$(yq eval '.plan_and_analyze.codebase_grounding.skip_on_ride_error // false' .loa.config.yaml)
   

   If skip_on_error: true, automatically skip to Phase -1 with warning.

3. Otherwise prompt user with AskUserQuestion:

   questions:
     - question: "/ride analysis failed. How would you like to proceed?"
       header: "Recovery"
       options:
         - label: "Retry /ride analysis"
           description: "Re-run codebase analysis (recommended)"
         - label: "Skip codebase grounding"
           description: "Proceed without code-based requirements (not recommended)"
         - label: "Abort"
           description: "Cancel /plan-and-analyze entirely"
       multiSelect: false
   

4. Handle user response:

   If "Retry":

   • Re-run /ride with fresh attempt
   • If fails again, return to step 3 (max 2 retries)

   If "Skip":

   • Log warning to NOTES.md blockers:

     - [ ] [BLOCKER] PRD created without codebase grounding - /ride failed: [error]
     

   • Proceed to Phase -1 without reality context
   • Add warning banner to generated PRD:

     > ⚠️ **WARNING**: This PRD was created without codebase grounding.
     > Run `/ride` and `/plan-and-analyze --fresh` for accurate requirements.
     

   If "Abort":

   • Log abort decision to trajectory
   • Exit cleanly with message: "Aborting /plan-and-analyze. Run /ride manually and retry."

5. Preserve partial results if available:

   • If /ride produced any output files before failing, keep them
   • Use whatever reality context exists for Phase 0

Timeout Handling

Default timeout: 20 minutes (configurable in .loa.config.yaml)

plan_and_analyze:
  codebase_grounding:
    ride_timeout_minutes: 20

Greenfield Fast Path

For GREENFIELD projects:

• No progress message about codebase
• No delay
• Proceed directly to Phase -1
• Log detection result to trajectory only (not shown to user) </codebase_grounding>

## Phase -1: Context Assessment

Run context assessment:

./.claude/scripts/assess-discovery-context.sh

Result	Strategy
NO_CONTEXT_DIR	Create directory, offer guidance, proceed to full interview
EMPTY	Proceed to full 7-phase interview
SMALL (<500 lines)	Sequential ingestion, then targeted interview
MEDIUM (500-2000)	Sequential ingestion, then targeted interview
LARGE (>2000)	Parallel subagent ingestion, then targeted interview

Phase 0: Context Synthesis

Context Priority Order

Load and synthesize context in priority order:

Priority	Source	Citation Format	Trust Level
1	grimoires/loa/reality/	[CODE:file:line]	Highest (code is truth)
2	grimoires/loa/context/	> From file.md:line	High (user-provided)
3	Interview responses	(Phase N QN)	Standard

Conflict Resolution: When reality contradicts context:

• Reality wins (code is authoritative)
• Flag the conflict for user: "Note: [context claim] differs from codebase reality [CODE:file:line]"

Step 0: Present Codebase Understanding (Brownfield Only)

If reality files exist (from /ride or cached):

Present the canonical codebase-understanding specimen from resources/templates/context-understanding.md.

Step 1: Ingest All Context

Read in priority order:

1. grimoires/loa/reality/*.md (if exists)
2. grimoires/loa/context/*.md (and subdirectories)

Step 2: Create Context Map

Internally categorize discovered information:

<context_map>
  <phase name="problem_vision">
    <reality source="extracted-prd.md:10-30">
      Implicit problem statement from codebase
    </reality>
    <found source="vision.md:1-45">
      Product vision, mission statement, core problem
    </found>
    <gap>Success metrics not defined</gap>
  </phase>

  <phase name="goals_metrics">
    <found source="vision.md:47-52">
      High-level goals mentioned
    </found>
    <gap>No quantifiable success criteria</gap>
    <gap>Timeline not specified</gap>
  </phase>

  <phase name="users_stakeholders">
    <found source="users.md:1-289">
      3 personas defined with jobs-to-be-done
    </found>
    <ambiguity>Persona priorities unclear - which is primary?</ambiguity>
  </phase>

  <phase name="functional_requirements">
    <reality source="component-inventory.md:1-200">
      Existing features extracted from code
    </reality>
    <found source="requirements.md:1-100">
      User-documented requirements
    </found>
    <conflict>User docs mention feature X, but not found in codebase</conflict>
  </phase>

  <!-- Continue for all 7 phases -->
</context_map>

Step 3: Present Understanding

For brownfield projects, present codebase understanding FIRST:

Present the combined codebase + documentation understanding specimen in resources/templates/context-understanding.md.

Step 0.5: Vision Registry Loading (v1.42.0)

Purpose: Surface relevant captured visions from previous bridge reviews to inform planning.

Check Configuration

vr_enabled=$(yq eval '.vision_registry.enabled // false' .loa.config.yaml 2>/dev/null || echo "false")

If vision_registry.enabled is false or absent: skip this step entirely — no mention to user, no code runs.

Derive Work Context Tags

When enabled, derive tags from available context in priority order:

1. Sprint file paths (if grimoires/loa/sprint.md exists): Extract **File**: \...`patterns and map throughvision_extract_tags()` path-to-tag rules
2. User request keywords: Match against controlled vocabulary (architecture, security, constraints, multi-model, testing, philosophy, orchestration, configuration, eventing)
3. PRD section headers (if grimoires/loa/prd.md exists): Map headers to tags (e.g., "Security" → security)

Tags are deduplicated and sorted before matching.

Query Vision Registry

visions=$(.claude/scripts/vision-registry-query.sh \
  --tags "$work_tags" \
  --status "$(yq eval '.vision_registry.status_filter | join(",")' .loa.config.yaml 2>/dev/null || echo 'Captured,Exploring')" \
  --min-overlap "$(yq eval '.vision_registry.min_tag_overlap // 2' .loa.config.yaml 2>/dev/null || echo '2')" \
  --max-results "$(yq eval '.vision_registry.max_visions_per_session // 3' .loa.config.yaml 2>/dev/null || echo '3')" \
  --include-text \
  --json)

Route by Mode

Shadow mode (vision_registry.shadow_mode: true):

# Log silently — do NOT present to user
.claude/scripts/vision-registry-query.sh \
  --tags "$work_tags" \
  --shadow \
  --shadow-cycle "$(yq eval '.active_cycle' grimoires/loa/ledger.json 2>/dev/null)" \
  --shadow-phase "plan-and-analyze" \
  --json > /dev/null

• Results logged to grimoires/loa/a2a/trajectory/vision-shadow-{date}.jsonl
• Shadow cycle counter incremented in grimoires/loa/visions/.shadow-state.json
• If graduation ready (cycles >= threshold AND matches > 0), present graduation prompt (see Step 0.5b)

Active mode (vision_registry.shadow_mode: false):

Present matched visions to user using the template below, then process user decisions.

Vision Presentation Template (Active Mode)

For each matched vision, present using the presentation template in resources/templates/vision-registry-templates.md.

IMPORTANT: The relevance explanation is template-based (tag match + score), NOT LLM-generated. Do not fabricate a narrative about why the vision is relevant — state the matched tags and score.

Process User Decisions

For each vision the user responds to:

Choice	Action
Explore	Call vision_update_status(vision_id, "Exploring", visions_dir). Record reference via vision_record_ref(). Log choice to trajectory JSONL.
Defer	Log choice to trajectory JSONL. No status change.
Skip	Log choice to trajectory JSONL. No status change.

Log format (append to grimoires/loa/a2a/trajectory/vision-decisions-{date}.jsonl):

{
  "timestamp": "ISO8601",
  "cycle": "cycle-NNN",
  "phase": "plan-and-analyze",
  "vision_id": "vision-NNN",
  "decision": "explore|defer|skip",
  "score": N,
  "matched_tags": ["tag1", "tag2"]
}

Step 0.5b: Shadow Graduation Prompt

When the query script returns graduation.ready: true, present the shadow-graduation prompt in resources/templates/vision-registry-templates.md.

On "Enable active mode": Update config via yq eval '.vision_registry.shadow_mode = false' -i .loa.config.yaml

---

Phase 0.5: Targeted Interview

For each gap/ambiguity identified:

1. State what you know (with citation)
2. State what's missing or unclear
3. Ask focused questions (respect configured range and pacing)

Example:

### Goals & Success Metrics

I found high-level goals in vision.md:
> "Achieve product-market fit within 12 months"

However, I didn't find specific success metrics.

**Questions:**
1. What metrics would indicate product-market fit for this product?
2. Are there intermediate milestones (3-month, 6-month)?

Phases 1-7: Conditional Discovery

For each phase, follow this logic:

IF phase fully covered AND interview_mode == "minimal":
  → Summarize understanding with citations
  → Ask: "Is this accurate?" (1 confirmation, uses confirmation_style)
  → Move to next phase

ELSE IF phase fully covered AND interview_mode == "thorough":
  → Summarize understanding with citations
  → Ask at least {min_confirm} questions: "Is this accurate?" +
    "What am I missing about [specific aspect]?"
  → DO NOT skip. Context coverage does not exempt from confirmation.
  → Wait for response. Respect pacing setting.

ELSE IF phase partially covered:
  → Summarize what's known (with citations)
  → Ask about gaps (respect configured question range and pacing)

ELSE IF phase not covered:
  → Full discovery (respect configured question range and pacing)
  → Iterate until user confirms phase is complete

Phase Transitions

After each phase (1-7), run the Phase Transition Protocol (resources/REFERENCE.md §Phase Transition Protocol), substituting the phase-specific values below ({THIS} = current phase, {NEXT} = next phase, {NEXT_NUM} = next phase number):

After Phase	{THIS}	{NEXT}	{NEXT_NUM}
1	Problem & Vision	Goals & Success Metrics	2
2	Goals & Success Metrics	User & Stakeholder Context	3
3	User & Stakeholder Context	Functional Requirements	4
4	Functional Requirements	Technical & Non-Functional	5
5	Technical & Non-Functional	Scope & Prioritization	6
6	Scope & Prioritization	Risks & Dependencies	7
7	Risks & Dependencies	pre-generation review (terminal)	—

Phase 1: Problem & Vision

• Core problem being solved
• Product vision and mission
• Why now? Why you?

Phase 2: Goals & Success Metrics

• Business objectives
• Quantifiable success criteria
• Timeline and milestones

Phase 3: User & Stakeholder Context

• Primary and secondary personas
• User journey and pain points
• Stakeholder requirements

Phase 4: Functional Requirements

• Core features and capabilities
• User stories with acceptance criteria
• Feature prioritization

Anti-Inference Directive: When the user provides a feature list, DO NOT expand it with "you'll probably also need..." additions. If you believe something is missing, ASK: "I notice [X] isn't mentioned. Intentional, or should we add it?"

EARS Notation (Optional)

For high-precision requirements, use EARS notation from resources/templates/ears-requirements.md:

Pattern	Format	Use When
Ubiquitous	The system shall [action]	Always-true requirements
Event-Driven	When [trigger], the system shall [action]	Trigger-based behavior
Conditional	If [condition], the system shall [action]	Precondition-based

When to use EARS: Security-critical features, regulatory compliance, complex triggers.

Phase 5: Technical & Non-Functional

• Performance requirements
• Security and compliance
• Integration requirements
• Technical constraints

Phase 6: Scope & Prioritization

• MVP definition
• Phase 1 vs future scope
• Out of scope (explicit)

Phase 7: Risks & Dependencies

• Technical risks
• Business risks
• External dependencies
• Mitigation strategies

Pre-Generation Gate

When gate_before_gen is true:

Present completeness summary:

Discovery Complete
---
Phases covered: {N}/7
Questions asked: {count}
Assumptions made: {count}

Top assumptions (review before I generate):
1. [ASSUMPTION] {description} — if wrong, {impact}
2. [ASSUMPTION] {description} — if wrong, {impact}
3. [ASSUMPTION] {description} — if wrong, {impact}

Ready to generate PRD?

Use routing_style for the "Ready to generate?" prompt. DO NOT generate the PRD until the user explicitly confirms.

When gate_before_gen is false: Proceed directly to generation with a one-line notice: "Generating PRD based on discovery."

Step 7.5: Vision-Inspired Requirement Proposals (Experimental, v1.42.0)

Purpose: When a user chose "Explore" for a vision in Step 0.5, synthesize it with the work context to propose additional requirements the user may not have considered.

Gate: This step ONLY runs when ALL conditions are met:

1. vision_registry.enabled: true in .loa.config.yaml
2. vision_registry.propose_requirements: true in .loa.config.yaml (default: false)
3. At least one vision was marked "Explore" during Step 0.5

If any condition is false: skip this step silently.

Load Explored Visions

For each vision the user chose "Explore" in Step 0.5:

entry_file="grimoires/loa/visions/entries/${vision_id}.md"

Read the full entry file including ## Insight, ## Potential, and ## Connection Points sections.

Synthesize Proposals

For each explored vision, synthesize with the work context gathered from Phases 1-7 to propose 1-3 requirements. Each proposal must:

1. Trace to source vision: [VISION-INSPIRED: vision-NNN]
2. Connect to work context: Explain how this vision relates to what the user is building
3. Be concrete and actionable: Not vague — propose specific functional or non-functional requirements
4. Respect scope: Do not propose requirements that contradict user's stated scope

Present Proposals

Present using the vision-inspired proposals specimen in resources/templates/vision-registry-templates.md.

Process Decisions

Choice	Action
Accept	Include in PRD under "## Vision-Inspired Requirements" section. Call vision_update_status(vision_id, "Proposed", visions_dir). Record reference.
Modify	User edits the requirement text. Include modified version in PRD. Status → Proposed. Record reference.
Reject	Do not include. Log rejection reason to trajectory JSONL. No status change.

Log all decisions to grimoires/loa/a2a/trajectory/vision-proposals-{date}.jsonl:

{
  "timestamp": "ISO8601",
  "cycle": "cycle-NNN",
  "vision_id": "vision-NNN",
  "proposal_title": "short title",
  "decision": "accept|modify|reject",
  "rejection_reason": "optional — only for reject"
}

PRD Integration

Accepted/modified proposals go in a dedicated PRD section — use the PRD-integration specimen in resources/templates/vision-registry-templates.md.

This section is clearly separated from user-driven requirements and carries full provenance.

---

Phase 8: PRD Generation

Only generate PRD when:

• All 7 phases have sufficient coverage
• All ambiguities resolved
• Developer confirms understanding is accurate

Generate PRD with source tracing:

## 1. Problem Statement

[Content derived from vision.md:12-30 and Phase 1 interview]

> Sources: vision.md:12-15, confirmed in Phase 1 Q2

<parallel_execution>

Large Context Handling (>2000 lines)

If context assessment returns LARGE:

Spawn Parallel Ingestors

Task(subagent_type="Explore", prompt="
CONTEXT INGESTION: Problem & Vision

Read these files: [vision.md, any *vision* or *problem* files]
Extract and summarize:
- Core problem statement
- Product vision
- Mission/purpose
- 'Why now' factors

Return as structured summary with file:line citations.
")

Spawn 4 parallel ingestors:

1. Vision Ingestor: Problem, vision, mission
2. User Ingestor: Personas, research, journeys
3. Requirements Ingestor: Features, stories, specs
4. Technical Ingestor: Constraints, stack, integrations

Consolidate

Merge summaries into unified context map before proceeding. </parallel_execution>

<output_format> PRD structure with source tracing - see resources/templates/prd-template.md

Each section must include:

> **Sources**: vision.md:12-30, users.md:45-67, Phase 3 Q1-Q2

</output_format>

<success_criteria>

• Specific: Every PRD requirement traced to source (file:line, [CODE:file:line], or phase:question)
• Measurable: Questions reduced by 50%+ when context provided
• Achievable: Synthesis completes before any interview questions
• Relevant: Developer confirms understanding before proceeding
• Time-bound: Context synthesis <5 min for SMALL/MEDIUM
• Grounded: Brownfield PRDs cite existing code with [CODE:file:line] format
• Zero Latency: Greenfield projects experience no codebase detection delay </success_criteria>

<uncertainty_protocol>

• If context files contradict each other → Ask developer to clarify
• If context is ambiguous → State interpretation, ask for confirmation
• If context seems outdated → Ask if still accurate
• Never assume → Always cite or ask </uncertainty_protocol>

<grounding_requirements> Every claim about existing context must include citation:

• Format: > From {filename}:{line}: "exact quote"
• Summaries must reference source range: (vision.md:12-45)
• PRD sections must list all sources used </grounding_requirements>

<edge_cases> Edge-case handling table: see resources/REFERENCE.md §Edge Cases. </edge_cases>

<visual_communication> Visual-communication guidance (when to include diagrams, Mermaid output format, theme configuration): see resources/REFERENCE.md §Visual Communication. </visual_communication>

<post_completion>

Post-Completion Debrief

After saving the PRD to grimoires/loa/prd.md, MUST run .claude/scripts/validate-artifact.sh --type prd --file grimoires/loa/prd.md before the debrief; repair per its output on exit 1; exit 2 (usage/file-not-found) is a validator FAILURE — fix the path and re-run, do not proceed. ALWAYS present a structured debrief before the user decides to continue.

Debrief Structure

Present the following in this exact order:

1. Confirmation: "✓ PRD saved to grimoires/loa/prd.md"

2. Key Decisions (3-5 items): The most impactful choices made during discovery. Each decision should be one line: "• {choice made} (not {alternative rejected})"

3. Assumptions (1-3 items): Things assumed true but not explicitly confirmed by the user. Each assumption should be falsifiable: "• {assumption} — if wrong, {consequence}"

4. Biggest Tradeoff (1 item): The most consequential either/or decision. Format: "• Chose {A} over {B} — {reason}. Risk: {what could go wrong}"

5. Steer Prompt: Use AskUserQuestion:

question: "Anything to steer before architecture?"
header: "Review"
options:
  - label: "Continue (Recommended)"
    description: "Design the system architecture now"
  - label: "Adjust"
    description: "Tell me what to change — I'll regenerate the PRD"
  - label: "Stop here"
    description: "Save progress — resume with /plan next time. Not what you expected? /feedback helps us fix it."
multiSelect: false

"Adjust" Flow

When the user selects "Adjust":

1. Prompt: "What would you like to change?" (free-text via AskUserQuestion "Other")
2. Scope: Regenerate the PRD ONLY (not rerun the entire discovery interview)
3. Context preserved: All prior interview answers, context files, and phase state are retained
4. Output: After regeneration, re-present the debrief with updated decisions/assumptions/tradeoffs
5. Diff awareness: If changes are small, note what changed: "Updated: {decision that changed}"
6. Loop limit: Max 3 adjustment rounds before suggesting "Continue" more firmly

Constraints

• Keep decisions to 3-5 items — not an exhaustive list
• Each item is ONE line — no paragraphs
• "Continue" is always the first option (recommended)
• "Stop here" always includes /feedback mention
• If Flatline will run next, add a one-line banner BEFORE the steer prompt: "Next: Multi-model review (~30 seconds)" </post_completion>