Manage Learn

Storage:

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

Overview

Pure file-operation CRUD skill for the workflow learning library. No agent spawning, no CLI calls, no LLM inference — just parse-infer-append-confirm. Complements quality-retrospective: where retrospective extracts insights in bulk from completed phases, manage-learn captures one timeless insight at a time during active work. Both write to the same lessons.jsonl store, disambiguated by source and lens fields.

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

Implementation

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:

// Create directory and empty files — use Bash + Write (apply_patch cannot create empty files reliably)
Bash('mkdir -p .workflow/learning && touch .workflow/learning/lessons.jsonl')
Write('.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:

{
  "id": "INS-a3f7b2c1",
  "title": "<first 80 chars of insight>",
  "summary": "<full insight text>",
  "source": "manual",
  "lens": null,
  "category": "<inferred or explicit>",
  "tags": ["manual", "<user tags...>"],
  "phase": <N or null>,
  "phase_slug": "<slug or null>",
  "confidence": "<high|medium|low>",
  "routed_to": null,
  "routed_id": null,
  "created_at": "<ISO>"
}

5. Append to lessons.jsonl:

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

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

const index = JSON.parse(Read('.workflow/learning/learning-index.json'))
index.entries.push({ id: insightRow.id, title: insightRow.title, category: insightRow.category, tags: insightRow.tags, phase: insightRow.phase, created_at: insightRow.created_at })
Write('.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 Handling

Core Rules

1. No LLM or CLI calls: This skill is pure file I/O — parse, infer, append, confirm. No exec_command, no spawn_agent.
2. Bootstrap on demand: Create .workflow/learning/ structure on first use; do not require it to exist.
3. Append-only lessons.jsonl: Never rewrite or delete existing rows.
4. Stable INS-ids: INS-{8hex} from hash(insightText + timestamp) — same text at different times gets different ids.
5. Source field: Always "manual" for captures from this skill; "retrospective" is reserved for quality-retrospective.
6. Phase auto-link: Read state.json automatically; --phase 0 is the only way to force null.
7. Keyword inference is approximate: When in doubt, default to pattern category rather than prompting user.