Skip to content

Commit 24a71b8

Browse files
rupurtrupurt
committed
feat(board): add milestone 03-formal-planning-process
Design formal document hierarchy: VISION → PRD → SRS → DESIGN → Stories - PRD per epic defines requirements and success criteria - SRS per milestone defines requirements with verification methods - DESIGN per milestone defines architecture and implementation - README files provide navigation and auto-updated progress - Just tasks to be updated for auto-sync
1 parent 57d416a commit 24a71b8

File tree

4 files changed

+424
-1
lines changed

4 files changed

+424
-1
lines changed

‎docs/board/epics/coherence-verification/README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,8 @@ Build a verification system that captures system behavior as visual artifacts (s
2525
|----|-----------|--------|
2626
| 01 | [Artifact Pipeline](milestones/01-verification-artifact-pipeline/) | done |
2727
| 02 | [Board Restructure](milestones/02-epic-based-project-hierarchy/) | done |
28-
| 03 | AI-Assisted Verification | planned |
28+
| 03 | [Formal Planning Process](milestones/03-formal-planning-process/) | backlog |
29+
| 04 | AI-Assisted Verification | planned |
2930

3031
## Success Criteria
3132

@@ -36,3 +37,6 @@ Build a verification system that captures system behavior as visual artifacts (s
3637
- [x] Story frontmatter uses single `scope` field (epic/milestone format)
3738
- [x] `just verify story <ID>` links artifacts to story acceptance criteria
3839
- [x] Story-specific reports at `verification/reports/<scope>/<id>.md`
40+
- [ ] Formal document hierarchy: VISION → PRD → SRS → DESIGN → Stories
41+
- [ ] Epic PRDs define requirements, milestones have SRS + DESIGN
42+
- [ ] Just tasks auto-update README progress and status

‎docs/board/epics/coherence-verification/milestones/03-formal-planning-process/DESIGN.md‎

Lines changed: 328 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,328 @@
1+
# Formal Planning Process — Design Document
2+
3+
> Traditional formal document hierarchy with automated progress tracking.
4+
5+
**SRS:** [SRS.md](SRS.md)
6+
7+
## Overview
8+
9+
Replace the ad-hoc planning structure with a formal hierarchy: VISION → PRD → SRS → DESIGN → Stories. Each document type has a clear purpose and templates. Just tasks automatically maintain progress and status in README navigation files.
10+
11+
## Architecture
12+
13+
### Document Hierarchy
14+
15+
```
16+
docs/
17+
├── VISION.md # Product vision & roadmap
18+
└── board/
19+
└── epics/
20+
└── <epic-name>/
21+
├── README.md # Navigation + summary
22+
├── PRD.md # Epic requirements
23+
└── milestones/
24+
└── <NN-milestone-name>/
25+
├── README.md # Navigation + summary
26+
├── SRS.md # Requirements + verification
27+
└── DESIGN.md # Architecture + design
28+
```
29+
30+
### Document Purposes
31+
32+
| Document | Contains | Answers |
33+
|----------|----------|---------|
34+
| `VISION.md` | Product direction, goals, non-goals, high-level architecture | Where are we going? |
35+
| Epic `PRD.md` | User needs, business value, success criteria, scope | What problem does this epic solve? |
36+
| Epic `README.md` | Links to PRD + milestones, status summary | How do I navigate this epic? |
37+
| `SRS.md` | Functional/non-functional requirements, verification methods | What must be built and how do we verify it? |
38+
| `DESIGN.md` | Architecture decisions, component design, data flow, trade-offs | How do we build it? |
39+
| Milestone `README.md` | Links to SRS + DESIGN, story index, status | How do I navigate this milestone? |
40+
41+
## Key Decisions
42+
43+
| Decision | Choice | Rationale |
44+
|----------|--------|-----------|
45+
| Document naming | Uppercase (PRD.md, SRS.md, DESIGN.md) | Visual distinction for formal docs |
46+
| Keep README.md | Yes | GitHub navigation, summary at a glance |
47+
| PRD per epic | Yes | Epics are natural product boundaries |
48+
| SRS per milestone | Yes | Milestones are implementation units |
49+
| Verification in SRS | Yes | Requirements and verification belong together |
50+
| Replace implementation.md | With SRS.md | SRS lists requirements + links to stories |
51+
52+
## Templates
53+
54+
### VISION.md (Product Level)
55+
56+
```markdown
57+
# [Product Name]
58+
59+
> [One-line vision statement]
60+
61+
## Goals
62+
63+
1. **[Goal 1]** — Description
64+
2. **[Goal 2]** — Description
65+
66+
## Non-Goals
67+
68+
- [What we're explicitly not doing]
69+
70+
## Architecture Overview
71+
72+
[High-level system diagram]
73+
74+
## Epics
75+
76+
| Epic | Status | Description |
77+
|------|--------|-------------|
78+
| [epic-name](board/epics/epic-name/) | active | Brief description |
79+
80+
## Roadmap
81+
82+
[Future direction, phases]
83+
```
84+
85+
### Epic PRD.md
86+
87+
```markdown
88+
# [Epic Name] — Product Requirements
89+
90+
> [One-line value proposition]
91+
92+
## Problem Statement
93+
94+
[What user problem does this solve?]
95+
96+
## Users
97+
98+
[Who benefits from this?]
99+
100+
## Requirements
101+
102+
### Functional Requirements
103+
104+
| ID | Requirement | Priority |
105+
|----|-------------|----------|
106+
| FR-01 | [User can...] | must |
107+
| FR-02 | [System shall...] | should |
108+
109+
### Non-Functional Requirements
110+
111+
| ID | Requirement | Priority |
112+
|----|-------------|----------|
113+
| NFR-01 | [Performance: ...] | must |
114+
115+
## Success Criteria
116+
117+
- [ ] [Measurable outcome 1]
118+
- [ ] [Measurable outcome 2]
119+
120+
## Milestones
121+
122+
| ID | Milestone | Status |
123+
|----|-----------|--------|
124+
| 01 | [Name](milestones/01-name/) | done |
125+
```
126+
127+
### Epic README.md
128+
129+
```markdown
130+
---
131+
id: <epic-id>
132+
title: <Epic Title>
133+
status: active | done
134+
---
135+
136+
# [Epic Title]
137+
138+
> [One-line from PRD]
139+
140+
## Documents
141+
142+
| Document | Description |
143+
|----------|-------------|
144+
| [PRD.md](PRD.md) | Product requirements and success criteria |
145+
146+
## Milestones
147+
148+
| ID | Milestone | Status | Progress |
149+
|----|-----------|--------|----------|
150+
| 01 | [Name](milestones/01-name/) | done | 6/6 |
151+
152+
## Status
153+
154+
**Active Milestone:** NN-name
155+
**Stories In Progress:** N
156+
**Completion:** N/M milestones done
157+
```
158+
159+
### Milestone SRS.md
160+
161+
```markdown
162+
# [Milestone Name] — Software Requirements Specification
163+
164+
> [One-line goal]
165+
166+
**Epic:** [Link to epic PRD](../PRD.md)
167+
**Status:** in-progress
168+
169+
## Scope
170+
171+
[What this milestone delivers]
172+
173+
## Requirements
174+
175+
### Functional Requirements
176+
177+
| ID | Requirement | Source | Verification |
178+
|----|-------------|--------|--------------|
179+
| SRS-01 | [Requirement] | FR-01 | [verification method] |
180+
181+
### Non-Functional Requirements
182+
183+
| ID | Requirement | Source | Verification |
184+
|----|-------------|--------|--------------|
185+
| SRS-NFR-01 | [Requirement] | NFR-01 | [verification method] |
186+
187+
## Stories
188+
189+
| Story | Requirements | Status |
190+
|-------|--------------|--------|
191+
| [ID](link) | SRS-01, SRS-02 | done |
192+
193+
## Traceability
194+
195+
- **Source:** Epic PRD requirements
196+
- **Implements:** Stories
197+
- **Verified by:** `just verify story <ID>`
198+
```
199+
200+
### Milestone DESIGN.md
201+
202+
```markdown
203+
# [Milestone Name] — Design Document
204+
205+
> [One-line summary of approach]
206+
207+
**SRS:** [SRS.md](SRS.md)
208+
209+
## Overview
210+
211+
[How this milestone achieves its requirements]
212+
213+
## Architecture
214+
215+
[Diagrams, component relationships]
216+
217+
## Key Decisions
218+
219+
| Decision | Choice | Rationale |
220+
|----------|--------|-----------|
221+
| [Decision] | [Choice] | [Why] |
222+
223+
## Components
224+
225+
### [Component 1]
226+
227+
[Purpose, interface, behavior]
228+
229+
## Data Flow
230+
231+
[How data moves through the system]
232+
233+
## Error Handling
234+
235+
[What can go wrong, how to handle it]
236+
```
237+
238+
### Milestone README.md
239+
240+
```markdown
241+
---
242+
id: <milestone-id>
243+
title: <Milestone Title>
244+
status: backlog | in-progress | done
245+
epic: <epic-id>
246+
---
247+
248+
# [Milestone Title]
249+
250+
> [One-line from SRS]
251+
252+
## Documents
253+
254+
| Document | Description |
255+
|----------|-------------|
256+
| [SRS.md](SRS.md) | Requirements and verification criteria |
257+
| [DESIGN.md](DESIGN.md) | Architecture and implementation details |
258+
259+
## Stories
260+
261+
| Story | Description | Status |
262+
|-------|-------------|--------|
263+
| [ID](link) | Description | done |
264+
265+
## Progress
266+
267+
**Requirements:** N/M verified
268+
**Stories:** N/M complete
269+
```
270+
271+
## Just Task Updates
272+
273+
### Commands to Update
274+
275+
| Command | New Behavior |
276+
|---------|--------------|
277+
| `just board generate` | Regenerate epic + milestone READMEs with progress |
278+
| `just board done-milestone` | Update epic README milestone table + progress |
279+
| `just board start-milestone` | Update epic README milestone table |
280+
| `just board done` | Update milestone README story table + progress |
281+
| `just board start` | Update milestone README story table |
282+
| `just board new epic` | Create directory with README.md + PRD.md templates |
283+
| `just board new milestone` | Create directory with README.md + SRS.md + DESIGN.md templates |
284+
285+
### Auto-Updated Fields
286+
287+
| Document | Auto-Updated Fields |
288+
|----------|---------------------|
289+
| Epic README.md | Milestone table (status), Progress section |
290+
| Milestone README.md | Story table (status), Progress section |
291+
292+
## Migration Strategy
293+
294+
### Phase 1: Structure
295+
296+
1. Rename `docs/PRD.md` → `docs/VISION.md`
297+
2. Update all links referencing PRD.md
298+
3. Create templates in `docs/board/templates/`
299+
300+
### Phase 2: Epic Migration
301+
302+
For each epic:
303+
1. Extract requirements from current README.md to new PRD.md
304+
2. Update README.md to new navigation format
305+
3. Preserve existing content where appropriate
306+
307+
### Phase 3: Milestone Migration
308+
309+
For each milestone:
310+
1. Rename `design.md` → `DESIGN.md`
311+
2. Create SRS.md from milestone requirements + implementation.md story list
312+
3. Update README.md to new navigation format
313+
4. Delete `implementation.md` after migration
314+
315+
### Phase 4: Tooling
316+
317+
1. Update `just board new epic` command
318+
2. Update `just board new milestone` command
319+
3. Update `just board generate` for README progress
320+
4. Update story/milestone commands for README sync
321+
322+
## Error Handling
323+
324+
| Scenario | Behavior |
325+
|----------|----------|
326+
| Missing PRD.md in epic | `just board generate` warns, skips progress |
327+
| Missing SRS.md in milestone | `just board generate` warns, skips progress |
328+
| Story links missing in README | Regenerate from frontmatter |

‎docs/board/epics/coherence-verification/milestones/03-formal-planning-process/README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
id: 03-formal-planning-process
3+
title: Formal Planning Process
4+
status: backlog
5+
epic: coherence-verification
6+
created: 2026-01-18
7+
---
8+
9+
# Formal Planning Process
10+
11+
> Establish traceable document hierarchy from vision through verification.
12+
13+
## Documents
14+
15+
| Document | Description |
16+
|----------|-------------|
17+
| [SRS.md](SRS.md) | Requirements and verification criteria |
18+
| [DESIGN.md](DESIGN.md) | Document templates and just task updates |
19+
20+
## Stories
21+
22+
| Story | Description | Status |
23+
|-------|-------------|--------|
24+
| — | Stories to be created after design approval | — |
25+
26+
## Progress
27+
28+
**Requirements:** 0/10 verified
29+
**Stories:** 0/0 complete

0 commit comments

Comments
 (0)