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

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, ^AC2 anchors
• 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.2 not "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:

1. ☐ Verify every requirement has block anchor
2. ☐ Verify every acceptance criterion has block anchor
3. ☐ Verify all cross-references use wiki link syntax
4. ☐ Run npm run citation:validate <file-path>
5. ☐ Fix any broken links reported by citation-manager
6. ☐ Re-run validation until zero errors

You MUST run citation-manager validate as the final step. This is non-negotiable.

Common Mistakes

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)

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.