---
name: discovery-functional
description: >
  Discovery phase 2 — Functional Requirements. Conversational drafting (greenfield),
  audit + iteration (review), or confirm + summarize (ingest). Produces
  docs/requirements/functional.md as a numbered list of testable FRs.
user-invocable: true
---

# /discovery-functional

Phase 2 of `/discovery`. Run standalone or as part of the orchestrator.

**Driver agent:** `planner` (opus).
**Output file:** `docs/requirements/functional.md`.
**Reads:** `docs/glossary.md` (for entity vocabulary), `docs/use-cases/*` if any.

---

## phase 2.0: detect mode

1. Resolve `FR_FILE = docs/requirements/functional.md`.
2. Classify:
   - File missing or only contains the template stub → **greenfield**
   - File exists with FRs and `.discovery-state.md` says `partial` or user passed `--mode review` → **review**
   - File exists, status `complete`, fresh → **ingest**

3. Print: `Mode: <mode>. Source: <FR_FILE>.`

---

## greenfield mode

The planner runs a conversational Q&A. **Three turns minimum** before any draft.

### turn 1 — scope
Ask the user:

> "What are the 3-5 things a user MUST be able to do with this system to call it useful? Skip nice-to-haves. Don't worry about how — just what."

Wait for response. Do not propose anything yet.

### turn 2 — actors & boundaries
After turn 1 reply, ask:

> "Who does each of those? Distinguish: end users, admins, external systems, scheduled jobs. Anything explicitly OUT of scope worth naming now?"

### turn 3 — verifiability
After turn 2 reply, ask:

> "For each capability, how would we know it works in production? A metric, an event, a screen — anything observable. If you can't answer for one, that's a sign it's underspecified."

### draft v1
After 3 turns, propose `docs/requirements/functional.md`:

```markdown
# Functional Requirements

## FR-01 — <short verb-phrase title>
**Actor:** <end user | admin | system X | scheduler>
**Trigger:** <event/action that initiates>
**Outcome:** <observable result>
**Verifiable by:** <log line | metric | DB row | UI element>
**Out of scope:** <if relevant>

## FR-02 — …
```

Format rules (enforced by planner):
- Verb-phrase title, max 10 words.
- One outcome per FR. Split if there are conjunctions.
- Every FR must have `Verifiable by` — if blank, mark `⚠️ NEEDS METRIC` and ask in next turn.
- IDs are stable: never renumber. Append new FRs at the end.

### iterate
- Show diff to user, ask: "Edit, accept, or pivot?"
- Apply edits, re-show. Loop until "ok".
- On "ok": write file, update state.

---

## review mode

### audit (3 lenses)

The planner runs all three before opening Q&A.

#### 1. completeness
For each FR, check:
- [ ] Has Actor
- [ ] Has Trigger
- [ ] Has Outcome
- [ ] Has Verifiable by (not `TBD`, not blank)
- [ ] Title is verb-phrase

#### 2. internal consistency
- Cross-reference `docs/use-cases/*` — every UC must trace to ≥1 FR. List orphan UCs.
- Cross-reference `docs/glossary.md` — entities used in FR text must be defined. List unknown entities.
- Look for duplicates / overlapping FRs (semantic, not literal).

#### 3. drift with reality (only if `src/` has code)
- Grep route definitions, handlers, exposed RPC endpoints. List endpoints with no FR mapping → "undocumented capability".
- Grep scheduled jobs / cron / queue consumers → same check.
- For each FR with `Verifiable by: <metric>`, check if the metric exists (search for the metric name in the codebase). Flag missing.

### present findings

```
Audit of docs/requirements/functional.md (mode: review)

Found 8 FRs. 3 issues:

1. ❌ FR-04 — missing Verifiable by (severity: blocker)
2. ⚠️ FR-07 + FR-09 — overlap on "send notification". Merge or differentiate?
3. ⚠️ Endpoint POST /api/exports/csv has no matching FR — undocumented capability?

Discuss in order, or pick one (1/2/3)?
```

### iterate
- One issue at a time. Q&A with user.
- Each resolved issue → update FR + log in `.discovery-state.md` `issues_resolved`.
- After all resolved → confirm and persist.

---

## ingest mode

1. Read existing `FR_FILE`.
2. Print compact summary:
   ```
   Functional Requirements (8 FRs)
   - FR-01: Register user with email verification
   - FR-02: Place order with stock check
   - …
   ```
3. Ask: `confirm | review | edit which?`
4. `confirm` → mark phase complete, advance.
5. `review` → switch to review mode.
6. `edit FR-N` → open conversational edit on that FR only.

---

## persistence

When user approves the final state:

1. Write `FR_FILE` (atomic — full rewrite, with `<!-- generated by /discovery-functional -->` header).
2. Update `docs/.discovery-state.md`:
   ```
   ## phase_2_functional
   mode: <greenfield|review|ingest>
   status: complete
   last_reviewed: <today>
   issues_open: 0
   issues_resolved: <count>
   ```
3. If downstream phases (`use_cases`, `architecture`) were `complete`, mark them `partial` and print:
   ```
   ⚠️ FRs changed. Phase 3 (use-cases) and Phase 5 (architecture) marked for re-review.
      Run /discovery-use-cases when ready.
   ```

---

## stop conditions

- User says `pause` → save state with `status: in_progress`, exit.
- ≥10 turns without progress on the same FR → suggest pausing, ask "stuck on what?"
- Audit finds zero issues in review mode → auto-confirm with: "No issues found. Mark complete? (y/n)"