s-compound

name	s-compound
description	Capture session learnings - extracts reusable knowledge and saves to docs/solutions/ (NEVER SKIP)

/s:compound - Knowledge Compound

Extract reusable learnings from the current session and persist them to docs/solutions/. This skill is the project's long-term memory. It must NEVER be skipped after feature work, bug fixes, or significant changes.

Why This Exists

Without compounding, every session starts from zero. Knowledge stays in chat history and vanishes when the context window rolls over. This skill captures what was learned so future sessions (and future developers) benefit.

Instructions

Step 1: Gather Session Context

Read the following sources to understand what happened in this session:

1. Git history: Run git log --oneline -20 to see recent commits
2. Git diff: Run git diff HEAD~5..HEAD --stat to see what files changed (adjust range as needed)
3. State file: Read .planning/STATE.md for decisions made during this session
4. Brainstorms: Check docs/brainstorms/ for any design context created this session
5. Plans: Check docs/plans/ for any implementation plans created this session

Synthesize a clear picture of what was built, fixed, or discovered.

Step 2: Ask the User

Present a summary of what you found, then ask:

"Based on the session, here is what I see was accomplished:

• {bullet list of work done}

What were the key learnings? Anything surprising, tricky, or worth remembering for next time?"

Wait for user input. Their perspective adds context that code alone does not capture.

Step 3: Extract Reusable Patterns

From the session context and user input, identify:

• Patterns: Reusable approaches that worked well
• Solutions: Specific fixes to specific problems
• Gotchas: Things that were harder than expected or had hidden requirements
• Decisions: Why a particular approach was chosen over alternatives
• Anti-patterns: Things that were tried and did NOT work

Step 4: Write the Solution Document

Create a new file at docs/solutions/YYYY-MM-DD-{topic}.md where:

• YYYY-MM-DD is today's date
• {topic} is a kebab-case descriptor (e.g., auth-flow-with-supabase, test-pollution-fix)

Use this format:

# {Topic Title}

## Problem
{What problem was being solved? What was the starting state?}

## Solution
{How was it solved? Include specific steps, code patterns, or configurations.
Be concrete enough that someone could reproduce this without the original context.}

## Why It Works
{Explain the reasoning. Why this approach over alternatives?
What trade-offs were accepted?}

## Gotchas
{Things to watch out for when applying this solution.
Edge cases, version-specific behavior, ordering dependencies, etc.}

## Related
- {Link to relevant files in the codebase}
- {Link to relevant docs, brainstorms, or plans}
- {Link to external resources if applicable}

Step 5: Update State

1. Update .planning/STATE.md:
   • Add a decision entry: | {DATE} | Compound: {topic} | Learnings captured in docs/solutions/ |
2. If this was the final step in a phase, note phase completion

Step 6: Suggest Next Steps

Output to the user:

Learnings captured: docs/solutions/{filename}.md

This knowledge is now part of the project's permanent memory.
Future sessions will benefit from these learnings.

Next steps:
- Run `/s:retro` for a full retrospective of this phase
- Run `/s:status` to see overall project progress

Rules

1. NEVER SKIP THIS SKILL after completing feature work, bug fixes, or significant refactoring
2. Every solution document must have all 5 sections (Problem, Solution, Why It Works, Gotchas, Related)
3. Be specific and concrete - vague learnings are not useful
4. Include file paths and code references where applicable
5. If multiple distinct topics were addressed, create separate solution documents for each
6. Do not duplicate information already in brainstorms or plans - reference them instead

When to Run

Trigger	Action
After /s:ship	Always - capture what was shipped
After a bug fix	Always - capture the root cause and fix
After a refactor	Always - capture why and how
After a difficult debugging session	Always - capture the investigation
After discovering something unexpected	Always - capture the surprise
After a trivial change	Optional - use judgment

Integration

• /s:ship suggests running this skill after every successful ship
• /s:retro reads from docs/solutions/ to build retrospective insights
• /s:resume reads recent solutions to reconstruct session context
• Session-start hook checks for recent solutions in the last 3 days