compound

name	compound
description	Capture knowledge from development sessions. Debug patterns, architecture decisions, framework gotchas, and integration learnings compound over time.

Compound: Knowledge Capture

Objective

Capture knowledge during development so it compounds over time. Every debug session, architecture decision, and framework gotcha becomes reusable knowledge for future sessions.

Principle: Knowledge that stays in a conversation dies with the context window. Knowledge that gets written down compounds.

---

When to Use

• After fixing a non-obvious bug: /compound debug convex-id-type-mismatch
• After making an architecture decision: /compound decision portkey-over-direct-api
• When you discover a framework gotcha: /compound gotcha nextjs-middleware-edge-only
• When you identify a reusable pattern: /compound pattern convex-batch-fetch
• When you learn how services connect: /compound integration mastra-convex-webhook

Agent should also suggest /compound after:

• A debug session that took >15 minutes
• Any two-strike rule invocation
• Discovering undocumented behavior
• Making a decision that future sessions need to know

---

Process

1. Parse Arguments

/compound <type> <title>

Type	Target File	Purpose
debug	.claude/reference/debug-patterns.md	What broke, why, how fixed
decision	.claude/reference/architecture-decisions.md	Why X over Y
gotcha	Relevant existing reference doc	Framework-specific traps
pattern	Relevant existing reference doc	Reusable code patterns
integration	.claude/reference/architecture.md	How services connect

2. Gather Context

Ask the agent (or user) for the key details:

For debug:

1. What was the symptom?
2. What was the root cause?
3. How was it fixed?
4. How to detect this earlier next time?

For decision:

1. What was the question?
2. What options were considered?
3. What was chosen and why?
4. What would change this decision?

For gotcha:

1. What was expected?
2. What actually happened?
3. Why? (underlying reason)
4. How to avoid it?

For pattern:

1. What problem does this solve?
2. Show the pattern (code example)
3. When to use / when not to use

For integration:

1. Which services?
2. How do they connect? (API, webhook, shared DB)
3. What data flows between them?
4. Failure modes and recovery

3. Write Knowledge Entry

Append to the appropriate reference doc using a consistent format:

### {Title}

**Added:** YYYY-MM-DD
**Context:** {One-line context}

{Content based on type — see templates below}

If the target doc doesn't exist, create it.

4. Templates by Type

Debug Pattern

### {Title}

**Added:** YYYY-MM-DD
**Symptom:** {What you saw}
**Root Cause:** {Why it happened}
**Fix:** {What resolved it}
**Detection:** {How to catch this earlier — grep pattern, lint rule, test}

Architecture Decision

### {Title}

**Added:** YYYY-MM-DD
**Question:** {What needed deciding}
**Decision:** {What was chosen}
**Alternatives:** {What was rejected}
**Rationale:** {Why this choice}
**Revisit When:** {Conditions that would change this}

Gotcha

### {Title}

**Added:** YYYY-MM-DD
**Expected:** {What you thought would happen}
**Actual:** {What happened}
**Why:** {Root cause}
**Fix:** {How to avoid}

Reusable Pattern

### {Title}

**Added:** YYYY-MM-DD
**Problem:** {What this solves}
**Pattern:**
\`\`\`typescript
// Example code
\`\`\`
**When to use:** {Conditions}
**When NOT to use:** {Anti-conditions}

Integration Learning

### {Title}

**Added:** YYYY-MM-DD
**Services:** {Service A <-> Service B}
**Connection:** {HTTP API / webhook / shared DB / message queue}
**Data Flow:** {What data, which direction}
**Failure Mode:** {What happens when it breaks}
**Recovery:** {How to recover}

5. Confirm

After writing, show:

KNOWLEDGE CAPTURED
----------------------------------------------------------------------

Type:     {debug|decision|gotcha|pattern|integration}
Title:    {title}
File:     {path to reference doc}

This knowledge will be available in all future sessions.
----------------------------------------------------------------------

---

Knowledge Files

File	Content
.claude/reference/debug-patterns.md	Recurring bugs and their fixes
.claude/reference/architecture-decisions.md	Why we chose X over Y
.claude/reference/convex-patterns.md	Convex-specific patterns (exists)
.claude/reference/nextjs-best-practices.md	Next.js patterns (exists)
.claude/reference/react-patterns.md	React patterns (exists)
.claude/reference/mastra-best-practices.md	Mastra patterns (exists)
.claude/reference/architecture.md	Integration learnings (exists)

Rule: Prefer appending to existing reference docs over creating new files. Only create a new file if no existing doc covers the topic.

---

Auto-Suggest Integration

The agent SHOULD proactively suggest /compound in these scenarios:

After a debug session:
"That was a non-obvious fix. Want to capture it? /compound debug {title}"

After a decision:
"We just decided on X. Want to record why? /compound decision {title}"

After hitting a gotcha:
"This framework behavior wasn't obvious. Capture it? /compound gotcha {title}"

---

Examples

/compound debug convex-collect-find-table-scan
/compound decision portkey-self-hosted
/compound gotcha mastra-studio-import-error
/compound pattern convex-batch-fetch-map
/compound integration frontend-mastra-brain-api