Parse Mode  →  Bootstrap Store  →  Execute Mode  →  Confirm
(capture /       (on first use)     (Bash/Read/      (INS-id
  list /          Bash+Write)        Write/Grep)      + hints)
  search /
  show)

bash
1$manage-learn "Always read state.json before planning to detect current phase"
2$manage-learn "list --limit 10 --category antipattern"
3$manage-learn "search context propagation"
4$manage-learn "show INS-a3f7b2c1"
5$manage-learn "\"Zod v4 breaks z.object().strict() API\" --category gotcha --tag zod,typescript"

Flags (capture mode):

• --category <name> — pattern|antipattern|decision|tool|gotcha|technique. Default: inferred from text keywords.
• --tag t1,t2 — Comma-separated tags. Always adds manual implicitly.
• --phase <N> — Override auto-detected current phase. --phase 0 forces no phase link.
• --confidence high|medium|low — Default: medium.

Flags (list/search mode):

• --tag t1,t2 — Filter by tag
• --category <name> — Filter by category
• --phase <N> — Filter by phase
• --lens <name> — Filter by retrospective lens (technical|process|quality|decision)
• --limit <N> — Row limit (default 20)

Storage:

• .workflow/learning/lessons.jsonl — append-only JSONL (shared with quality-retrospective)
• .workflow/learning/learning-index.json — searchable index </context>

Step 1: Parse Mode and Validate Arguments

Parse the first non-flag token from $ARGUMENTS:

Validate --category if provided (allowed: pattern, antipattern, decision, tool, gotcha, technique). E002 if unknown.

Step 2: Bootstrap Learning Store (on first use)

Check if .workflow/learning/lessons.jsonl exists. If not:

javascript
1// Create directory and empty files — use Bash + Write (apply_patch cannot create empty files reliably)
2Bash('mkdir -p .workflow/learning && touch .workflow/learning/lessons.jsonl')
3Write('.workflow/learning/learning-index.json', '{"version":1,"entries":[]}\n')

Verify .workflow/ exists (E001 if not).

Step 3: Execute Mode

Capture Mode

1. Infer category from insight text (keyword heuristics, no LLM):

2. Auto-link phase: Read .workflow/state.json for current_phase. Resolve matching directory slug from .workflow/phases/. --phase 0 forces null.

3. Generate stable INS-id: INS-{8 lowercase hex} from hash(insightText + timestamp).

4. Build lessons.jsonl row:

json
1{
2  "id": "INS-a3f7b2c1",
3  "title": "<first 80 chars of insight>",
4  "summary": "<full insight text>",
5  "source": "manual",
6  "lens": null,
7  "category": "<inferred or explicit>",
8  "tags": ["manual", "<user tags...>"],
9  "phase": "<N or null>",
10  "phase_slug": "<slug or null>",
11  "confidence": "<high|medium|low>",
12  "routed_to": null,
13  "routed_id": null,
14  "created_at": "<ISO>"
15}

5. Append to lessons.jsonl:

javascript
1// Append single JSON line — Bash echo avoids rewriting the whole file
2Bash(`echo '${JSON.stringify(insightRow)}' >> .workflow/learning/lessons.jsonl`)

6. Update learning-index.json: Read, push entry, write back:

javascript
1const index = JSON.parse(Read('.workflow/learning/learning-index.json'))
2index.entries.push({ id: insightRow.id, title: insightRow.title, category: insightRow.category, tags: insightRow.tags, phase: insightRow.phase, created_at: insightRow.created_at })
3Write('.workflow/learning/learning-index.json', JSON.stringify(index, null, 2) + '\n')

List Mode

Read learning-index.json entries array. Apply filters (--tag, --category, --phase, --lens). Sort newest-first. Display up to --limit rows (default 20):

ID              Category     Phase  Tags              Title
INS-a3f7b2c1   gotcha       3      manual,zod        Zod v4 breaks z.object().strict() API
INS-b1c2d3e4   pattern      2      manual            Always read state.json before planning

Search Mode

Grep across lessons.jsonl for the query string. Rank by field match weight: title (3) > tags (2) > summary (1). Display top matches with ID, category, phase, title.

Show Mode

Validate INS-id format INS-[0-9a-f]{8}. Find row in lessons.jsonl where id matches. Display full record with all fields. If routed_to is set, display the linked artifact path.

Step 4: Display Confirmation

Capture mode:

=== INSIGHT CAPTURED ===
ID:         INS-a3f7b2c1
Category:   gotcha
Phase:      3 (phase-03-api-layer)
Confidence: medium
Tags:       manual, zod, typescript

Next: $manage-learn "list"  or  $manage-learn "search zod"

<error_codes>

<success_criteria>

• Mode parsed correctly (capture, list, search, show)
• Learning store bootstrapped on first use
• Capture: category inferred from keywords, phase auto-linked, INS-id generated
• Capture: row appended to lessons.jsonl (append-only), index updated
• List: filters applied, newest-first, respects --limit
• Search: grep with weighted ranking across title/tags/summary
• Show: full record displayed for valid INS-id
• No LLM or CLI calls — pure file I/O only </success_criteria>