manage-learn

<purpose> Unified atomic knowledge capture for the workflow learning library. Captures two types of knowledge: - **Insights**: Timeless "eureka moment" entries (patterns, gotchas, techniques) — the default mode - **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-knowhow-capture tip`)

Both types are stored in .workflow/specs/learnings.md as <spec-entry> blocks with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by source: "tip" and implicitly tagged tip. Same store as retrospective output, so search and list see the entire knowledge corpus. </purpose>

<required_reading> @~/.maestro/workflows/learn.md </required_reading>

<context> Arguments: $ARGUMENTS

Modes (auto-detected from first token):

• "<insight text>" (or any non-keyword text) → insight capture mode
• tip <text> → tip capture mode (quick contextual note, auto-tagged tip)
• list → list recent entries (default 20)
• search <query> → maestro spec load --category learning or text search across .workflow/specs/learnings.md
• show <INS-id> → full detail with phase context
• empty → AskUserQuestion to prompt for text

Flags, storage paths, and shared store rationale defined in workflow learn.md. </context>

<execution> Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order. </execution>

<error_codes>

Code	Severity	Description	Stage
E001	error	.workflow/ not initialized — run /maestro-init first	parse_input
E002	error	Unknown --category value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip)	parse_input
E003	error	show mode requires an INS-id argument	show
E004	error	Insight id not found in .workflow/specs/learnings.md	show
W001	warning	Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null	capture
</error_codes>

<success_criteria>

• Mode correctly routed (capture / list / search / show)
• Capture: <spec-entry> block appended to .workflow/specs/learnings.md with all required fields
• Capture: phase auto-link resolves correctly via artifact registry when state.json has current_phase
• Capture: category inference produces a sensible default when --category absent
• List: filters apply, output sorted newest-first, default limit 20
• Search: results ranked by title (3) > tags (2) > summary (1) match
• Show: full insight displayed with phase context and routed-artifact link if any
• No file modifications outside .workflow/specs/learnings.md and .workflow/knowhow/
• Confirmation banner displayed with INS-id and next-step hints
• Next step: /manage-learn list to browse, or /manage-learn search <query> to find related insights </success_criteria>