Skip to content

Commit c09719e

Browse files
committed
feat: add quick reference index to LEARNINGS.md
- Refactored index code to be generic (supports both files) - Normalized LEARNINGS.md entries to full timestamp format - Auto-updates index on `ctx add learning` - New `ctx learnings reindex` command for manual regeneration - Converted inline bullet entries to structured format Both DECISIONS.md and LEARNINGS.md now have scannable indexes for AI agents with limited context budgets. Signed-off-by: Jose Alekhinne <alekhinejose@gmail.com>
1 parent cfe24d0 commit c09719e

7 files changed

Lines changed: 413 additions & 74 deletions

File tree

‎.context/LEARNINGS.md‎

Lines changed: 118 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,118 @@
11
# Learnings
22

3-
> Ordered reverse-chronologically (newest first) to ensure most relevant items
4-
> are read first regardless of token budget.
3+
<!-- INDEX:START -->
4+
| Date | Learning |
5+
|------------|------------------------------------------------------|
6+
| 2026-01-28 | Required flags now enforced for learnings |
7+
| 2026-01-28 | Claude Code Hooks Receive JSON via Stdin |
8+
| 2026-01-28 | Changelogs vs Blogs serve different audiences |
9+
| 2026-01-28 | IDE is already the UI |
10+
| 2026-01-28 | Subtasks complete does not mean parent task complete |
11+
| 2026-01-28 | AI session JSONL formats are not standardized |
12+
| 2026-01-27 | Always Complete Decision Record Sections |
13+
| 2026-01-27 | Slash Commands Require Matching Permissions |
14+
| 2026-01-26 | Go json.Marshal Escapes Shell Characters |
15+
| 2026-01-26 | Claude Code Hook Key Names |
16+
| 2026-01-25 | defer os.Chdir Fails errcheck Linter |
17+
| 2026-01-25 | golangci-lint Go Version Mismatch in CI |
18+
| 2026-01-25 | CI Tests Need CTX_SKIP_PATH_CHECK |
19+
| 2026-01-25 | AGENTS.md Is Not Auto-Loaded |
20+
| 2026-01-25 | Hook Regex Can Overfit |
21+
| 2026-01-25 | Autonomous Mode Creates Technical Debt |
22+
| 2026-01-23 | ctx agent vs Manual File Reading Trade-offs |
23+
| 2026-01-23 | Claude Code Skills Format |
24+
| 2026-01-23 | Infer Intent on "Do You Remember?" Questions |
25+
| 2026-01-23 | Always Use ctx from PATH |
26+
| 2026-01-21 | Exit Criteria Must Include Verification |
27+
| 2026-01-21 | Orchestrator vs Agent Tasks Must Be Separate |
28+
| 2026-01-21 | One Templates Directory, Not Two |
29+
| 2026-01-21 | Hooks Should Use PATH, Not Hardcoded Paths |
30+
| 2026-01-20 | ctx and Ralph Loop Are Separate Systems |
31+
| 2026-01-20 | .context/ Is NOT a Claude Code Primitive |
32+
| 2026-01-20 | SessionEnd Hook Catches Ctrl+C |
33+
| 2026-01-20 | Session Filename Must Include Time |
34+
| 2026-01-20 | Two Tiers of Persistence |
35+
| 2026-01-20 | Auto-Load Works, Auto-Save Was Missing |
36+
| 2026-01-20 | Always Backup Before Modifying User Files |
37+
| 2026-01-19 | CGO Must Be Disabled for ARM64 Linux |
38+
<!-- INDEX:END -->
539

640
---
741

842
## [2026-01-28-191951] Required flags now enforced for learnings
943

1044
**Context**: Implemented ctx add learning flags to match decision's ADR pattern
1145

12-
**Lesson**: Structured entries with Context/Lesson/Application are more useful than one-liners
46+
**Lesson**: Structured entries with Context/Lesson/Application are more useful
47+
than one-liners
1348

14-
**Application**: Always use ctx add learning with all three flags; agents guided via AGENT_PLAYBOOK.md
49+
**Application**: Always use ctx add learning with all three flags; agents
50+
guided via AGENT_PLAYBOOK.md
1551

