manage-learn

name: manage-learn description: Capture atomic learning insights into .workflow/learning/lessons.jsonl. Lightweight CRUD over the shared learning store — supports capture, list, search, and show modes. No LLM or CLI calls; all operations are pure file reads and writes. argument-hint: "["<insight text>"|list|search <query>|show <INS-id>] [--category pattern|antipattern|decision|tool|gotcha|technique] [--tag t1,t2] [--phase N] [--confidence high|medium|low]" allowed-tools: Read, Write, Edit, Bash, Glob, Grep

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

$manage-learn "Always read state.json before planning to detect current phase"
$manage-learn "list --limit 10 --category antipattern"
$manage-learn "search context propagation"
$manage-learn "show INS-a3f7b2c1"
$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)

Verify .workflow/ exists (E001 if not). If .workflow/learning/lessons.jsonl missing: create directory, empty lessons.jsonl, and initialize learning-index.json with {"version":1,"entries":[]}.

Step 3: Execute Mode

Capture Mode

1. Infer category from keywords (no LLM):

1. Auto-link phase from state.json artifact registry. --phase 0 forces null.
2. Generate INS-id: INS-{8 hex} from hash(insightText + timestamp).
3. Build row with fields: id, title (first 80 chars), summary, source="manual", lens=null, category, tags (includes "manual"), phase, phase_slug, confidence, routed_to=null, created_at.
4. Append JSON line to lessons.jsonl (append-only, never rewrite).
5. Update learning-index.json: push entry with id, title, category, tags, phase, created_at.

List Mode

Read learning-index.json, apply filters (--tag, --category, --phase, --lens), sort newest-first, display up to --limit rows (default 20) as table.

Search Mode

Grep lessons.jsonl for query. Rank by field weight: title (3) > tags (2) > summary (1). Display top matches.

Show Mode

Validate INS-[0-9a-f]{8} format. Find matching row, display full record. Show linked artifact if routed_to is set.

Step 4: Display Confirmation

Capture mode: display ID, category, phase, confidence, tags, and next-step commands ($manage-learn "list", $manage-learn "search ..."). </execution>

<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>