PRD Mode: docs advertise interactive PRD authoring (`Write a PRD for…`) but spec only supports ingestion

[tamirdresher]

Summary

The published PRD Mode docs advertise a Write a PRD for… prompt as the first example, which reads like an integrated PRD authoring/generation ceremony. The current Squad PRD Mode spec and agent routing only define ingestion of an existing PRD/spec, so the docs and runtime mental model are out of sync.

Current behavior

The public docs currently lead with an authoring prompt in docs/src/content/docs/features/prd-mode.md lines 6–9:

**Try this to generate a requirements document:**

Write a PRD for a user authentication system with OAuth support

But the PRD intake template only defines ingestion/update triggers. .squad-templates/prd-intake.md lines 7–12 contain the full trigger table:

| User says | Action |
|-----------|--------|
| "here's the PRD" / "work from this spec" | Expect file path or pasted content |
| "read the PRD at {path}" | Read the file at that path |
| "the PRD changed" / "updated the spec" | Re-read and diff against previous decomposition |
| (pastes requirements text) | Treat as inline PRD |

The first intake step also assumes a PRD source already exists. .squad-templates/prd-intake.md line 16:

1. **Detect source:** File path, pasted text, or URL. Store a reference in .squad/team.mdunder## PRD Source.

The agent prompt mirrors the same ingestion-only framing: .github/agents/squad.agent.md line 957 says Squad can “ingest a PRD,” line 959 points to prd-intake.md, lines 965–968 list the same ingestion triggers, and line 970 starts with Detect source → store PRD ref....

Result: a user who types Write a PRD for X does not enter PRD Mode as documented. It falls through to general routing; the Lead may draft a PRD-shaped artifact as ordinary work, but the user then has to feed it back in via read the PRD at {path} or here's the PRD to trigger decomposition.

Expected behavior

If Squad keeps the published Write a PRD for… promise, PRD Mode should support a single integrated ceremony:

1. User says Write a PRD for an OAuth login system or asks to work in PRD mode without an existing PRD.
2. Squad/Lead runs a structured discovery conversation: goal, users, success metrics, constraints, non-goals, risks.
3. Lead drafts the PRD using a standard template.
4. User reviews and iterates.
5. On approval, Squad automatically transitions into the existing PRD ingestion flow: compute hash, write ## PRD Source to team.md, decompose into work items, present the table, and route approved work.
6. The user experiences one continuous flow: idea → draft → approval → decomposition → routing.

User impact

This is a UX and mental-model mismatch: the docs promise “generate a requirements document,” while the spec implements “ingest an existing requirements document.” New users can reasonably expect PRD Mode to create the PRD from their input and then decompose it, but today they need to discover and perform a two-step handoff manually.

Resolution options

Option A — docs-only fix

Update docs/src/content/docs/features/prd-mode.md to remove or qualify the Write a PRD for… prompt. Clarify that PRD Mode is ingestion-only at this stage: provide a PRD/spec by path, pasted text, or update notice, and Squad decomposes it.

Option B — implement the authoring flow

Add a new PRD Mode entry point for authoring/generation:

• Add elicitation triggers such as Write a PRD for... and work in PRD mode without an existing PRD.
• Run Lead-driven discovery Q&A.
• Draft → review → approval.
• Automatically continue into the existing ingestion/decomposition/routing flow after approval.

Likely touchpoints: .github/agents/squad.agent.md PRD Mode routing plus .squad-templates/prd-intake.md. If this behavior is template-backed, mirror the updated PRD template to templates/, packages/squad-cli/templates/, and packages/squad-sdk/templates/ to keep the template copies aligned.

Open questions for Brady

• Should PRD authoring live inside the existing prd-intake.md, or should it be split into a separate prd-author.md / prd-generate.md template that hands off to intake?
• Should the elicitation be a prescribed checklist/Q&A, or a free-form Lead conversation that only requires certain fields before approval?
• Should the drafted PRD be written to a file before ingestion, kept inline, or decided by user preference?
• If Squad should avoid prescribing a specific authoring workflow in core, should the docs explicitly point users toward custom squads/skills for interactive PRD authoring instead?

Related prior discussion: #966 covered an adjacent interactive PRD idea and was closed, but it did not address this specific docs-vs-runtime mismatch around the published Write a PRD for… prompt.

Reported by Flight 🏗️ on behalf of @tamirdresher.

[bradygaster]

Fixed in PR #1426 (docs overhaul). Will auto-close on merge.