1652
## [2026-01-28-194113] Claude Code Hooks Receive JSON via Stdin
1753

18-
**Context**: Debugging Claude Code PreToolUse hooks - they were not receiving command data when using environment variables like CLAUDE_TOOL_INPUT
54+
**Context**: Debugging Claude Code PreToolUse hooks - they were not receiving
55+
command data when using environment variables like CLAUDE_TOOL_INPUT
1956

20-
**Lesson**: Claude Code hooks receive input as JSON via stdin, not environment variables. Use HOOK_INPUT=$(cat) then parse with jq: COMMAND=$(echo "$HOOK_INPUT" | jq -r ".tool_input.command // empty")
57+
**Lesson**: Claude Code hooks receive input as JSON via stdin, not environment
58+
variables. Use HOOK_INPUT=$(cat) then parse with
59+
jq: COMMAND=$(echo "$HOOK_INPUT" | jq -r ".tool_input.command // empty")
2160

22-
**Application**: All hook scripts should read stdin for input. The JSON structure includes .tool_input.command for Bash commands. Test hooks with debug logging to /tmp/ to verify they receive expected data.
61+
**Application**: All hook scripts should read stdin for input. The JSON
62+
structure includes .tool_input.command for Bash commands. Test hooks with
63+
debug logging to /tmp/ to verify they receive expected data.
2364

24-
- **[2026-01-28-072838]** Changelogs document WHAT; blogs explain WHY. Same information, different engagement. Changelogs are for machines (audits, dependency trackers). Blogs are for humans (narrative, context, lessons). When synthesizing session history, output both: changelog for completeness, blog for readability.
65+
## [2026-01-28-072838] Changelogs vs Blogs serve different audiences
2566

26-
- **[2026-01-28-051426]** IDE is already the UI: Discovery, search, and
27-
editing of .context/ markdown files works better in VS Code/IDE than any
28-
custom UI we'd build. Full-text search, git integration, extensions - all free.
29-
Don't reinvent the editor.
67+
**Context**: Synthesizing session history into documentation
3068

31-
- **[2026-01-28-040915]** Subtasks complete does not mean parent task complete
69+
**Lesson**: Changelogs document WHAT; blogs explain WHY. Same information,
70+
different engagement. Changelogs are for machines (audits, dependency trackers).
71+
Blogs are for humans (narrative, context, lessons).
3272

33-
- **[2026-01-28-040251]** AI session JSONL formats are not standardized across tools
73+
**Application**: When synthesizing session history, output both: changelog for
74+
completeness, blog for readability.
3475

3576
---
3677

37-
## [2026-01-27] Always Complete Decision Record Sections
78+
## [2026-01-28-051426] IDE is already the UI
79+
80+
**Context**: Considering whether to build custom UI for .context/ files
81+
82+
**Lesson**: Discovery, search, and editing of .context/ markdown files works
83+
better in VS Code/IDE than any custom UI we'd build. Full-text search,
84+
git integration, extensions - all free.
85+
86+
**Application**: Don't reinvent the editor. Let users use their preferred IDE.
87+
88+
---
89+
90+
## [2026-01-28-040915] Subtasks complete does not mean parent task complete
91+
92+
**Context**: AI marked parent task done after finishing subtasks but missing
93+
actual deliverable
94+
95+
**Lesson**: Subtask completion is implementation progress, not delivery.
96+
The parent task defines what the user gets.
97+
98+
**Application**: Parent tasks should have explicit deliverables; don't close
99+
until deliverable is verified.
100+
101+
---
102+
103+
## [2026-01-28-040251] AI session JSONL formats are not standardized
104+
105+
**Context**: Building recall feature to parse session history from multiple
106+
AI tools
107+
108+
**Lesson**: Claude Code, Cursor, Aider each have different JSONL formats
109+
or may not export sessions at all.
110+
111+
**Application**: Use tool-agnostic Session type with tool-specific parsers.
112+
113+
---
114+
115+
## [2026-01-27-180000] Always Complete Decision Record Sections
38116

