Priority: P2
Problem
All SoT files, PRD.md, and EPIC templates contain placeholder content (e.g., [YOUR_PRODUCT], <!-- Template: fill in -->). A new user has no reference for what a completed artifact looks like:
- How detailed should a
BR-001 entry be?
- What does a well-written
UJ-001 user journey look like?
- How should PRD v0.1-v0.4 sections read when filled in?
- What does a populated EPIC look like?
Without a concrete example, users either under-specify (one-sentence entries) or over-specify (trying to fill everything at once).
Proposed Change
Create an examples/ directory (or an example branch) with a simple but complete walkthrough project. Suggested scope: a fictional Task Tracker API — simple enough to be universally understood, complex enough to exercise the key artifacts.
Minimum Example Content
| File |
Content |
examples/PRD.md |
Filled PRD through v0.4 (Spark, Market, Commercial, Journeys) |
examples/SoT/SoT.BUSINESS_RULES.md |
3-5 populated BR entries (e.g., BR-001 through BR-005) |
examples/SoT/SoT.USER_JOURNEYS.md |
2-3 user journeys (UJ-001, UJ-002) with linked personas (PER-001) |
examples/SoT/SoT.API_CONTRACTS.md |
1-2 API endpoint definitions (API-001, API-002) |
examples/epics/EPIC-01-mvp-crud.md |
One completed EPIC with filled Session State |
Key Qualities
- Realistic but simple — not a toy example, but not enterprise-scale
- Cross-referenced — IDs reference each other (e.g., EPIC links to BR-001, UJ-001)
- Shows progression — PRD sections build on each other (v0.1 problem → v0.2 market → v0.3 pricing → v0.4 journeys)
- Demonstrates Session State — the EPIC shows what a completed session state entry looks like
Files to Change
| File |
Change |
examples/ |
New directory with all example files |
README.md (or QUICKSTART.md) |
Add link: "See examples/ for a complete walkthrough" |
Acceptance Criteria
Verification
ls examples/ shows at least 5 files
grep -r "BR-001" examples/ returns hits in multiple files (cross-references work)
- Example PRD validates against
check-stage-gate.sh logic (sections exist for v0.1-v0.4)
- A new user can read the example and understand the expected quality/detail level
Related
Priority: P2
Problem
All SoT files, PRD.md, and EPIC templates contain placeholder content (e.g.,
[YOUR_PRODUCT],<!-- Template: fill in -->). A new user has no reference for what a completed artifact looks like:BR-001entry be?UJ-001user journey look like?Without a concrete example, users either under-specify (one-sentence entries) or over-specify (trying to fill everything at once).
Proposed Change
Create an
examples/directory (or anexamplebranch) with a simple but complete walkthrough project. Suggested scope: a fictional Task Tracker API — simple enough to be universally understood, complex enough to exercise the key artifacts.Minimum Example Content
examples/PRD.mdexamples/SoT/SoT.BUSINESS_RULES.mdexamples/SoT/SoT.USER_JOURNEYS.mdexamples/SoT/SoT.API_CONTRACTS.mdexamples/epics/EPIC-01-mvp-crud.mdKey Qualities
Files to Change
examples/README.md(orQUICKSTART.md)examples/for a complete walkthrough"Acceptance Criteria
examples/directory exists with at least: PRD.md, 3 SoT files, 1 EPICVerification
ls examples/shows at least 5 filesgrep -r "BR-001" examples/returns hits in multiple files (cross-references work)check-stage-gate.shlogic (sections exist for v0.1-v0.4)Related