Compound Learnings

Steps

Read assets/solution-template.md for the solution document template and tagging guidelines.

1. Gather the Learning

If an issue file is provided, read it thoroughly — including all accumulated sections from prior pipeline steps:

• ## Context — initial problem analysis (from /capture-issue)
• ## Research Notes — findings, patterns, constraints (from /plan-issue)
• ## Implementation Notes — decisions, trade-offs, gotchas (from /work-on-task)
• ## Activity — timestamped session logs (from /work-on-task)

These sections contain the full history of the issue lifecycle. Use them to extract learnings.

If no issue file is provided, ask the user:

• What was the problem? (symptom)
• What caused it? (root cause)
• How was it fixed? (solution)
• How can it be prevented? (prevention)

2. Categorize

Choose the most appropriate category for docs/solutions/:

• performance-issues/ — slow queries, memory leaks, scaling problems
• security-issues/ — vulnerabilities, auth bugs, data exposure
• build-errors/ — dependency issues, compilation failures, CI problems
• configuration-fixes/ — environment config, deployment issues, integration problems

If none fit, create a new category directory.

3. Create Solution File

Path: docs/solutions/<category>/<descriptive-slug>.md

Use the template from assets/solution-template.md. Follow the tagging guidelines in that file.

4. Graduate to Agent Context (Curation Step)

Evaluate whether this learning should be graduated to .github/agent-context.md — the curated project memory that every agent session reads at start.

Graduate when the learning reveals:

• A project-level convention ("In this project, we always X because Y")
• An architectural pattern ("Service A communicates with B via events, not direct calls")
• A recurring gotcha ("The payments API returns 200 on validation failure — check the response body")
• An active decision ("We chose library X over Y because Z — don't switch without team discussion")

Don't graduate when the learning is:

• A one-time fix (the solution doc in docs/solutions/ is sufficient)
• Too detailed for a one-liner (keep the detail in the solution doc, link from agent-context)
• Already covered by existing conventions or instructions

When graduating, add to the appropriate section of agent-context.md:

### [Category]: [Brief finding]
[One-sentence summary. See docs/solutions/<file> for details.]

Curation check: If agent-context.md exceeds ~200 lines, review for stale entries — patterns that are no longer accurate, decisions that have been superseded, or gotchas that have been fixed. Remove or archive stale entries to keep the file compact and high-signal.

5. Update Plan File

If working from a plan file, set status: done and append a final activity entry:

### YYYY-MM-DD HH:MM — Issue completed
- Learning documented: `docs/solutions/<category>/<file>.md`
- Agent context updated: [Yes/No]
- **Status:** Done

6. Print Summary

Confirm: "Learning documented at docs/solutions/<path>. Future agents will reference this when encountering similar problems."

Trigger Examples

Should trigger:

• "Document what we learned from this bug fix"
• "Save this solution for future reference"
• "Let's compound this learning"

Should not trigger:

• "Plan this feature" → /plan-issue
• "Review this code" → /code-review
• "Fix this bug" → /tdd-fix

Guardrails

• Keep solution files focused — one problem, one solution per file.
• Include enough context that someone unfamiliar with the codebase can understand the learning.
• Use specific code examples, not vague descriptions.
• Tag accurately — tags are how future agents find relevant learnings.