spectre-learn

name	spectre-learn
description	Use when the user invokes /learn or asks to remember, save, or capture a pattern, decision, gotcha, procedure, or feature dossier from this session for later re-use ("please remember", "what did we learn?"). Captures durable project knowledge as a canonical user-level record. Do NOT trigger for simple personal preferences (those go to CLAUDE.md) or for searching or loading existing knowledge (use the knowledge CLI).
user-invocable	true
disable-model-invocation	true

Learning Agent

Capture durable project knowledge as a canonical user-level record. When invoked (/learn or spectre-learn), this is the exclusive knowledge handler: do not write to MEMORY.md or any auto-memory system. Goal: someone with zero context becomes productive on the topic without follow-up questions.

Inputs

• Topic/content from $ARGUMENTS; if absent, infer from the last ~10–20 messages.
• Project root = ${CLAUDE_PROJECT_DIR:-$PWD}. Do not traverse to a Git root or main worktree; identify the project from where the user is working. Never use git rev-parse.
• Canonical knowledge from the host-neutral node "${PLUGIN_ROOT}/hooks/scripts/knowledge-cli.mjs" search and exact-ID node "${PLUGIN_ROOT}/hooks/scripts/knowledge-cli.mjs" load contract. The commands resolve Git and non-Git projects to the readable user-level store under ~/.spectre/projects/.

Working Set

• Read-only search results and any selected canonical recordPath.
• One temporary proposal directory created with mktemp -d; it must be outside the project.
• The approved core SKILL.md plus optional focused references/ staged under that proposal directory.

Method / guardrails

1. Context or investigate. If the topic was discussed in detail or you already understand it this session, proceed. Otherwise enter Investigation Mode — do NOT fabricate. Dispatch @spectre_finder to map relevant files, then 2–3 read-only @spectre_analyst passes answering the category's required-section questions (cite file:line). Synthesize: cross-reference shared files, resolve conflicts by reading the disputed code, flag gaps.

2. Migrate, then search before deciding. Run:

   project_root="${CLAUDE_PROJECT_DIR:-$PWD}"
   node "${PLUGIN_ROOT}/hooks/scripts/knowledge-cli.mjs" migrate --project-dir "$project_root" --json
   node "${PLUGIN_ROOT}/hooks/scripts/knowledge-cli.mjs" search "$ARGUMENTS" --project-dir "$project_root" --json
   

   Treat migration issues as preserved debt, not permission to rewrite or delete legacy input. For each plausible search result, load the verified core by exact ID before choosing an action:

   node "${PLUGIN_ROOT}/hooks/scripts/knowledge-cli.mjs" load "<exact-id>" --project-dir "$project_root" --json
   

   Search results are metadata, not loaded knowledge. Use the load result's recordPath, recordDirectory, and lazy resource manifest when inspecting an existing candidate.

3. Capture criteria — proceed only if ≥2 of 4 hold: Frequency (recurs) · Pain (cost real debug time) · Surprise (non-obvious) · Durability (true in 6 months). Skip one-offs, generic knowledge, temporary workarounds, and simple preferences (→ CLAUDE.md).

4. Categorize — use ONLY these (never invent): feature · gotchas · patterns · decisions · procedures · integration · performance · testing · ux · strategy.

5. Required sections by category (minimums — add depth per Content Principles below):

Outputs + DONE

• A validated canonical SKILL.md plus any focused references/, committed atomically through node "${PLUGIN_ROOT}/hooks/scripts/knowledge-cli.mjs" register.
• DONE when: the user approved at the proposal gate · registration returned ok: true · canonical search finds the expected active record · exact-ID load returns the approved full core and resource paths · no project knowledge files were created.

Handoff

Report the canonical recordPath, action, category, confidence, version, and any resource paths. If a previously applied record proved incomplete or wrong, route the correction through the same search, proposal, temporary-stage, registration, and verification flow.

Escalate-If

• Category is ambiguous → ask the user which of the ten categories.
• Investigation can't confirm a load-bearing claim → flag it inline and set confidence low; do not assert unverified behavior as fact.
• Migration reports divergent, malformed, conflicting, or unproven oversized input relevant to this topic → preserve it and surface the exact issue before proposing new authority. Proven legacy Spectre-generated learnings migrate intact even when oversized; do not rewrite their canonical bytes merely to satisfy superseded delivery constraints.