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.

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?

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:

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 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:

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

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.

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

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