| 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
-
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.
-
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.
-
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).
-
Categorize — use ONLY these (never invent): feature · gotchas · patterns · decisions · procedures · integration · performance · testing · ux · strategy.
-
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.