39117
**Context**: Decisions added via `ctx add decision` were left with placeholder
40118
text like "[Add context here]".
@@ -50,7 +128,7 @@ flags when available.
50128

51129
---
52130

53-
## [2026-01-27] Slash Commands Require Matching Permissions
131+
## [2026-01-27-160000] Slash Commands Require Matching Permissions
54132

55133
**Context**: Claude Code slash commands using `!` bash syntax require matching
56134
permissions in settings.local.json.
@@ -61,7 +139,7 @@ config - never remove existing permissions.
61139

62140
---
63141

64-
## [2026-01-26] Go json.Marshal Escapes Shell Characters
142+
## [2026-01-26-180000] Go json.Marshal Escapes Shell Characters
65143

66144
**Context**: Generated settings.local.json had `2\u003e/dev/null` instead
67145
of `2>/dev/null`.
@@ -73,7 +151,7 @@ that contain shell commands.
73151

74152
---
75153

76-
## [2026-01-26] Claude Code Hook Key Names
154+
## [2026-01-26-160000] Claude Code Hook Key Names
77155

78156
**Context**: Hooks weren't working, getting "Invalid key in record" errors.
79157

@@ -83,7 +161,7 @@ causes validation errors.
83161

84162
---
85163

86-
## [2026-01-25] defer os.Chdir Fails errcheck Linter
164+
## [2026-01-25-200000] defer os.Chdir Fails errcheck Linter
87165

88166
**Context**: `defer os.Chdir(originalDir)` fails golangci-lint errcheck.
89167

@@ -92,7 +170,7 @@ error return value.
92170

93171
---
94172

95-
## [2026-01-25] golangci-lint Go Version Mismatch in CI
173+
## [2026-01-25-190000] golangci-lint Go Version Mismatch in CI
96174

97175
**Context**: CI was failing with Go version mismatches between golangci-lint
98176
and the project.
@@ -103,7 +181,7 @@ source using the project's Go version.
103181

104182
---
105183

106-
## [2026-01-25] CI Tests Need CTX_SKIP_PATH_CHECK
184+
## [2026-01-25-180000] CI Tests Need CTX_SKIP_PATH_CHECK
107185

108186
**Context**: CI tests were failing because ctx binary isn't installed on CI runners.
109187

@@ -112,7 +190,7 @@ env var, because init checks if ctx is in PATH.
112190

113191
---
114192

115-
## [2026-01-25] AGENTS.md Is Not Auto-Loaded
193+
## [2026-01-25-170000] AGENTS.md Is Not Auto-Loaded
116194

117195
**Context**: Had both AGENTS.md and CLAUDE.md in project root, causing confusion.
118196

@@ -121,7 +199,7 @@ using ctx should rely on the CLAUDE.md → AGENT_PLAYBOOK.md chain, not AGENTS.m
121199

122200
---
123201

124-
## [2026-01-25] Hook Regex Can Overfit
202+
## [2026-01-25-160000] Hook Regex Can Overfit
125203

126204
**Context**: `.claude/hooks/block-non-path-ctx.sh` was blocking legitimate sed
127205
commands because the regex `ctx[^ ]*` matched paths containing "ctx" as a
@@ -137,7 +215,7 @@ directory component (e.g., `/home/user/ctx/internal/...`).
137215

138216
---
139217

140-
## [2026-01-25] Autonomous Mode Creates Technical Debt
218+
## [2026-01-25-140000] Autonomous Mode Creates Technical Debt
141219

142220
**Context**: Compared commits from autonomous "YOLO mode" (auto-accept,
143221
agent-driven) vs human-guided refactoring sessions.
@@ -160,7 +238,7 @@ agent-driven) vs human-guided refactoring sessions.
160238

161239
---
162240

163-
## [2026-01-23] ctx agent vs Manual File Reading Trade-offs
241+
## [2026-01-23-180000] ctx agent vs Manual File Reading Trade-offs
164242

165243
**Context**: User asked "Do you remember?" and agent used parallel file reads
166244
instead of `ctx agent`. Compared outputs to understand the delta.
@@ -183,7 +261,7 @@ Manual file reading is better for exploratory/memory questions:
183261

