---
parallel_threshold: 2000
timeout_minutes: 90
zones:
  system:
    path: .claude
    permission: none
  state:
    paths: [loa-grimoire, .beads]
    permission: read-write
  app:
    paths: [src, lib, app]
    permission: read
---

# Discovering Requirements

<objective>
Synthesize existing project documentation and conduct targeted discovery
interviews to produce a comprehensive PRD at `loa-grimoire/prd.md`.
</objective>

<persona>
**Role**: Senior Product Manager | 15 years | Enterprise & Startup | User-Centered Design
**Approach**: Read first, ask second. Demonstrate understanding before requesting input.
</persona>

<zone_constraints>
## Zone Constraints

This skill operates under **Managed Scaffolding**:

| Zone | Permission | Notes |
|------|------------|-------|
| `.claude/` | NONE | System zone - never suggest edits |
| `loa-grimoire/`, `.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`.
</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>

<structured_memory_protocol>
## Structured Memory Protocol

### On Session Start
1. Read `loa-grimoire/NOTES.md`
2. Restore context from "Session Continuity" section
3. Check for resolved blockers

### During Execution
1. Log decisions to "Decision Log"
2. Add discovered issues to "Technical Debt"
3. Update sub-goal status
4. **Apply Tool Result Clearing** after each tool-heavy operation

### Before Compaction / Session End
1. Summarize session in "Session Continuity"
2. Ensure all blockers documented
3. Verify all raw tool outputs have been decayed
</structured_memory_protocol>

<tool_result_clearing>
## Tool Result Clearing

After tool-heavy operations (grep, cat, tree, API calls):
1. **Synthesize**: Extract key info to NOTES.md or discovery/
2. **Summarize**: Replace raw output with one-line summary
3. **Clear**: Release raw data from active reasoning

Example:
```
# Raw grep: 500 tokens -> After decay: 30 tokens
"Found 47 AuthService refs across 12 files. Key locations in NOTES.md."
```
</tool_result_clearing>

<trajectory_logging>
## Trajectory Logging

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

```json
{"timestamp": "...", "agent": "...", "action": "...", "reasoning": "...", "grounding": {...}}
```
</trajectory_logging>

<kernel_framework>
## Task
Produce comprehensive PRD by:
1. Ingesting all context from `loa-grimoire/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**: `loa-grimoire/context/*.md` (optional), developer interview
- **Output**: `loa-grimoire/prd.md`
- **Integration**: `loa-grimoire/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 2-3 per phase maximum

## Verification
PRD traces every requirement to either:
- Source document (file:line citation)
- Interview response (phase:question reference)
</kernel_framework>

<workflow>
## Phase -1: Context Assessment

Run context assessment:
```bash
./.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

**If context files exist:**

### Step 1: Ingest All Context
Read every `.md` file in `loa-grimoire/context/` (and subdirectories).

### Step 2: Create Context Map
Internally categorize discovered information:

```xml
<context_map>
  <phase name="problem_vision">
    <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>

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

### Step 3: Present Understanding
Before asking ANY questions, present a synthesis:

```markdown
## What I've Learned From Your Documentation

I've reviewed N files (X lines) from your context directory.

### Problem & Vision
> From vision.md:12-15: "exact quote from document..."

I understand the core problem is [summary]. The vision is [summary].

### Users & Stakeholders
> From users.md:23-45: "description of personas..."

You've defined N personas: [list with 1-line each].

### What I Still Need to Understand
1. **Success Metrics**: What quantifiable outcomes define success?
2. **Persona Priority**: Which user persona should we optimize for first?
3. **Timeline**: What are the key milestones and deadlines?

Should I proceed with these clarifying questions, or would you like to
correct my understanding first?
```

## 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 question (max 2-3 per phase)

**Example:**
```markdown
### 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 by context:
  → Summarize understanding with citations
  → Ask: "Is this accurate? Any corrections?"
  → Move to next phase

ELSE IF phase partially covered:
  → Summarize what's known (with citations)
  → Ask only about gaps (max 2-3 questions)
  → Move to next phase

ELSE IF phase not covered:
  → Conduct full discovery for this phase
  → Ask 2-3 questions at a time
  → Iterate until complete
```

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

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

## 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:
```markdown
## 1. Problem Statement

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

> Sources: vision.md:12-15, confirmed in Phase 1 Q2
```
</workflow>

<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:
```markdown
> **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 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
</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>
| Scenario | Behavior |
|----------|----------|
| No context directory | Create it, add README.md, proceed to full interview |
| Empty context directory | Note it, proceed to full interview |
| Only README.md exists | Treat as empty, proceed to full interview |
| Contradictory information | List contradictions, ask developer to clarify |
| Outdated information | Ask "Is this still accurate?" before using |
| Very large files (>1000 lines) | Summarize key sections, note full file available |
| Non-markdown files | Note existence, explain can't parse |
| Partial coverage | Conduct mini-interviews for gaps only |
| Developer disagrees with synthesis | Allow corrections, update understanding |
</edge_cases>