majiayu000 Writing Requirements Documents
Create requirements documents 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
- Documenting epics with user stories
- 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]] |
| Epic (header-based) | Epic 1, Epic 2... | None | [[#Epic 1 - Name|Epic 1]] |
| User Story (header-based) | Story 1.1, 1.2... | None | [[#Story 1.1 Title|Story 1.1]] |
| Acceptance Criteria | AC within story | ^US1-1AC1 |
[[#^US1-1AC1|AC1]] |
Link Types:
- Internal wiki link to block anchor:
[[#^FR1|FR1]]- For requirements/ACs - Internal wiki link to header:
[[#Story 1.1 Title|Story 1.1]]- For epics/stories - 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. 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 Epic with user stories
npm run citation:extract:header /path/to/template-prd.md -- "Epic 1"
Template Source: /Users/wesleyfrederick/Documents/ObsidianVaultNew/0_SoftwareDevelopment/claude-code-knowledgebase/design-docs/features/version-based-analysis/version-based-analysis-prd.md
Document Structure
Requirements Section
## Requirements
### Functional Requirements
- FR1: The system SHALL [specific, testable action]. ^FR1
- FR2: The system SHALL [another requirement]. ^FR2
### Non-Functional Requirements
- NFR1: [Quality attribute like performance, security]. ^NFR1
- NFR2: [Maintainability, scalability requirement]. ^NFR2
Epic with User Stories
## Epic 1 - [Epic Name]
[Epic description and business value]
### Story 1.1: [Story Title]
**As a** [role],
**I want** [capability],
**so that** [business value].
#### Acceptance Criteria
1. WHEN [condition], THEN the system SHALL [expected behavior]. ^US1-1AC1
2. IF [condition], THEN the system shall [behavior]. ^US1-1AC2
*Depends On*: None
*Functional Requirements*: [[#^FR1|FR1]], [[#^FR2|FR2]]
*Non-Functional Requirements*: [[#^NFR1|NFR1]]
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, US1.1 |
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
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 agile 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. |
| "Header links are good enough for stories" | Markdown links work | Yes! Headers can use [[#Story 1.1 Title|Story 1.1]] or [Story 1.1](#story-11-title). This is correct. |
Example: Before vs After
Before (Wrong)
## Requirements
**REQ-F1:** System shall export to JSON.
Related User Stories: US-001
After (Correct)
## Requirements
### Functional Requirements
- FR1: The system SHALL export validation reports to JSON format. ^FR1
### User Story Reference
*Functional Requirements*: [[#^FR1|FR1]]
Integration with Other Tools
- After brainstorming: Use this skill to formalize design into requirements
- Before writing-plans: 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.