Writing Requirements Documents
Create PRDs with Obsidian-native linking (block anchors + wiki links) and mandatory link validation.
When to Use
Use this skill when:
- •Creating new PRD (Product Requirements Document)
- •Writing functional/non-functional requirements
- •Adding acceptance criteria that need traceability
- •Any requirements documentation needing cross-references
Do NOT use for:
- •Simple feature descriptions without formal requirements
- •Informal notes or brainstorming docs
- •Documentation that doesn't need traceability
Quick Reference
| Element | ID Format | Block Anchor | Internal Link Example |
|---|---|---|---|
| Functional Requirement | FR1, FR2... | ^FR1 | [[#^FR1|FR1]] |
| Non-Functional Requirement | NFR1, NFR2... | ^NFR1 | [[#^NFR1|NFR1]] |
| Acceptance Criteria (in Sequencing docs) | AC1, AC2... | ^AC1 | [[#^AC1|AC1]] with ([[#^FR1|FR1]]) traceability |
| Draft AC (in whiteboards) | AC-draft-1... | ^AC-draft-1 | Promoted to ^AC1 in Sequencing phase |
Link Types:
- •Internal wiki link to block anchor:
[[#^FR1|FR1]]- For requirements/ACs - •Internal wiki link to header:
[[#Requirements|Requirements]]- For sections - •Internal markdown link:
[Requirements](#requirements)- Alternative for headers - •Cross-document link:
[Architecture](../design-docs/Architecture.md)- Always use markdown syntax
Core Principles
1. Every Requirement Needs a Block Anchor
Why: Block anchors enable precise linking within Obsidian. Without them, you cannot create reliable cross-references.
Format:
- FR1: The system SHALL detect the Claude Code version from the binary. ^FR1 - NFR1: The system should follow Single Responsibility Principle. ^NFR1
NOT this:
- REQ-F1: The system shall detect version.
2. Use Wiki Links for Internal References, Markdown Links for Cross-Document
Internal references (same document): Use wiki links with block anchors Cross-document references: Use markdown links with file paths
Internal Format:
*Functional Requirements*: [[#^FR1|FR1]], [[#^FR2|FR2]], [[#^FR3|FR3]] *Non-Functional Requirements*: [[#^NFR5|NFR5]], [[#^NFR7|NFR7]]
Cross-Document Format:
*Related Design*: [ARCHITECTURE-PRINCIPLES.md](../../../ARCHITECTURE-PRINCIPLES.md) *Implementation Guide*: [Setup Guide](./guides/setup.md#installation)
NOT this:
Related Requirements: REQ-F1, REQ-NF1 <!-- Plain text, not clickable -->
3. Use RFC 2119 Keywords in Requirements
Mandatory requirements: SHALL, SHALL NOT, REQUIRED Recommended: SHOULD, SHOULD NOT, RECOMMENDED Optional: MAY, OPTIONAL
Example:
- FR1: The system SHALL validate all citations before commit. ^FR1 - FR2: The system SHOULD provide warnings for missing metadata. ^FR2 - FR3: The system MAY cache validation results for performance. ^FR3
4. Follow JTBD → FR → AC Layering
Conceptual model source: .claude/agents/product-manager.md (Requirements Pipeline section)
Requirements follow a three-layer structure that progresses from motivation to specification to verification:
JTBD (Job To Be Done) — Why:
- •Captured in Overview/Business Value section of PRD
- •Explains user needs and business outcomes
- •No block anchors needed (contextual, not referenced)
FR (Functional Requirement) — What:
- •Listed in Requirements section with block anchors:
^FR1,^FR2 - •Outcome-oriented and testable
- •NOT implementation details
Success Criteria — How you'll know the feature works:
- •Already exists in PRD Overview section
- •High-level, outcome-focused verification
- •NOT the same as detailed Acceptance Criteria
Acceptance Criteria (AC) — Detailed test conditions:
- •Do NOT belong in PRD — emerge during Design/Sequencing phases
- •During whiteboarding, capture draft ACs as
^AC-draft-1,^AC-draft-2 - •Formalized in Sequencing Document with
^AC1,^AC2anchors - •Each AC must trace back to an FR:
([[#^FR1|FR1]]) - •ACs become literal test cases during Implementation phase
Why this matters: PRDs are high-level and generic. Detailed, testable ACs require system context that only exists after Design. Don't force premature precision.
5. Reference Template PRD
Before writing, use citation-manager to extract template sections:
# Extract Requirements section npm run citation:extract:header /path/to/template-prd.md -- "Requirements" # Extract Acceptance Criteria npm run citation:extract:header /path/to/template-prd.md -- "Acceptance Criteria"
Template Source: /Users/wesleyfrederick/Documents/ObsidianVault/0_SoftwareDevelopment/cc-workflows/tools/citation-manager/design-docs/features/20251119-type-contract-restoration/typescript-migration-prd.md
PRD Document Structure
A PRD follows this section structure:
- Overview (Business Value, Success Criteria) - Scope (In Scope / Out of Scope) - Requirements (FR + NFR with block anchors) - Non-Goals - Dependencies (Technical, Knowledge, Process) - Risks & Mitigations - Acceptance Criteria (with block anchors) - References (Context Docs, Architecture Standards, Technical Baseline)
Overview Section
## Overview [1-2 sentence description of what this PRD covers and why.] ### Business Value - **[Category]**: [Concrete benefit] - **[Category]**: [Concrete benefit] ### Success Criteria **Done when:** - [Measurable criterion 1] - [Measurable criterion 2] - [Measurable criterion 3]
Token-efficient Overview guidance:
- •Overview = WHAT + WHY (outcomes), never HOW (implementation)
- •Keep capability descriptions ("enables pattern detection")
- •Remove mechanism details ("via deterministic hooks") → belongs in Design
- •"Done when" not "Port complete when" — simpler language
Scope Section
## Scope ### In Scope **[Category]:** - [Specific deliverable or activity] - [Specific deliverable or activity] ### Out of Scope - [Explicitly excluded item] — [Phase if deferred] - [Explicitly excluded item]
Out of Scope format:
- •Pattern:
<item> — <phase>(terse) - •Write
/evolve — Phase A.2not "deferred to Phase A.2" - •Don't repeat terms already evident from item name
Requirements Section
## Requirements ### Functional Requirements - FR1: The system SHALL [specific, testable action]. ^FR1 - FR2: The system SHALL [another requirement]. ^FR2 ### Non-Functional Requirements #### Quality Requirements - NFR1: The system SHALL NOT [constraint]. ^NFR1 - NFR2: [Quality attribute] SHALL [measurable target]. ^NFR2 #### Maintainability Requirements - NFR3: [Maintainability requirement]. ^NFR3 #### Process Requirements - NFR4: [Process constraint or workflow requirement]. ^NFR4
Non-Goals Section
## Non-Goals Explicitly **out of scope** for this effort: - **[Category]**: [Why this is excluded] - **[Category]**: [Why this is excluded]
Dependencies Section
## Dependencies ### Technical Dependencies - [Technology/tool and version requirement] - [Existing infrastructure dependency] ### Knowledge Dependencies - [Documentation or expertise needed] - [Understanding of existing systems] ### Process Dependencies - [Workflow or process requirement] - [Team or organizational dependency]
Risks & Mitigations Section
## Risks and Mitigations ### Risk 1: [Risk Title] **Impact**: [What happens if this risk materializes] **Mitigation**: [How to prevent or address it] ### Risk 2: [Risk Title] **Impact**: [What happens if this risk materializes] **Mitigation**: [How to prevent or address it]
Note: PRDs do NOT include detailed Acceptance Criteria sections. The Success Criteria in the Overview section serves as the high-level completion criteria. Detailed, testable ACs emerge during the Design/Sequencing phase when system context is available.
References Section
## References ### Context Documents - **[Doc Name]**: [link](path/to/doc.md) - [Brief description] ### Architecture Standards - **[Principle Name]**: [link](path/to/ARCHITECTURE-PRINCIPLES.md#Section) - [Why relevant] ### Technical Baseline - **[Baseline Name]**: [Commit hash or version] - [What it represents]
References guidance:
- •Link synthesized artifacts only (whiteboards, design docs)
- •Don't link raw research (agent outputs, session transcripts)
- •Raw research is working material; PRD references curated artifacts
- •"Traceability" means tracing to synthesis, not raw dumps — whiteboard already traces decisions
- •If reviewer asks for "sources", point to whiteboard (which cites raw research internally)
Mandatory Validation Checklist
After writing requirements documentation, create TodoWrite todos for:
- •☐ Verify every requirement has block anchor
- •☐ Verify every acceptance criterion has block anchor
- •☐ Verify all cross-references use wiki link syntax
- •☐ Run
npm run citation:validate <file-path> - •☐ Fix any broken links reported by citation-manager
- •☐ Re-run validation until zero errors
You MUST run citation-manager validate as the final step. This is non-negotiable.
Common Mistakes
| Mistake | Why It's Wrong | Fix |
|---|---|---|
| Plain text IDs (REQ-F1) | Not clickable, breaks navigation | Use [[#^FR1|FR1]] |
| Missing block anchors | Cannot create precise links | Add ^FR1 at end of line |
| "Portability" rationalization | We use Obsidian for linked docs | Wiki links are our standard |
| Skipping validation | Broken links in docs | Run citation-manager validate |
| Wrong ID format (REQ-F1) | Inconsistent with templates | Use FR1, NFR1, AC1 |
| Missing Non-Goals section | Scope creep without boundaries | Always document what's excluded |
| Requirements without categories | Hard to navigate large PRDs | Group NFRs by Quality, Maintainability, Process |
| ACs in PRD instead of Sequencing | Violates progressive disclosure | PRD gets Success Criteria; ACs formalize in Sequencing |
| ACs without FR traceability | Can't verify which requirement is satisfied | Add ([[#^FR1|FR1]]) to each AC |
| Implementation details in Overview | Overview = WHAT/WHY, not HOW | Move mechanisms to Design doc |
| Verbose Out of Scope ("deferred to Phase A.2") | Wastes tokens, harder to scan | Use — Phase A.2 format |
| Linking raw research (agent outputs) | Working material, not curated | Link synthesized artifacts only |
Red Flags
🚩 Requirements without block anchors 🚩 Cross-references as plain text 🚩 "I'll validate the links manually" 🚩 "Block anchors are extra work" 🚩 "Plain text is more portable" 🚩 Skipping citation-manager validate step 🚩 Using inconsistent ID formats 🚩 Missing Non-Goals or Scope sections 🚩 Detailed acceptance criteria in PRD (use Success Criteria instead) 🚩 Acceptance criteria without FR traceability links 🚩 Implementation mechanisms in Overview (hooks, APIs, technologies) 🚩 Verbose Out of Scope items ("deferred to", redundant descriptions) 🚩 Raw research artifacts in References (agent outputs, session transcripts)
Common Rationalizations (And Why They're Wrong)
| Rationalization | Why You Might Think This | The Truth |
|---|---|---|
| "Plain text IDs are more portable for export to Word/PDF" | Requirements docs often get exported | We use Obsidian specifically for linked documentation. Portability is not our goal—traceability is. |
| "Easier to reference REQ-F1 in conversations" | Plain text feels simpler | Wiki links display as text (FR1) but provide navigation. No conversation difference, huge usability gain. |
| "This follows professional standards" | Generic requirements patterns | Professional ≠ Obsidian-optimized. We have specific standards for our workflow. |
| "I can validate links manually or write a script" | Automation seems unnecessary | We already have citation-manager. Use it. Manual validation is error-prone. |
| "Block anchors aren't necessary for simple docs" | Only complex docs need anchors | Every requirement needs traceability from day one. "Simple" docs become complex. |
| "I'll add the anchors and links later" | Focus on content first | Never happens. Add them now or they'll be missing forever. |
| "Non-Goals aren't needed for small PRDs" | Seems like overhead | Non-Goals prevent scope creep. Even small PRDs benefit from explicit boundaries. |
| "Implementation details help understanding" | Context feels helpful | Overview = WHAT/WHY only. HOW belongs in Design doc. Readers scan for outcomes, not mechanisms. |
| "Verbose Out of Scope is clearer" | More words = more clarity | Terse is scannable. — Phase A.2 conveys same info as "deferred to Phase A.2". |
| "Raw research links show my work" | Transparency is good | PRDs reference curated artifacts. Working materials (agent outputs) clutter the doc. |
Example: Before vs After
Before (Wrong)
## Requirements **REQ-F1:** System shall export to JSON. Related: See acceptance criteria in appendix.
After (Correct)
## Requirements ### Functional Requirements - FR1: The system SHALL export validation reports to JSON format. ^FR1 ## Acceptance Criteria 1. **Export**: JSON output matches documented schema. ^AC1 *Functional Requirements*: [[#^FR1|FR1]]
Integration with Other Tools
- •After brainstorming: Use this skill to formalize design into PRD requirements
- •Before writing-plans: PRD requirements feed into implementation plans
- •With citation-manager: Always validate links before committing
Remember: If you catch yourself thinking "anchors are tedious" or "I'll add links later" — STOP. Those are rationalizations. Block anchors and wiki links are mandatory, not optional.