---
name: fp-write-prd
description: Author a Product Requirements Document grounded in the fastpace domain context. Interviews the user one question at a time, then writes a committable PRD to fastpace/docs/prd/<slug>.md. Triggers on /fp-write-prd <feature-name-or-slug>.
---

# fp-write-prd

Produce a PRD the team can actually build against — specific, testable, grounded in your domain vocabulary. PRDs answer *what* and *why*, never *how*.

## Preflight

1. Read `fastpace/context/glossary.md`, `architecture.md`, and `conventions.md`. They seed your vocabulary and constrain what's in scope.
2. Read `fastpace/context/decisions.md` and recent ADRs — these shape what's possible and what's off-limits.
3. List existing PRDs in `fastpace/docs/prd/` — if the user's topic overlaps, surface that overlap before interviewing.
4. Derive the slug from the invocation. `"add credit card validation"` → `credit-card-validation`. Confirm with the user.
5. **Check for cached external doc bodies** at `fastpace/.refs-bodies/<slug>/`. If files exist (Layer 2 has resolved them), read each one — they're plain text dumps of Confluence pages / Google Docs already linked to this slug. Use them as ground truth when authoring. Skip if the directory doesn't exist (no refs added yet, or auto-discovery / Layer 2 disabled).

## Process

1. **Confirm scope** in one line: "Writing a PRD for `<slug>`. Goal is to capture the what + why. I'll ask one question at a time. Ready?"
2. **Interview** in the order below. **One question at a time.** Skip any the user already answered in their initial invocation. Stop interviewing as soon as you have enough to write — don't over-ask.
3. **Draft the PRD** and show the user the full markdown before writing.
4. **Write** to `fastpace/docs/prd/<slug>.md` after explicit confirmation.
5. **Auto-discover external refs** (only if at least one provider has auto-discovery enabled). After writing, run `fastpace refs suggest <slug>` — fastpace uses the freshly-written PRD body as the search query. Show the top candidates as a numbered list and ask which (if any) to add. Confirm before adding any. **Never add silently.** See "Auto-discovery" below.
6. **Report** the file path, any refs added, and suggest the next step (`/fp-prd-to-erd <slug>` once approved).

## Interview order

Ask these roughly in order, one at a time. Adapt: if the user's first answer reveals they already know metrics, skip ahead; if they're fuzzy on "who", dig in.

1. **Problem.** "Who hurts today, and how — in one sentence?"
2. **Now-ness.** "Why solve this now? What changed?"
3. **Target user.** "Which persona/segment feels this pain — primarily?"
4. **Goals.** "What's the outcome if this works? (measurable, not feature-list.)"
5. **Non-goals.** "What are you explicitly not trying to fix in this feature?"
6. **Success metric.** "What single number tells you it worked?"
7. **Constraints.** "Hard constraints — deadline, regulatory, dependencies, team capacity?"
8. **Rollout.** "All at once, feature flag, canary, gradual — preference?"
9. **Open questions.** "Anything you're unsure about that the team will need to resolve?"

Stop after a question if the user says "write it up" or you've covered the essentials.

## PRD format (exact)

```markdown
---
title: <human-readable feature name>
slug: <slug>
status: draft
author: <user>
created: <YYYY-MM-DD>
target_release: <YYYY-QN or TBD>
---

# <human-readable feature name>

## Summary

<2-4 sentences. What we're building, for whom, why now. No implementation.>

## Problem

<Who hurts. How often. What happens today. Ground with a number if the user gave one;
mark "TBD" if they didn't — never make numbers up.>

## Target user

<Specific persona or segment. Include what differentiates them from adjacent users.>

## Goals

- <measurable outcome, not feature>
- <…>

## Non-goals

- <explicit out-of-scope>
- <…>

## User stories

- As a <persona>, I want <capability> so that <outcome>.
- <…>

## Success metric

**Primary:** <metric name> ≥ <target> by <date>.
**Guardrail (don't regress):** <metric> stays within <band>.

## Constraints & dependencies

- **Deadline:** <date or "none stated">
- **Regulatory:** <PCI / GDPR / SOC2 / none>
- **Dependencies:** <internal teams / external services>
- **Capacity:** <number of engineers × weeks>

## Rollout

<flag name if gated; canary plan; rollback trigger>

## Open questions

- <question>
- <…>

## References

- Context cited: <fastpace/context/<file>.md § section>
- Related decisions: <fastpace/context/decisions.md § YYYY-MM-DD | ADR NNNN>
- Prior PRDs touching this area: <paths, if any>
```

## Rules

- **No implementation.** The word "endpoint", "schema", "table", or any library name should rarely appear. Push them to the ERD.
- **No fabricated numbers.** If the user can't give a target, write `TBD` and list it under Open Questions.
- **Use the glossary.** If the user uses a term that contradicts `glossary.md`, flag it: "Glossary says X — is that what you mean, or is this something new?"
- **One question at a time.** Never dump a 9-item questionnaire. Users disengage.
- **Don't prescribe rollout.** If the user has no preference, default to "feature flag, 10% canary, then gradual" and mark as default.
- **Preserve quotes.** If the user says something precise ("card decline rate"), use their words.
- **Check for overlap.** If a prior PRD covers adjacent scope, ask: "Extend `<existing-slug>` or start fresh?" before drafting.

## Integration

- After writing, tell the user: "Next: `/fp-prd-to-erd <slug>` once this is approved, to produce the engineering design."
- If the user's answers suggest a real decision (e.g. "we're deprecating the old checkout"), recommend `/fp-write-adr` for that decision separately — don't bury it in the PRD.
- If the scope is enormous, recommend splitting into 2+ PRDs now rather than later.

## Auto-discovery (optional, off by default)

If `references.resolvers.confluence.auto_discover.enabled` or `.google-docs.auto_discover.enabled` is true in `fastpace.config.yaml`, run after step 4:

```bash
fastpace refs suggest <slug> --limit 5
```

That command:
- reads the PRD body you just wrote as the search query
- ranks Confluence pages with BM25 (over allow-listed spaces)
- ranks Google Docs by Drive's `orderBy=relevance` (over allow-listed folders)
- returns the top 5 candidates, never auto-adding anything

Show the user the candidates **as a numbered list** with title + score + URL. Then ask:

> *"Add any of these to the PRD's references? Reply with numbers (e.g. `1, 3`) or `none`."*

For each chosen item, run `fastpace refs add <slug> --url <url> --title "<title>"`. Report what was added.

If both providers are off (default), skip this step silently — don't pester the user about a feature they didn't enable.

## Exit criteria

- File written at `fastpace/docs/prd/<slug>.md` with `status: draft` and `created` date.
- User saw the draft before it was saved.
- Output: file path + "run `/fp-prd-to-erd <slug>` once approved" + optional git-add hint.