manage-learn

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/specs/learnings.md — append-only store (shared with quality-retrospective)
• Index auto-maintained by WikiIndexer (no manual index file needed)

Output boundary: ALL file writes MUST target .workflow/specs/learnings.md only. NEVER modify source code or files outside this path. Bootstrap (creating .workflow/specs/ directory and learnings.md) is the only exception.

Step 1: Parse Mode and Validate Arguments

Parse the first non-flag token from $ARGUMENTS:

First token	Mode
list	list
search followed by query	search
show followed by INS-id	show
Empty	Prompt with functions.request_user_input
Any other text (quoted or not)	capture

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/specs/learnings.md missing: create .workflow/specs/ directory and empty learnings.md with header.

Step 3: Execute Mode

Capture Mode

1. Infer category from keywords (no LLM):

Keywords	Category
always, should, prefer, best practice	pattern
never, avoid, don't, pitfall, breaks	antipattern
decided, chose, tradeoff, because	decision
tool, library, framework, package	tool
gotcha, surprising, unexpected	gotcha
technique, approach, method	technique

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 entry to .workflow/specs/learnings.md (append-only, never rewrite).
5. WikiIndexer auto-indexes the new entry (no manual index update needed).

List Mode

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

Search Mode

Grep learnings.md 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 ...").

<error_codes>

Code	Severity	Description	Stage
E001	error	.workflow/ not initialized — run $maestro-init first	parse_input
E002	error	Unknown --category value	parse_input
E003	error	show mode requires INS-id argument	show
E004	error	INS-id not found in learnings.md	show
W001	warning	Auto-phase detection: no matching artifact directory found; phase set to null	capture
W002	warning	Entry count differs from learnings.md; offer to rebuild index	list/search
</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: entry appended to .workflow/specs/learnings.md (append-only)
• 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>