Skip to content

Commit d72bbd4

Browse files
rupurtrupurt
committed
feat(board): add learnings capture milestone and stories
Add milestone 05-learnings-capture to coherence-verification epic with 6 stories for capturing and propagating learnings from completed work. Stories: - CHORE0202: Add learnings template to story template - FEAT0203: Implement learning capture on story completion - FEAT0204: Implement milestone learnings aggregation - FEAT0205: Add just learn reflect command - FEAT0206: Add just learn apply propagation engine - FEAT0207: Add just learn list command Also fixes octal interpretation bug in _next-milestone function.
1 parent 4cc4d71 commit d72bbd4

File tree

12 files changed

+491
-6
lines changed

12 files changed

+491
-6
lines changed

‎.justfiles/board.just‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -635,16 +635,18 @@ _next-milestone:
635635
for ms_dir in epics/*/milestones/[0-9]*/; do
636636
[[ -d "$ms_dir" ]] || continue
637637
num=$(basename "$ms_dir" | sed -n 's/^\([0-9]*\).*/\1/p')
638-
if [[ -n "$num" ]] && [[ "$num" -gt "$max" ]]; then
639-
max=$num
638+
# Use 10# to force decimal interpretation (avoid octal issues with 08, 09)
639+
if [[ -n "$num" ]] && [[ 10#$num -gt $max ]]; then
640+
max=$((10#$num))
640641
fi
641642
done
642643
# Also check top-level milestones for backwards compatibility
643644
for d in milestones/[0-9]*/; do
644645
[[ -d "$d" ]] || continue
645646
num=$(basename "$d" | sed -n 's/^\([0-9]*\).*/\1/p')
646-
if [[ -n "$num" ]] && [[ "$num" -gt "$max" ]]; then
647-
max=$num
647+
# Use 10# to force decimal interpretation (avoid octal issues with 08, 09)
648+
if [[ -n "$num" ]] && [[ 10#$num -gt $max ]]; then
649+
max=$((10#$num))
648650
fi
649651
done
650652
printf "%02d" $((max + 1))

‎docs/board/README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
| Story | Type | Priority | Scope |
1515
|-------|------|----------|-------|
1616
| [[CHORE][0146]-create-ai-verification-config](stages/backlog/stories/[CHORE][0146]-create-ai-verification-config.md) | chore | high | coherence-verification/04-ai-assisted-verification |
17+
| [[CHORE][0202]-add-learnings-template](stages/backlog/stories/[CHORE][0202]-add-learnings-template.md) | chore | high | coherence-verification/05-learnings-capture |
1718
| [[FEAT][0115]-eval-web-ui](stages/backlog/stories/[FEAT][0115]-eval-web-ui.md) | feat | medium | evals/39-performance-evaluation |
1819
| [[FEAT][0116]-pty-server-core](stages/backlog/stories/[FEAT][0116]-pty-server-core.md) | feat | medium | tui/46-terminal-server |
1920
| [[FEAT][0117]-session-management](stages/backlog/stories/[FEAT][0117]-session-management.md) | feat | medium | tui/46-terminal-server |
@@ -24,6 +25,11 @@
2425
| [[FEAT][0199]-implement-model-router](stages/backlog/stories/[FEAT][0199]-implement-model-router.md) | feat | high | coherence-verification/04-ai-assisted-verification |
2526
| [[FEAT][0200]-implement-ai-report-generator](stages/backlog/stories/[FEAT][0200]-implement-ai-report-generator.md) | feat | high | coherence-verification/04-ai-assisted-verification |
2627
| [[FEAT][0201]-add-verify-ai-command](stages/backlog/stories/[FEAT][0201]-add-verify-ai-command.md) | feat | high | coherence-verification/04-ai-assisted-verification |
28+
| [[FEAT][0203]-implement-story-learning-capture](stages/backlog/stories/[FEAT][0203]-implement-story-learning-capture.md) | feat | high | coherence-verification/05-learnings-capture |
29+
| [[FEAT][0204]-implement-milestone-learnings-aggregation](stages/backlog/stories/[FEAT][0204]-implement-milestone-learnings-aggregation.md) | feat | high | coherence-verification/05-learnings-capture |
30+
| [[FEAT][0205]-add-learn-reflect-command](stages/backlog/stories/[FEAT][0205]-add-learn-reflect-command.md) | feat | medium | coherence-verification/05-learnings-capture |
31+
| [[FEAT][0206]-add-learn-apply-command](stages/backlog/stories/[FEAT][0206]-add-learn-apply-command.md) | feat | medium | coherence-verification/05-learnings-capture |
32+
| [[FEAT][0207]-add-learn-list-command](stages/backlog/stories/[FEAT][0207]-add-learn-list-command.md) | feat | low | coherence-verification/05-learnings-capture |
2733

2834
## Icebox
2935

@@ -48,14 +54,15 @@
4854
| [35-guided-setup](epics/cli/milestones/35-guided-setup/) | done |
4955
| [54-enhanced-cli-experience](epics/cli/milestones/54-enhanced-cli-experience/) | planned |
5056

51-
### [coherence-verification](epics/coherence-verification/) (active) - 4 milestones, 3 done
57+
### [coherence-verification](epics/coherence-verification/) (active) - 5 milestones, 3 done
5258

5359
| Milestone | Status |
5460
|-----------|--------|
5561
| [01-verification-artifact-pipeline](epics/coherence-verification/milestones/01-verification-artifact-pipeline/) | done |
5662
| [02-epic-based-project-hierarchy](epics/coherence-verification/milestones/02-epic-based-project-hierarchy/) | done |
5763
| [03-formal-planning-process](epics/coherence-verification/milestones/03-formal-planning-process/) | done |
5864
| [04-ai-assisted-verification](epics/coherence-verification/milestones/04-ai-assisted-verification/) | backlog |
65+
| [05-learnings-capture](epics/coherence-verification/milestones/05-learnings-capture/) | backlog |
5966

6067
### [evals](epics/evals/) (planned) - 6 milestones, 0 done
6168

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,13 @@ Build a verification system that captures system behavior as visual artifacts (s
2222
<!-- BEGIN GENERATED -->
2323
## Milestones
2424

25-
**Progress:** 3/4 milestones complete, 15/21 stories done
25+
**Progress:** 3/5 milestones complete, 15/27 stories done
2626

2727
| ID | Milestone | Stories | Status |
2828
|----|-----------|---------|--------|
2929
| 01 | [Verification Artifact Pipeline](milestones/01-verification-artifact-pipeline/) | 0/0 | done |
3030
| 02 | [Epic-Based Project Hierarchy](milestones/02-epic-based-project-hierarchy/) | 6/6 | done |
3131
| 03 | [Formal Planning Process](milestones/03-formal-planning-process/) | 9/9 | done |
3232
| 04 | [AI-Assisted Verification](milestones/04-ai-assisted-verification/) | 0/6 | backlog |
33+
| 05 | [Learnings Capture](milestones/05-learnings-capture/) | 0/6 | backlog |
3334
<!-- END GENERATED -->

‎docs/board/epics/coherence-verification/milestones/05-learnings-capture/DESIGN.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# Learnings Capture — Design Document
2+
3+
> Architecture and implementation details for the learnings capture system.
4+
5+
**Milestone:** [05-learnings-capture](README.md)
6+
**SRS:** [SRS.md](SRS.md)
7+
8+
## Architecture
9+
10+
```
11+
┌─────────────────────────────────────────────────────────────────┐
12+
│ Learnings Capture System │
13+
├─────────────────────────────────────────────────────────────────┤
14+
│ │
15+
│ Triggers: │
16+
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
17+
│ │ just board │ │ just board │ │ just learn │ │
18+
│ │ done <id> │ │ done- │ │ reflect │ │
19+
│ │ │ │ milestone │ │ │ │
20+
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
21+
│ │ │ │ │
22+
│ ▼ ▼ ▼ │
23+
│ ┌────────────────────────────────────────────────────┐ │
24+
│ │ Learning Capture Prompt │ │
25+
│ │ (AI-guided reflection on what was learned) │ │
26+
│ └────────────────────────────┬───────────────────────┘ │
27+
│ │ │
28+
│ ▼ │
29+
│ ┌────────────────────────────────────────────────────┐ │
30+
│ │ Storage Layer │ │
31+
│ │ ┌────────────┐ ┌─────────────┐ ┌──────────────┐ │ │
32+
│ │ │ Story file │ │ Milestone │ │ docs/ │ │ │
33+
│ │ │ ## Learn.. │ │ LEARNINGS.md│ │ learnings/ │ │ │
34+
│ │ └────────────┘ └─────────────┘ └──────────────┘ │ │
35+
│ └────────────────────────────────────────────────────┘ │
36+
│ │ │
37+
│ ▼ │
38+
│ ┌────────────────────────────────────────────────────┐ │
39+
│ │ Propagation Engine │ │
40+
│ │ (AI suggests where to apply, user decides) │ │
41+
│ └────────────────────────────────────────────────────┘ │
42+
│ │
43+
└─────────────────────────────────────────────────────────────────┘
44+
```
45+
46+
## Components
47+
48+
### 1. Learning Template
49+
50+
Structured format for all learnings:
51+
52+
```markdown
53+
### L001: [Brief title]
54+
55+
| Field | Value |
56+
|-------|-------|
57+
| **Category** | process / architecture / verification / code |
58+
| **Context** | What triggered this learning |
59+
| **Insight** | What we learned |
60+
| **Suggested Action** | Concrete next step |
61+
| **Applies To** | Where this should propagate |
62+
| **Applied** | (empty until propagated) |
63+
```
64+
65+
### 2. Story Learning Capture
66+
67+
Added to `just board done`:
68+
69+
```bash
70+
# Prompt flow
71+
echo "What went well with this story? (Enter to skip)"
72+
read well
73+
echo "What was harder than expected? (Enter to skip)"
74+
read hard
75+
echo "What would you do differently? (Enter to skip)"
76+
read different
77+
78+
# If any input provided, append to story file
79+
if [[ -n "$well" || -n "$hard" || -n "$different" ]]; then
80+
# Generate structured learning and append to story
81+
fi
82+
```
83+
84+
### 3. Milestone Learnings Aggregation
85+
86+
Created by `just board done-milestone`:
87+
88+
```markdown
89+
# Milestone Learnings: 05-learnings-capture
90+
91+
> Aggregated learnings from completed stories.
92+
93+
## Story Learnings
94+
95+
### From FEAT0203: Implement story learning capture
96+
97+
[Copy of learnings from story file]
98+
99+
## Synthesis
100+
101+
### ML001: [Milestone-level insight]
102+
103+
| Field | Value |
104+
|-------|-------|
105+
| **Category** | process |
106+
| **Context** | Completing the learnings capture milestone |
107+
| **Insight** | [User-provided synthesis] |
108+
| **Suggested Action** | [Concrete next step] |
109+
| **Applies To** | [Target files/conventions] |
110+
```
111+
112+
### 4. Ad-hoc Reflection
113+
114+
`just learn reflect` creates files in `docs/learnings/`:
115+
116+
```
117+
docs/learnings/
118+
├── 2026-01-19-verification-hints.md
119+
├── 2026-01-20-test-patterns.md
120+
└── ...
121+
```
122+
123+
### 5. Propagation Engine
124+
125+
`just learn apply` workflow:
126+
127+
1. Scan all learnings (stories, milestones, ad-hoc) for unapplied entries
128+
2. For each, AI suggests concrete changes to target files
129+
3. Present diff-style preview to user
130+
4. User: accept / reject / edit
131+
5. Apply accepted changes, mark learning as applied
132+
133+
## Commands
134+
135+
| Command | Description |
136+
|---------|-------------|
137+
| `just board done <id>` | (Modified) Prompts for learnings before completing |
138+
| `just board done-milestone <id>` | (Modified) Aggregates learnings, prompts for synthesis |
139+
| `just learn reflect` | Interactive ad-hoc learning capture |
140+
| `just learn apply` | Suggest and apply pending learnings |
141+
| `just learn list` | Show all learnings with status |
142+
143+
## File Locations
144+
145+
| Type | Location |
146+
|------|----------|
147+
| Story learnings | `docs/board/stages/done/stories/[TYPE][NNNN]-name.md` (## Learnings section) |
148+
| Milestone learnings | `docs/board/epics/*/milestones/*/LEARNINGS.md` |
149+
| Ad-hoc learnings | `docs/learnings/YYYY-MM-DD-topic.md` |
150+
151+
## Learning ID Format
152+
153+
| Scope | Format | Example |
154+
|-------|--------|---------|
155+
| Story | `L001`, `L002` | Per-story sequential |
156+
| Milestone | `ML001`, `ML002` | Per-milestone sequential |
157+
| Ad-hoc | Filename | `2026-01-19-verification-hints` |
158+
159+
## Applied Status Tracking
160+
161+
When a learning is propagated:
162+
163+
```markdown
164+
| **Applied** | CLAUDE.md (2026-01-20), CONVENTIONS.md (2026-01-20) |
165+
```
166+
167+
## Error Handling
168+
169+
| Scenario | Behavior |
170+
|----------|----------|
171+
| User skips all prompts | No learnings added, story/milestone still completes |
172+
| Learning file missing | Create with header, then append |
173+
| Propagation target doesn't exist | Warn and skip that target |
174+
| User rejects all suggestions | Mark as "reviewed" not "applied" |
175+

‎docs/board/epics/coherence-verification/milestones/05-learnings-capture/README.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
id: 05-learnings-capture
3+
title: Learnings Capture
4+
status: backlog
5+
epic: coherence-verification
6+
created: 2026-01-19
7+
---
8+
9+
# Learnings Capture
10+
11+
> Capture and propagate learnings from completed work to improve process, architecture, and verification.
12+
13+
## Documents
14+
15+
| Document | Description |
16+
|----------|-------------|
17+
| [SRS.md](SRS.md) | Requirements and verification criteria |
18+
| [DESIGN.md](DESIGN.md) | Architecture and implementation details |
19+
20+
## Stories
21+
22+
| # | Story | Description | Status |
23+
|---|-------|-------------|--------|
24+
| 1 | [CHORE0202](../../../../stages/backlog/stories/[CHORE][0202]-add-learnings-template.md) | Add learnings template to story template | backlog |
25+
| 2 | [FEAT0203](../../../../stages/backlog/stories/[FEAT][0203]-implement-story-learning-capture.md) | Implement learning capture on story completion | backlog |
26+
| 3 | [FEAT0204](../../../../stages/backlog/stories/[FEAT][0204]-implement-milestone-learnings-aggregation.md) | Implement milestone learnings aggregation | backlog |
27+
| 4 | [FEAT0205](../../../../stages/backlog/stories/[FEAT][0205]-add-learn-reflect-command.md) | Add just learn reflect command | backlog |
28+
| 5 | [FEAT0206](../../../../stages/backlog/stories/[FEAT][0206]-add-learn-apply-command.md) | Add just learn apply propagation engine | backlog |
29+
| 6 | [FEAT0207](../../../../stages/backlog/stories/[FEAT][0207]-add-learn-list-command.md) | Add just learn list command | backlog |
30+
31+
## Progress
32+
33+
**Requirements:** 0/13 verified
34+
**Stories:** 0/6 complete
35+

‎docs/board/epics/coherence-verification/milestones/05-learnings-capture/SRS.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Learnings Capture — Software Requirements Specification
2+
3+
> Capture and propagate learnings from completed work to improve process, architecture, and verification.
4+
5+
**Epic:** [Coherence Verification](../../PRD.md)
6+
**Status:** backlog
7+
8+
## Scope
9+
10+
Add a system to capture learnings at multiple points (story completion, milestone completion, ad-hoc reflection) and propagate them to improve CLAUDE.md, templates, conventions, and code patterns.
11+
12+
## Requirements
13+
14+
### Functional Requirements
15+
16+
| ID | Requirement | Source | Verification |
17+
|----|-------------|--------|--------------|
18+
| SRS-01 | Story template includes `## Learnings` section | FR-06 | file exists |
19+
| SRS-02 | `just board done` prompts for learnings before completing story | FR-06 | manual |
20+
| SRS-03 | Learnings use structured template (category, context, insight, action, applies-to) | FR-06 | unit test |
21+
| SRS-04 | `just board done-milestone` aggregates story learnings into LEARNINGS.md | FR-06 | file exists |
22+
| SRS-05 | Milestone completion prompts for synthesis learnings | FR-06 | manual |
23+
| SRS-06 | `just learn reflect` enables ad-hoc learning capture | FR-06 | manual |
24+
| SRS-07 | Ad-hoc learnings saved to `docs/learnings/YYYY-MM-DD-topic.md` | FR-06 | file exists |
25+
| SRS-08 | `just learn apply` suggests propagation targets for unapplied learnings | FR-06 | manual |
26+
| SRS-09 | User can accept/reject/edit suggested changes | FR-06 | manual |
27+
| SRS-10 | `just learn list` shows all learnings with applied/pending status | FR-06 | manual |
28+
29+
### Non-Functional Requirements
30+
31+
| ID | Requirement | Source | Verification |
32+
|----|-------------|--------|--------------|
33+
| SRS-NFR-01 | Learning capture is optional (can skip if no learnings) | NFR-03 | manual |
34+
| SRS-NFR-02 | AI-assisted prompts guide reflection without being prescriptive | NFR-03 | manual |
35+
| SRS-NFR-03 | Implementation in bash/just (consistent with board tooling) | NFR-03 | code review |
36+
37+
## Stories
38+
39+
| Story | Requirements | Status |
40+
|-------|--------------|--------|
41+
| [CHORE0202](../../../../stages/backlog/stories/[CHORE][0202]-add-learnings-template.md) | SRS-01 | backlog |
42+
| [FEAT0203](../../../../stages/backlog/stories/[FEAT][0203]-implement-story-learning-capture.md) | SRS-02, SRS-03 | backlog |
43+
| [FEAT0204](../../../../stages/backlog/stories/[FEAT][0204]-implement-milestone-learnings-aggregation.md) | SRS-04, SRS-05 | backlog |
44+
| [FEAT0205](../../../../stages/backlog/stories/[FEAT][0205]-add-learn-reflect-command.md) | SRS-06, SRS-07 | backlog |
45+
| [FEAT0206](../../../../stages/backlog/stories/[FEAT][0206]-add-learn-apply-command.md) | SRS-08, SRS-09 | backlog |
46+
| [FEAT0207](../../../../stages/backlog/stories/[FEAT][0207]-add-learn-list-command.md) | SRS-10 | backlog |
47+
48+
## Traceability
49+
50+
- **Source:** PRD FR-06 (Generate verification reports), extended for process improvement
51+
- **Implements:** Stories listed above
52+
- **Verified by:** Manual testing of commands, file existence checks
53+

‎docs/board/stages/backlog/stories/[CHORE][0202]-add-learnings-template.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
id: CHORE0202
3+
title: Add learnings template to story template
4+
type: chore
5+
status: backlog
6+
priority: high
7+
scope: coherence-verification/05-learnings-capture
8+
depends: []
9+
estimate: 30m
10+
created: 2026-01-19
11+
---
12+
13+
# Add learnings template to story template
14+
15+
## Summary
16+
17+
Update the story template to include a `## Learnings` section with the structured template format.
18+
19+
## Acceptance Criteria
20+
21+
- [ ] Story template includes `## Learnings` section at the end
22+
- [ ] Template shows structured format (category, context, insight, action, applies-to)
23+
- [ ] Example learning entry included as comment
24+
- [ ] CONVENTIONS.md updated to document learnings format
25+
26+
## Implementation Notes
27+
28+
**SRS Requirements:** SRS-01
29+
30+
**Files:**
31+
- Modify: `docs/board/templates/story.md`
32+
- Modify: `docs/board/CONVENTIONS.md`
33+

0 commit comments

Comments
 (0)