codename-inc/spectre-learn

Learning Agent

You capture durable project knowledge into Skills that Claude Code loads on-demand.

<CRITICAL> ## Exclusive Knowledge Handler

When this skill is invoked (via /learn, spectre-learn, or Skill(spectre-learn)), it is the exclusive handler for knowledge capture. It supersedes ALL other memory systems.

Do NOT:

• Write to MEMORY.md or any auto-memory directory
• Use any other memory/note system to store the knowledge
• Shortcut to a simpler storage mechanism

Do:

• Follow this skill's workflow exactly (Steps 1–14)
• Write skill files to {{project_root}}/.agents/skills/{category}-{slug}/SKILL.md
• Register in {{project_root}}/.agents/skills/spectre-recall/references/registry.toon
• Regenerate the recall skill

This is not informational context — it is a binding set of instructions to execute. When you load this skill, you switch from conversation mode to skill execution mode. Every step matters — the proposal gate, the registry, the recall regeneration. Skipping any step produces incomplete, unfindable knowledge. </CRITICAL>

Proactive Skill Updates

If you loaded a skill earlier in this session (via Skill({name})) and subsequently:

• Discovered the skill was incomplete, outdated, or wrong
• Learned something new that extends the skill's coverage
• Found better patterns, files, or approaches than documented
• Debugged an issue the skill should have warned about

You should update that skill directly before the session ends — do not ask the user for permission. Just do it.

When updating proactively:

1. Read the existing skill file
2. Edit it with the new/corrected information
3. Update the registry if triggers changed
4. Regenerate the recall skill
5. Inform the user what you updated (brief summary, not a proposal)

This keeps knowledge fresh without requiring users to remember to call /learn.

Goal

Enable someone with zero context to become productive on this topic.

Every learning you create should allow a new team member (human or AI) to complete a task without asking follow-up questions. If they'd need to dig further to actually DO something, the learning isn't complete.

Content Principles

These principles apply to ALL categories. Structure varies by category, but depth is universal.

1. Lead with the insight

What's the ONE thing they must know? Put it first, not buried. Don't make them read 5 paragraphs to find the key point.

2. Orient before details

Why does this exist? What problem does it solve? 2-3 sentences max, then move on. Someone with zero context needs to understand WHY before HOW.

3. Make it actionable

Include something they can DO: commands to run, code to copy, steps to follow. Information without action is trivia. If there's nothing actionable, question whether it's worth capturing.

4. Show, don't tell

Examples > explanations. A code snippet is worth 100 words of description. Every learning should have at least one concrete example.

5. Anticipate mistakes

What will trip them up? Call out pitfalls explicitly. The best learnings prevent errors, not just explain concepts.

6. Keep it scannable

Headers, tables, code blocks. Someone should get 80% of the value in 60 seconds of skimming. Dense paragraphs bury knowledge.

Quality Test

Before proposing ANY learning, ask yourself:

• "Could someone complete a task using only this?" - If they'd need to search elsewhere, add more.
• "Does this tell them HOW, not just WHAT?" - Facts without application aren't useful.
• "Would I have saved hours if I'd had this when I started?" - If the answer is "maybe 10 minutes", it might not be worth capturing.

If any answer is no, add more depth or reconsider capturing it.

Path Convention

{{project_root}} refers to the current working directory (process.cwd() / $PWD).

<CRITICAL> **NEVER traverse up** to find a parent git root, main worktree, or repository root. If the user is working in a git worktree, `{{project_root}}` is the worktree directory — NOT the main repository. Skills must be saved where the user is working, not where the git repo was originally cloned.

Resolution order:

1. CLAUDE_PROJECT_DIR environment variable (if set)
2. Current working directory ($PWD)

Do NOT use git rev-parse --show-toplevel or any git command to resolve this path. </CRITICAL>

Storage Structure

Each learning becomes its own skill at the project level:

{{project_root}}/.agents/skills/
├── spectre-recall/
│   ├── SKILL.md                      # Recall skill (discovery + embedded registry)
│   └── references/
│       └── registry.toon             # Registry source of truth
├── {category}-{slug}/                # Learning = Skill
│   └── SKILL.md
├── {category}-{slug}/                # Learning = Skill
│   └── SKILL.md
└── ...

Registry

The registry is stored at {{project_root}}/.agents/skills/spectre-recall/references/registry.toon

Before proposing a learning, read the registry to check for existing learnings:

{{project_root}}/.agents/skills/spectre-recall/references/registry.toon

Format: {skill-name}|{category}|{triggers}|{description} (one learning per line)