184262
---
185263

186-
## [2026-01-23] Claude Code Skills Format
264+
## [2026-01-23-160000] Claude Code Skills Format
187265

188266
**Context**: Needed to understand how to create custom slash commands.
189267

@@ -194,7 +272,7 @@ passes command args.
194272

195273
---
196274

197-
## [2026-01-23] Infer Intent on "Do You Remember?" Questions
275+
## [2026-01-23-140000] Infer Intent on "Do You Remember?" Questions
198276

199277
**Context**: User asked "Do you remember?" at session start. Agent asked for
200278
clarification instead of proactively checking context files.
@@ -214,7 +292,7 @@ obvious intent.
214292

215293
---
216294

217-
## [2026-01-23] Always Use ctx from PATH
295+
## [2026-01-23-120000] Always Use ctx from PATH
218296

219297
**Context**: Agent used `./dist/ctx-linux-arm64` and `go run ./cmd/ctx`
220298
instead of just `ctx`, even though the binary was installed to PATH.
@@ -232,7 +310,7 @@ setup (`sudo make install` or `sudo cp ./ctx /usr/local/bin/`).
232310

233311
---
234312

235-
## [2026-01-21] Exit Criteria Must Include Verification
313+
## [2026-01-21-180000] Exit Criteria Must Include Verification
236314

237315
**Context**: Dogfooding experiment had another Claude rebuild `ctx` from specs.
238316
All tasks were marked complete, Ralph Loop exited successfully. But the built
@@ -255,7 +333,7 @@ Exit criteria must include:
255333

256334
---
257335

258-
## [2026-01-21] Orchestrator vs Agent Tasks Must Be Separate
336+
## [2026-01-21-160000] Orchestrator vs Agent Tasks Must Be Separate
259337

260338
**Context**: Ralph Loop checked `IMPLEMENTATION_PLAN.md`, found all tasks
261339
done, exited — ignoring `.context/TASKS.md`.
@@ -272,7 +350,7 @@ The orchestrator shouldn't maintain a parallel ledger. It just says
272350

273351
---
274352

275-
## [2026-01-21] One Templates Directory, Not Two
353+
## [2026-01-21-140000] One Templates Directory, Not Two
276354

277355
**Context**: Confusion arose about `templates/` (root) vs
278356
`internal/templates/` (embedded).
@@ -291,7 +369,7 @@ internal/templates/ ──[ctx init]──> .context/
291369

292370
---
293371

294-
## [2026-01-21] Hooks Should Use PATH, Not Hardcoded Paths
372+
## [2026-01-21-120000] Hooks Should Use PATH, Not Hardcoded Paths
295373

296374
**Context**: Original hooks used hardcoded absolute paths like
297375
`/home/user/project/dist/ctx-linux-arm64`. This caused issues when dogfooding
@@ -312,7 +390,7 @@ or sharing configs.
312390

313391
---
314392

315-
## [2026-01-20] ctx and Ralph Loop Are Separate Systems
393+
## [2026-01-20-200000] ctx and Ralph Loop Are Separate Systems
316394

317395
**Context**: User asked "How do I use the ctx binary to recreate this project?"
318396

@@ -329,7 +407,7 @@ or sharing configs.
329407

330408
---
331409

332-
## [2026-01-20] .context/ Is NOT a Claude Code Primitive
410+
## [2026-01-20-180000] .context/ Is NOT a Claude Code Primitive
333411

334412
**Context**: User asked if Claude Code natively understands `.context/`.
335413

@@ -345,7 +423,7 @@ The `.context/` directory is a ctx convention. Claude won't know about it unless
345423

346424
---
347425

348-
## [2026-01-20] SessionEnd Hook Catches Ctrl+C
426+
## [2026-01-20-160000] SessionEnd Hook Catches Ctrl+C
349427

350428
**Context**: Needed to auto-save context even when user force-quits with Ctrl+C.
351429

@@ -359,7 +437,7 @@ The `.context/` directory is a ctx convention. Claude won't know about it unless
359437

