Compound

Compound

Document a recently solved problem or shipped feature to compound your project's knowledge. Each documented solution makes future planning and implementation faster — the agent consults docs/solutions/ during /research and /write-a-prd, so lessons learned today prevent mistakes tomorrow.

When the work surfaced planning or estimation surprises, capture those too. McConnell-style calibration only happens if actual work feeds back into future shaping.

Invocation Position

This is a primary pipeline skill that closes the compounding loop. It runs near the tail of the default delivery path, after /pre-merge has created the PR.

Default — capture the lesson in the PR, before merge. When a durable lesson is already known at PR time, run /compound on the open PR branch so the docs/solutions/ entry rides the same PR as the code that taught it — reviewed in the same pass and merged atomically with it. This places /compound between /pre-merge and /closeout:

… → /pre-merge → /compound (in-PR, when a lesson exists) → /closeout (merge + teardown) → cleanup

Fallback — capture post-merge. Some lessons only surface during or after the merge: integration surprises, QA findings, behavior seen once it ships. For those, run /compound after /closeout has merged. This is the fallback path, not the default.

Either way, /compound never performs the merge or worktree teardown itself — that is /closeout. Capturing in-PR means committing onto the open PR branch so the lesson is reviewed like any other change; it does not mean merging.

Do not use it for trivial edits or for lessons that belong entirely in a higher-fidelity artifact like a test, linter rule, or code comment without any durable project-level learning. Whether in-PR or post-merge, the "When NOT to Use" guard below still applies — most PRs carry no durable lesson, and there is no standing per-PR docs/solutions/ slot to fill.

Why This Exists

Without this step, you've done traditional engineering with AI assistance. The first three steps of the workflow (plan, work, review) produce a feature. This fourth step produces a system that builds features better each time.

When to Use

• When a feature's PR is ready and it taught a durable lesson — capture it onto the PR before merge (the happy path)
• After shipping, when a lesson only became clear during or after the merge (the post-merge fallback)
• After fixing a tricky bug where the root cause was non-obvious
• After a QA cycle revealed issues that could have been caught earlier
• After making an architectural decision with significant tradeoffs
• When you've discovered a pattern that should be reused

When NOT to Use

• For trivial fixes (typo corrections, simple config changes)
• When the solution is already well-documented in official library docs
• When the lesson is project-specific but you're about to deprecate that code
• When the work was a clean execution of a pre-shaped plan — no surprises, no rework, no non-obvious decisions. The issue body and PR description already carry that record; a docs/solutions/ entry with no reusable lesson trains future readers to skim
• When in doubt — skipping costs nothing because the issue and PR persist in GitHub. Capturing a low-value lesson costs future planners' attention every time they consult docs/solutions/

Execution Flow

Phase 1: Identify What to Capture

On the in-PR default path the work under review is the open PR branch, so the commands below read it directly (git log and git diff main...HEAD against the still-unmerged branch). On the post-merge fallback path, run them in a session that can still see the merged feature's history — once /closeout has pruned the branch and pulled base, git diff main...HEAD is empty and you must read the PR diff via gh pr diff instead. Either way, review the recent work. Look at:

1. Git log — What commits were made? What changed?

``bash git log --oneline -20 ``

1. Issue thread — What was the original problem? What was discussed?

1. The diff — What files changed? What patterns emerged?

``bash git diff main...HEAD --stat ``

Ask the user: "What was the most important thing you learned or the trickiest part of this feature?" Their answer often reveals the highest-value lesson to capture.

Before writing, classify the lesson at the right level:

• Event — a one-off incident or visible failure
• Pattern — something that has happened repeatedly across features, bugs, or handoffs
• Structure — a recurring condition in the codebase, workflow, incentives, or decision process that keeps producing the pattern

Prefer capturing the highest level you can support with evidence. If the lesson is structural, name the feedback loop, missing feedback, or delayed effect that made the outcome likely.

Before proceeding, consider three questions (guidance, not a gate — if the answer is unclear, proceed and let the writing process clarify):