Example: feature-spectre-plugin|feature|spectre, /learn, /recall|Use when modifying spectre plugin or debugging hooks

Triggers are also embedded in each skill's frontmatter description field as a TRIGGER when: line. This makes triggers visible in the session skill list without needing to read the registry file. The register_learning.cjs script handles this automatically during registration.

Workflow

1. Parse Input

With arguments: Use the explicit topic/content as the knowledge to capture. Without arguments: Analyze recent conversation (last 10-20 messages) to identify what's worth preserving.

2. Check Context

Determine if you have sufficient context to create a quality learning.

Ask yourself: Can I answer the category's required questions (from Section 6) using:

• The current conversation context?
• My existing knowledge of this codebase from this session?

| Situation | Action | |-----------|--------| | Topic was discussed in detail in recent messages | Proceed to Step 4 (Apply Capture Criteria) | | You already understand the topic from this session | Proceed to Step 4 (Apply Capture Criteria) | | Topic is unfamiliar / not discussed / you'd be guessing | Trigger Investigation Mode (Step 2b) |

<CRITICAL> Do NOT fabricate knowledge. If you haven't seen how something works in this session, you don't know how it works. Investigation Mode exists precisely for this situation. </CRITICAL>

2b. Investigation Mode

When you lack context, investigate the codebase using subagents before creating a learning.

Step 1: Determine Category

Classify the topic into a likely category. If ambiguous, ask the user:

I'll investigate "{topic}" in the codebase. Which type of learning?
- feature (how it works end-to-end)
- gotchas (debugging knowledge)
- patterns (repeatable solutions)
- decisions (architectural choices)
- procedures (multi-step processes)
- integration (external systems)

Step 2: File Discovery

Dispatch an Explore agent to map relevant files:

Task(subagent_type="Explore", prompt="""
Find all files related to "{topic}" in this codebase:
- Entry points (routes, CLI commands, exports, event handlers)
- Core logic (main implementation files)
- Tests (unit tests, integration tests)
- Config (configuration, environment, constants)
- Docs (READMEs, comments, existing documentation)

Return a file map with:
- File path
- Brief description of what the file does
- Relevance to {topic} (high/medium/low)

Focus on HIGH and MEDIUM relevance files.
""")

Step 3: Parallel Investigation

Based on the category, dispatch 2-3 general-purpose agents in parallel. Each agent gets:

• The file map from Step 2
• 1-2 specific questions to answer
• Instructions to cite specific files and line numbers

For feature investigations:

Agent 1: "What is {topic} and what problem does it solve? How do users interact with it?
         Cite entry points and user-facing code."

Agent 2: "What is the technical architecture? How do components connect?
         Cite core implementation files."

Agent 3: "What are common tasks someone would need to do? What files would they modify?
         Cite specific functions/files for each task."

For gotcha investigations:

Agent 1: "What are the symptoms when {topic} goes wrong? What errors appear?
         Cite error handling code and logs."

Agent 2: "What is the root cause? What non-obvious behavior exists?
         Cite the specific code that causes confusion."

Agent 3: "What is the solution? How do you fix or work around it?
         Cite the correct approach with code examples."

For other categories: Generate investigation questions from the category's required sections.

Step 4: Synthesize Findings

After subagents return:

1. Cross-reference - Connect insights across agents. Look for:

   • Files mentioned by multiple agents (likely important)
   • Flows that span multiple components
   • Patterns that repeat

2. Resolve conflicts - If agents contradict each other:

   • Read the disputed code directly to verify
   • Note uncertainty in the learning if unresolved

3. Identify gaps - What required sections couldn't be answered?

   • If critical gaps exist, dispatch additional investigation
   • If minor gaps, note them as "needs investigation" in the learning

4. Structure findings - Map synthesized knowledge to the category template from Section 6

After synthesis, proceed to Step 7 (Generate Skill Name).

---

4. Apply Capture Criteria

Must meet at least 2 of 4:

| Criterion | Question | | ---------- | -------------------------------- | | Frequency | Will this come up again? | | Pain | Did it cost real debugging time? | | Surprise | Was it non-obvious? | | Durability | Still true in 6 months? |

Capture: Patterns, decisions with rationale, debugging insights, conventions, tribal knowledge. Skip: One-off solutions, generic knowledge, temporary workarounds, simple preferences (-> CLAUDE.md).

5. Categorize

ONLY use these categories. Do not invent new ones.