360438
---
361439

362-
## [2026-01-20] Session Filename Must Include Time
440+
## [2026-01-20-140000] Session Filename Must Include Time
363441

364442
**Context**: Using just date (`2026-01-20-topic.md`) would overwrite multiple sessions per day.
365443

@@ -369,7 +447,7 @@ The `.context/` directory is a ctx convention. Claude won't know about it unless
369447

370448
---
371449

372-
## [2026-01-20] Two Tiers of Persistence
450+
## [2026-01-20-120000] Two Tiers of Persistence
373451

374452
**Context**: User wanted to ensure nothing is lost when session ends.
375453

@@ -384,7 +462,7 @@ The `.context/` directory is a ctx convention. Claude won't know about it unless
384462

385463
---
386464

387-
## [2026-01-20] Auto-Load Works, Auto-Save Was Missing
465+
## [2026-01-20-100000] Auto-Load Works, Auto-Save Was Missing
388466

389467
**Context**: Explored how to persist context across Claude Code sessions.
390468

@@ -396,7 +474,7 @@ The `.context/` directory is a ctx convention. Claude won't know about it unless
396474

397475
---
398476

399-
## [2026-01-20] Always Backup Before Modifying User Files
477+
## [2026-01-20-080000] Always Backup Before Modifying User Files
400478

401479
**Context**: `ctx init` needs to create/modify CLAUDE.md, but user may have existing customizations.
402480

@@ -410,7 +488,7 @@ The `.context/` directory is a ctx convention. Claude won't know about it unless
410488

411489
---
412490

413-
## [undated] CGO Must Be Disabled for ARM64 Linux
491+
## [2026-01-19-120000] CGO Must Be Disabled for ARM64 Linux
414492

415493
**Context**: `go test` failed with `gcc: error: unrecognized command-line option '-m64'`
416494

‎.context/TASKS.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,12 @@
1717

1818
## Phase 1.a: Cleanup and Release
1919

20-
- [x] T1.2.0 feat: ctx add learning requires --context, --lesson, --application
20+
- [ ] T1.2.0.1 Add quick reference index table to DECISIONS.md template
21+
and ctx add decision #priority:medium #added:2026-01-29-035140
22+
Consider if other files can benefit from this kind of indexing structure too.
23+
- [ ] T1.2.0.2 Add ctx decisions reindex command to regenerate index from
24+
existing entries #priority:low #added:2026-01-29-035140
25+
- [x] T1.2.0.3 feat: ctx add learning requires --context, --lesson, --application
2126
flags (matching decision's ADR pattern) #priority:high #added:2026-01-28-053941
2227
- [x] T1.2.1 fix: update context-update XML tag format to include required
2328
fields (context, lesson, application for learnings; context, rationale,
@@ -153,3 +158,4 @@ Could run as:
153158
- ctx enrich --dry-run (show what would be expanded)
154159

155160
#priority:low #phase:future #added:2026-01-28-073058
161+

‎internal/bootstrap/bootstrap.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ import (
2626
"github.com/ActiveMemory/ctx/internal/cli/drift"
2727
"github.com/ActiveMemory/ctx/internal/cli/hook"
2828
"github.com/ActiveMemory/ctx/internal/cli/initialize"
29+
"github.com/ActiveMemory/ctx/internal/cli/learnings"
2930
"github.com/ActiveMemory/ctx/internal/cli/load"
3031
"github.com/ActiveMemory/ctx/internal/cli/loop"
3132
"github.com/ActiveMemory/ctx/internal/cli/recall"
@@ -84,6 +85,7 @@ func Initialize(cmd *cobra.Command) *cobra.Command {
8485
cmd.AddCommand(decisions.Cmd())
8586
cmd.AddCommand(watch.Cmd())
8687
cmd.AddCommand(hook.Cmd())
88+
cmd.AddCommand(learnings.Cmd())
8789
cmd.AddCommand(session.Cmd())
8890
cmd.AddCommand(task.Cmd())
8991
cmd.AddCommand(loop.Cmd())

0 commit comments

Comments
 (0)