1. Is this genuinely novel? Check official library docs and existing docs/solutions/ files. If the lesson is already well-documented elsewhere, skip it or link to the existing source.
2. Will this still be accurate in 3 months? If the lesson is tightly coupled to a dependency version or a temporary workaround, note that — it affects the volatility classification below.
3. Could this be captured closer to the source? A behavioral invariant is better as a test. A convention is better as a linter rule. A "why" explanation is better as a code comment co-located with the decision. If the lesson can be fully captured in a higher-fidelity artifact, do that instead of (or in addition to) writing prose.
4. Was the process fixed? (Bug-fix compounds only.) Was the fix a correction (removed the defect) or a workaround (suppressed the failure)? Were structurally similar patterns elsewhere in the codebase found and addressed? What process change would prevent this defect class from entering the codebase again — a stronger test, a linter rule, an assertion, a planning checklist item? If the answer is "nothing," the mechanism that produced this defect is still active.

Rabbit Hole review. If a PRD issue exists for this feature, read its Rabbit Holes section. For each one, check: did the pre-decided resolution hold, or did it need to be revised during implementation? Rabbit Holes that bit — required a different resolution than planned, or surfaced late despite being named — are high-value compound targets. Capture the risk pattern and the actual resolution in docs/solutions/ so future /write-a-prd sessions surface them during the completeness scan. Rabbit Holes that held as planned are less valuable to document unless the risk pattern is likely to recur in unrelated features.

Scope accuracy check. Also check: did this feature reveal a scope lesson worth capturing?

• Were significant activities omitted from the original decomposition that had to be discovered during implementation?
• Did a specific type of work (auth integration, data migration, UI state management) consistently appear as unplanned scope additions?

If a scope pattern emerges (e.g., "auth changes in this codebase consistently require updating three additional systems"), capture it in the appropriate existing docs/solutions/ category — integration-issues/, patterns/, etc. The lesson compounds: /write-a-prd's omitted activities scan and /prd-to-issues's scope completeness check both consult docs/solutions/, so a documented pattern directly improves the next feature's planning.

If the main lesson is not about the downstream project but about Skill Kit itself — for example unclear skill boundaries, missing handoff guidance, or weak process guardrails in chrislacey89/skills — recommend /improve-pipeline if that skill is present. Do not invoke it. /compound still captures project knowledge; /improve-pipeline is for improving Skill Kit.

Calibration check. Also ask:

• Which unknowns actually drove variance between the shaped work and the implemented work?
• Did the team confuse a target, estimate, or commitment at any point?
• Did the first tracer bullet materially tighten confidence or reveal hidden work?
• Are there concrete actuals from this feature that should become a baseline for similar future work?

You do not need formal project accounting. A few truthful lines about what actually widened or narrowed the work are enough to improve future planning.

Phase 2: Classify the Problem

Determine the category for filing. Use the most specific category that fits:

| Category | When to Use | |----------|-------------| | integration-issues | External API, third-party service, library integration | | architecture-decisions | Structural choices with significant tradeoffs | | performance-issues | Optimization, N+1 queries, caching strategies | | runtime-errors | Bugs that were hard to diagnose | | logic-errors | Business logic that was subtly wrong | | testing-patterns | Testing approaches that worked well (or didn't) | | ui-patterns | Frontend patterns, component architecture | | devops | Build, deploy, CI/CD, environment issues | | security-issues | Auth, permissions, data handling | | patterns | Reusable patterns that emerged from implementation |

Phase 3: Write the Solution Document

Create the document in docs/solutions//. Use the template below.

Before writing the Root Cause section, apply two tests. First: was the outcome a predictable consequence of the decision, or did it depend on conditions that weren't available to reason about at decision time? If unpredictable from the decision, the lesson belongs in Context (what you now know about the environment), not Prevention (what to do differently next time). Second: under what conditions would this lesson mislead a future agent? If you can't name a condition that would make the lesson wrong, tighten it until it's falsifiable or drop it. For Pattern and Structure lessons, record the answer in the Rule Scope section of the template so future /research consumers can pattern-match their own work's shape against the preconditions without re-deriving them from prose.

Ensure the directory exists:

mkdir -p docs/solutions/

Filename convention: -.md

Example: docs/solutions/integration-issues/ably-presence-channel-auth-2026-03-28.md

---
date: YYYY-MM-DD
category: 
problem_type: 
components: [list, of, affected, components]
technologies: [list, of, relevant, technologies]
severity: low | medium | high | critical
volatility: evergreen | stable | volatile
---

# [Problem Title]

## Problem

[1-2 sentence description of the issue. Be specific enough that someone searching for this problem would find it.]

## Context

[What were you building when this came up? What was the expected behavior vs actual behavior?]

## Symptoms

[Observable symptoms that would help someone recognize they're hitting the same issue.]

- [Symptom 1 — error message, behavior, timing]
- [Symptom 2]

## Root Cause

[Why this happened. Be precise — not "the API was wrong" but "Ably's presence channel requires explicit auth via a server-side token request endpoint, not client-side API key auth."]

## Learning Level

- **Level:** Event / Pattern / Structure
- **Feedback loop or delay:** [If applicable, what reinforcing loop, balancing loop, missing feedback, or delayed effect made this likely?]

## Rule Scope

*Required for Pattern and Structure lessons. Optional for Event lessons — include only when the event's Solution embeds a transferable rule.*

[State the structural conditions under which the Solution's recommendation is correct, so a future `/research` consumer can pattern-match against their own work's shape without re-deriving the preconditions from prose. Be specific about shape, not just keywords — a 2-step agent loop with a terminal forced tool is a different shape from a 3-step loop where the same tool is non-terminal, even though both mention the same tool name. Note where the rule inverts if the conditions differ, and cross-reference sibling docs that cover the inverted or adjacent shape.]

- **Applies when:** [Structural preconditions — e.g., "the forced tool is terminal in the agent loop", "the callback replaces rather than merges the collection", "the component is a client component rendered inside an RSC boundary"]
- **Inverts or does not apply when:** [The shapes where following this recommendation would produce the opposite of the intended outcome, or simply not help — e.g., "for N+1-step loops where the tool is non-terminal, the `stopWhen` list must exclude it; see ``"]
- **Sibling docs:** [Links to `docs/solutions/` entries covering adjacent or inverted shapes, if any exist]

[Diagram suggestion: if Rule Scope describes conditional applicability with ≥3 distinguishable branches (multiple Applies-when shapes, or several Inverts-or-does-not-apply shapes that diverge in different directions), consider invoking `/mermaid` for a decision diagram showing which conditions route to which recommendation. Skip when the rule is binary (one Applies-when, one Inverts-when) — prose is already the cleanest rendering at that size.]

## Solution

[The actual fix. Include before/after code when it helps.]

**Before:**
```typescript
// What didn't work and why

After:

// What works and why

Prevention

[How to avoid this in the future. Separate code-level and process-level strategies.]

Code-level: [Tests, assertions, checks, linter rules that would catch this defect or its siblings.]

Process-level: [Pipeline step changes — e.g., "add auth token refresh to /write-a-prd's omitted activities scan" or "this defect class is a specification error; invest more in /shape for this domain."]

Planning / Calibration Notes

[Include when the lesson should change future shaping, decomposition, or commitment language.]

• What widened the work: [Unknowns, omitted activities, or integration surprises]
• What tightened the work: [Tracer bullet, research answer, reused pattern, or existing baseline]
• Future planning adjustment: [What /research, /write-a-prd, or /prd-to-issues should do differently next time]

Actuals Worth Reusing

[Include when this feature produced a reusable baseline for future work. Keep it lightweight and qualitative if hard numbers are unavailable.]

• Comparable future work: [What kind of feature this should inform]
• Reusable baseline: [Size, effort shape, scope pattern, or dependency pattern to remember]

Defect Classification (bug-fix compounds only)

Origin phase: Specification error / Design error / Coding error Fix type: Correction (addresses root cause) / Workaround (suppresses symptom — note what the real fix would require)

Key Decision

[If an architectural or library choice was made, document it here.]

Decision: [What was chosen] Rationale: [Why] Alternatives considered: [What else was evaluated] Revisable: [Yes/No — and under what conditions]

Related

• [Link to GitHub issue or PR if applicable]
• [Link to related docs/solutions/ files if they exist]
• [Link to the research spike issue when one exists for this feature — Refs #. This preserves the causal chain from research → PRD → slices → PR → compound, citable from any machine. If the project uses archive-mode research instead, omit this link — archive paths are openable only by the originating user, so they add no value to a docs/solutions/ entry that may be read by others.]

Shelf Life

[What change would make this solution unnecessary? E.g., "When Ably SDK v3 ships built-in auth" or "When we refactor the auth module per RFC #42". If this is an enduring principle, write "Evergreen — no expiration condition."]

**Adjust the template to fit the content.** Not every solution needs eve

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [chrislacey89](https://github.com/chrislacey89)
- **Source:** [chrislacey89/skills](https://github.com/chrislacey89/skills)
- **License:** MIT
- **Homepage:** https://skills.sh/chrislacey89/skills

Install and usage instructions live in the source repository linked above.