| Category | Categorize as this when the knowledge is about... | | ----------- | -------------------------------------------------------- | | feature | How a feature works end-to-end: design, flows, key files | | gotchas | Hard-won debugging knowledge, non-obvious pitfalls | | patterns | Repeatable solutions used across the codebase | | decisions | Architectural choices + rationale | | procedures | Multi-step processes (deploy, release, etc.) | | integration | Third-party APIs, vendor quirks, external systems | | performance | Optimization learnings, benchmarks, scaling decisions | | testing | Test strategies, coverage decisions, QA patterns | | ux | Design patterns, user research insights, interactions | | strategy | Roadmap decisions, prioritization rationale |

Category selection guide:

• "How does X feature work?" → feature
• "Why did we choose X over Y?" → decisions
• "X keeps breaking in weird ways" → gotchas
• "How do we deploy/release/migrate X?" → procedures
• "How do we talk to X API?" → integration

6. Category-Specific Structure

Each category has expected sections. These are minimums - add more depth as needed to meet the Content Principles.

Feature Learnings

Feature learnings are comprehensive "dossiers" that enable someone to work on a feature without prior context.

Required sections:

• What is {Feature}? - 2-3 sentences explaining what it is and why it exists
• Why Use It? / Use Cases - Problem/solution pairs or concrete scenarios (at least 3)
• User Flows - How users interact with it (at least 2 flows)
• Technical Design - Architecture, key patterns, how it works
• Key Files - Files that matter with their purposes (at least 3)
• Common Tasks - Things someone will need to do, with how-to (at least 2)

Gotcha Learnings

Gotchas capture hard-won debugging knowledge.

Required sections:

• Symptom - What you observe when you hit this
• Root Cause - Why it happens (the non-obvious part)
• Solution - How to fix it, with code/commands
• Prevention - How to avoid hitting it again (if applicable)

Pattern Learnings

Patterns document repeatable solutions.

Required sections:

• Problem - What situation calls for this pattern
• Solution - The pattern itself, with code example
• When to Use - Specific scenarios where this applies
• Trade-offs - What you give up by using this pattern

Decision Learnings

Decisions preserve architectural choices and rationale.

Required sections:

• Context - What situation prompted this decision
• Options Considered - What alternatives existed
• Decision - What we chose
• Rationale - Why we chose it (the important part)
• Consequences - What this decision enables/prevents

Procedure Learnings

Procedures document multi-step processes.

Required sections:

• When to Use - What triggers this procedure
• Prerequisites - What you need before starting
• Steps - Numbered steps with commands/code
• Verification - How to confirm it worked

Integration Learnings

Integrations document external system connections.

Required sections:

• What it is - The external system and why we use it
• How we connect - Auth, endpoints, SDK usage
• Key Operations - Common tasks with code examples
• Gotchas - Vendor-specific quirks and workarounds

Other Categories (performance, testing, ux, strategy)

Follow the Content Principles. Include:

• Context (why this matters)
• The knowledge itself (specific, actionable)
• Examples (code, commands, or concrete scenarios)
• Pitfalls (what to watch out for)

7. Generate Skill Name

The skill name follows the pattern {category}-{slug}:

Naming rules (CRITICAL for discoverability):

VALID:   feature-auth-flows, gotchas-hook-timeout, patterns-retry-logic
INVALID: auth-flows (no category), feature/auth-flows (no slashes), feature_auth_flows (no underscores)

Rules:

• {category}-{slug} format: category prefix, then descriptive slug
• lowercase-kebab-case ONLY: letters, numbers, hyphens
• NO special characters: no colons, slashes, underscores, or parentheses
• Descriptive slug: session-restore, handling-timeouts
• 3-5 words max in slug: enough to be specific, short enough to scan

8. Match, Update, or Create

Read the registry to find candidates, then read the actual skill file to compare content.

Registry scan - look for:

• Same category prefix
• Overlapping trigger keywords
• Related topic

If candidate found, read {{project_root}}/.agents/skills/{skill-name}/SKILL.md and check:

1. UPDATE - New knowledge contradicts, extends, or supersedes an existing learning

   • Same topic but new/better information
   • Original learning was incomplete or wrong
   • Circumstances changed (dependency updated, API changed, etc.)

2. APPEND - New learning belongs in same skill but is distinct

   • Related topic, different specific insight
   • Same category, different trigger keywords

3. CREATE - No semantic match in registry

   • New topic area
   • Different category

Decision priority: UPDATE > APPEND > CREATE (prefer consolidation over proliferation)

9. Verify Learning

Before proposing, verify the learning is accurate. This is especially important for Investigation Mode learnings.

Verification checklist:

1. Spot-check key claims (2-3 minimum)

   • Pick specific claims from your draft ("File X handles Y")
   • Read the actual file to confirm
   • If wrong, correct the learning

2. Verify file purposes

   • For each file in "Key Files", quick-read to confirm description
   • Remove files that don't match their described purpose

3. Trace one flow (for feature learnings)

   • Pick a user flow from the learning
   • Trace through actual code to confirm accuracy
   • Note any discrepancies

If verification fails:

• Correct the learning before proposing
• If uncertainty remains, flag it explicitly:

  > **Note**: The {specific area} couldn't be fully verified.
  > This may need confirmation.
  

Confidence calibration based on verification:

| Verification Result | Confidence | |---------------------|------------| | All claims verified, flows traced | high | | Most verified, minor gaps | medium | | Significant uncertainty, partial verification | low |

For Investigation Mode learnings, default to medium unless verification is thorough.

10. Propose

Stop and wait for user response. Format depends on action type:

For UPDATE (revising existing learning):

I'd update the skill: `{skill-name}`

**Current**: {1-2 sentence summary of existing}
**Proposed**: {1-2 sentence summary of revision}
**Reason**: {contradicts|extends|supersedes} - {why}

{Updated content preview - FULL content, not summary}

Update this? [Y/n/edit]

For APPEND (adding to existing skill):

I'd append to the skill: `{skill-name}`

**{Title}**

{Full content following category structure}

Trigger: {keywords}
Confidence: {low|medium|high}

Save this? [Y/n/edit]

For CREATE (new skill):

I'd create a new skill: `{skill-name}`

**{Title}**

{Full content following category structure}

Trigger: {keywords}
Confidence: {low|medium|high}

Create this? [Y/n/edit]

Confidence (determined in Step 9 - Verify Learning):

• low = observed once, or Investigation Mode with partial verification
• medium = repeated/taught, or Investigation Mode with solid verification
• high = battle-tested, or fully verified with traced flows

<CRITICAL> Always show FULL proposed content, not summaries. The user needs to see exactly what will be saved to approve it. Sparse proposals lead to sparse learnings. </CRITICAL>

11. Handle Response

• y/yes -> write as proposed
• n/no -> cancel
• edit or custom text -> modify first
• Different skill name -> use that instead

12. Write Learning

Location: {{project_root}}/.agents/skills/{skill-name}/SKILL.md

Skill Template:

---
name: {skill-name}
description: Use when {triggering conditions - MUST start with "Use when"} TRIGGER when: {comma-separated trigger keywords}
user-invocable: true
---

# {Title}

**Trigger**: {keywords}
**Confidence**: {level}
**Created**: {YYYY-MM-DD}
**Updated**: {YYYY-MM-DD}
**Version**: 1

{Content - follows category-specific structure from Section 6}

UPDATE - Revise existing skill:

1. Preserve **Created** date
2. Set **Updated** to today
3. Increment **Version** by 1
4. Update confidence if warranted (e.g., low → medium after verification)

APPEND - For skills with multiple sections, add new section:

---

## {New Section Title}

**Trigger**: {keywords}
**Confidence**: {level}
**Created**: {YYYY-MM-DD}
**Updated**: {YYYY-MM-DD}
**Version**: 1

{Explanation}

13. Register the Learning

Run spectre-register (on PATH via the plugin bin/ directory) to update the registry, regenerate the recall skill, and inject TRIGGER when: into all skill frontmatter descriptions.

<CRITICAL> **Registry description format:**

The description is used to MATCH knowledge to tasks. It must describe WHEN to use the knowledge, not what it contains.

• MUST start with "Use when..."
• Describes triggering CONDITIONS
• Focuses on tasks/scenarios that need this knowledge

Good: "Use when modifying spectre plugin, debugging hooks, or adding knowledge categories" Good: "Use when auth fails silently or tokens expire unexpectedly" Bad: "spectre plugin architecture" (describes content, not when to use) Bad: "Authentication system overview" (too vague, no triggering conditions) </CRITICAL>

spectre-register \
  --project-root "{{project_root}}" \
  --skill-name "{skill-name}" \
  --category "{category}" \
  --triggers "{triggers}" \
  --description "{description}"

This single command handles:

• Creating/updating the registry entry in registry.toon
• Regenerating the spectre-recall/SKILL.md skill
• Injecting TRIGGER when: lines into ALL registered skills' frontmatter descriptions (so triggers are visible in the session skill list without reading the registry)

14. Confirm

Saved .agents/skills/{skill-name}/SKILL.md
Registered in .agents/skills/spectre-recall/references/registry.toon