Generate a detailed Product Requirements Document via `tx doc add prd`. Uses EARS requirement syntax with traceable IDs, acceptance criteria, and non-functional requirements. References plan via file path instead of embedding. Plan lives in ~/.claude/plans/<name>.md. Designed to be created alongside a companion `/design-doc`. Output lands in specs/prd/<name>.md.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Generate a detailed Product Requirements Document via `tx doc add prd`. Uses EARS requirement syntax with traceable IDs, acceptance criteria, and non-functional requirements. References plan via file path instead of embedding. Plan lives in ~/.claude/plans/<name>.md. Designed to be created alongside a companion `/design-doc`. Output lands in specs/prd/<name>.md.
argument-hint
<feature-name>
Generate Product Requirements Document (PRD)
Create a comprehensive PRD using the tx doc primitive. PRDs are the source of truth for EARS requirements that feed into tx spec discover for spec-to-test traceability.
PRD + Design Doc are companions. A PRD defines WHAT and WHY. A design doc defines HOW. They are typically created together. The PRD is created first, then /design-doc reads it automatically.
Workflow State Machine
START
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 0: PLAN GATE โ
โ โ
โ Is there an active plan in this conversation? โ
โ โ
โ โโ YES โ Save plan to `~/.claude/plans/<name>.md` if not โ
โ โ already saved. Set `plan: ~/.claude/plans/<name>.md` โ
โ โ in frontmatter. โ
โ โ โ Continue to Step 1 โ
โ โ โ
โ โโ NO โ Tell the user: โ
โ "No plan found. Run /plan first to create โ
โ one, then re-run /prd. Or describe the โ
โ feature and I'll draft the plan inline." โ
โ โ
โ If the user provided enough detail, โ
โ generate a plan yourself (research the โ
โ codebase, think through requirements, โ
โ edge cases, constraints), save to โ
โ `~/.claude/plans/<name>.md`. โ
โ โ Continue to Step 1 โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 1: SCAFFOLD via tx โ
โ โ
โ tx doc add prd <name> --title "<title>" โ
โ โโ SUCCESS โ Continue to Step 2 โ
โ โโ FAIL (exists) โ Edit existing doc โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 2: GATHER CONTEXT โ
โ โ
โ Read: ARCHITECTURE.md, QUALITY.md, CLAUDE.md, โ
โ domain code, schema.ts, API routes, โ
โ existing specs (tx doc list, tx doc show) โ
โ โ Continue to Step 3 โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 3: FILL DOCUMENT โ
โ โ
โ Write `# Plan` first (reference to plan file). โ
โ Then fill all sections from plan file + codebase. โ
โ Convert plan items to EARS requirements. โ
โ โ
โ MINIMUM THRESHOLDS: โ
โ - EARS requirements: โฅ 10 โ
โ - Acceptance criteria: โฅ 5 โ
โ - NFRs: โฅ 8 โ
โ - User personas: โฅ 1 โ
โ โ
โ RULE: No section may be left as a template/stub. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 4: SELF-AUDIT โ
โ โ
โ Re-read the plan. Every plan item must appear. โ
โ Check minimums. Check EARS syntax. No stubs. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 5: VALIDATE โ
โ โ
โ tx spec lint โ
โ โโ PASS โ Continue to Step 6 โ
โ โโ WARN/FAIL โ Fix, re-validate โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 6: DISCOVER + LINK + REPORT โ
โ โ
โ Step 5.5: SYNC PLAN FILE โ
โ โ
โ Read the plan file from frontmatter `plan:` path. โ
โ Compare with what the doc now contains. โ
โ UPDATE the plan file to incorporate: โ
โ - New requirements/constraints discovered โ
โ - Refined scope, decisions, error handling โ
โ - Acceptance criteria, risks, NFRs โ
โ The plan file must reflect the FULL current state โ
โ of the feature โ not just the initial draft. โ
โ This is a MANDATORY step, not optional. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Step 6: DISCOVER + LINK + REPORT โ
โ โ
โ tx spec discover --doc <name> โ
โ tx doc link <overview> <prd> (if overview exists) โ
โ tx doc show <name> โ
โ Print summary โ
โ Suggest: /design-doc <name> for companion doc โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
DONE
Step 0 โ Plan Gate
The plan is the primary input. Check for plan content in the conversation:
If the user ran /plan or was in plan mode, the plan text is in the conversation. Write it to ~/.claude/plans/<name>.md (relative to repo root).
If a plan file already exists at ~/.claude/plans/<name>.md, read it instead of overwriting.
If no plan but the user gave detailed requirements, generate a plan yourself: research the codebase, think through requirements/edge cases/constraints, write the plan to ~/.claude/plans/<name>.md.
If no plan and the request is vague, ask the user to run /plan first or provide more detail.
The plan is saved as a standalone file at ~/.claude/plans/<name>.md (relative to repo root). The doc's frontmatter gets plan: ~/.claude/plans/<name>.md and the # Plan section contains a reference link plus a brief summary, not the full verbatim content.
Body Structure โ ALL sections MUST have real content
# Plan comes first (as a reference to the plan file). Every subsequent section draws from the plan file content. No section may be a stub.
How to Convert Plan Items to EARS
Plan Item Type
EARS Pattern
Example
"System does X"
Ubiquitous
The system shall X
"When user does X, show Y"
Event-driven
When X, the system shall show Y
"If logged in, allow X"
State-driven
While authenticated, the system shall allow X
"Handle error X"
Unwanted
If X occurs, then the system shall Y
"Feature flag for X"
Optional
Where X is enabled, the system shall Y
"When state A and user does B"
Complex
While A, when B, the system shall C
# Plan> Full plan: [~/.claude/plans/<name>.md](../~/.claude/plans/<name>.md)
<2-3 sentence summary of what the plan covers. The full plan lives in the file referenced above.>
# Summary
2-3 sentence summary of the feature and business value.
# Problem## Current State
How things work today. Pain points.
## Impact
Quantify: user friction, lost revenue, operational cost.
# Scope## Included- Systems, packages, domains affected
- Reference specific paths: `apps/api`, `packages/core/src/domains/<domain>`## Excluded- What is explicitly NOT part of this feature
# User Personas## Persona 1: <Name>
| Attribute | Detail |
|-----------|--------|
| Role | |
| Goals | |
| Pain Points | |
| Technical Proficiency | |
**MINIMUM: โฅ 1 persona.**# Requirements## EARS Requirements
All functional requirements use EARS. Each gets `REQ-<SCOPE>-NNN`. These become traceable invariants via `tx spec discover`.
### EARS Pattern Reference
| Pattern | Template | When to Use |
|---------|----------|-------------|
| Ubiquitous | The system shall `<action>` | Always-on behavior |
| Event-driven | When `<trigger>`, the system shall `<action>` | Response to event |
| State-driven | While `<state>`, the system shall `<action>` | State-dependent |
| Optional | Where `<feature>` is enabled, the system shall `<action>` | Feature-flagged |
| Unwanted | If `<condition>`, then the system shall `<action>` | Error/edge case |
| Complex | While `<state>`, when `<trigger>`, the system shall `<action>` | State + event |
### Core Requirements```yaml
ears_requirements:
- id: REQ-<SCOPE>-001
kind: ubiquitous
statement: the system shall <action>
priority: must
rationale: <why this matters>
All endpoints validate auth tokens via Effect HttpApi middleware
NFR-021
Passwords hashed with bcrypt (cost >= 12)
NFR-022
SQL injection prevented via Drizzle parameterized queries
NFR-023
Rate limiting on auth endpoints
Observability
ID
Requirement
NFR-030
Structured logging via @tx-agent-kit/logging (no console.*)
NFR-031
OpenTelemetry spans for key operations
NFR-032
OTel tracing for AI operations (if applicable)
Data Retention
ID
Requirement
NFR-040
Retention policies for session/token tables
NFR-041
Financial audit trails (usage_records, credit_ledger) โ NO retention
MINIMUM: โฅ 8 NFRs across categories.
Success Metrics
Metric
Baseline
Target
Measurement Window
Risks & Mitigations
ID
Risk
Likelihood
Impact
Mitigation
R-001
Dependencies
Dependency
Owner
Status
Risk
Non-goals
Explicit exclusions
Open Questions
Questions requiring stakeholder input
## Step 4 โ Self-Audit
Re-read the plan section. For every item in the plan, confirm it appears in at least one subsequent section. Check:
- โฅ 10 EARS, โฅ 5 ACs, โฅ 8 NFRs, โฅ 1 persona
- EARS IDs unique and sequential
- EARS statements follow the correct pattern for their kind
- No stubs, no empty tables, no "..." placeholders
- Verify plan file exists at the path in frontmatter and its content is consistent with the doc sections
## Step 5 โ Validate
```bash
tx spec lint
Step 5.5 โ Sync Plan File (MANDATORY)
After filling and validating the doc, update the plan file at the plan: frontmatter path to reflect everything the doc surfaced. The plan file must be the living source of truth โ not a stale initial draft.
What to add to the plan file:
New requirements, constraints, and error handling discovered while writing EARS
Acceptance criteria summaries
Refined scope (included/excluded)
Risk mitigations
Key decisions made during the PRD process
NFR targets
Read the current plan file, merge in the new information, and write it back. Preserve the plan's structure but ensure it now covers the full feature scope as understood after the PRD.
Step 6 โ Discover, Link & Report
tx spec discover --doc <name>
tx doc link <overview> <prd> # if overview exists
tx doc show <name>
Companion: Design Doc
This PRD is designed to be paired with a design doc. After creating the PRD, suggest:
Run /design-doc <name> to create the companion design document.
The design doc will automatically read this PRD and map EARS requirements to invariants.
The design doc reads the PRD via tx doc show <prd-name> --md and maps every must-priority EARS requirement to an invariant + verification entry.
Summarize: EARS count, AC count, NFR count, persona count.
List open questions.
Suggest: /design-doc <name> for the companion design doc.
If the plan file is modified later, update the # Plan summary and derived sections in this doc. If this doc's scope changes, update the plan file to stay consistent.
