Skip to content

synesenom/ran / .claude/skills/compound

compound

Verified

Compound Skill

You are documenting a solved problem so that future sessions can learn from it.

Core Principle

Every solved problem should make future problems easier. Capture the problem, root cause, fix, and prevention strategy in a searchable format.

Workflow

When the user invokes /compound or /compound <description>:

1. Gather Context

If a description is provided, use it as context. Otherwise, first sync the fresh upstream ref without touching the local main branch: git fetch origin main. Then:

  • git diff origin/main...HEAD
  • git log origin/main..HEAD --oneline
  • Spawn the discovery-thoughts agent to find the related plan/research

2. Check for Existing Solutions

Spawn the discovery-thoughts agent to search for related past solutions (by category, tags, and keywords from the diff). This runs before insight extraction so duplication can be judged before a new file is drafted, not after.

Also check whether this change supersedes — not merely duplicates — a specific past solution: the old file's root cause or prevention strategy is now known to be wrong, incomplete, or replaced (as opposed to Duplicate, where the old file's guidance was correctly reapplied). Note the candidate path if so; it feeds step 5's supersession step.

3. Extract Insight

Spawn the ops-insight agent with: the diff summary, commit messages, plan path (or N/A), branch name, and the related past solutions found in step 2 (path + problem/root-cause/prevention summary for each).

The agent returns a draft with a confidence field: High, Duplicate, or Low.

4. Decide Whether to Document

  • High confidence: Proceed to step 5.
  • Duplicate confidence: Skip writing a new file. If the affected code doesn't already reference the existing solution, add the WHY-comment link (step 6) pointing at it. Report:

    "Compound: skipped — already covered by solutions/<category>/<existing-file>.md."

  • Low confidence: Skip silently. Report:

    "Compound: skipped — changes don't contain a clear, documentable insight."

Trivial changes to always skip:

  • Typo fixes, formatting-only changes
  • Import reordering, method reordering
  • Renames with no logic change
  • Comment-only additions
  • A routine reapplication of an already-documented pattern with no new failure mode (this is what ops-insight's Duplicate confidence flags — see above)

5. Write the Solution Document

Create at: solutions/<category>/YYYY-MM-DD-HHmm-<description-slug>.md

Categories: distribution, algorithm, correctness, special-functions, performance, testing, tooling

A new solution always gets status: complete — never set anything else at write time. Use this format:

---
date: <ISO timestamp>
category: "<category>"
problem: "<one-line problem summary>"
status: complete
related_issue: "<#number or N/A>"
related_plan: "<path or N/A>"
tags: [<relevant keywords>]
---

# Solution: <description>

**Date**: <timestamp>
**Category**: <category>
**Related Issue**: <#number or N/A>

## Problem

<What went wrong — symptoms, not just "file X was changed">

## Root Cause

<Why it happened — the underlying mathematical or implementation issue>

## Fix

<What was done — the approach and reasoning>

## Prevention Strategy

<How to avoid this in the future — patterns to follow, checks to add>

## Related Solutions

- <Link to related past solutions, if any>

## Key Insight

<One sentence capturing the most important takeaway>

If step 2 flagged a past solution as superseded by this one (its root cause or prevention strategy is now wrong or incomplete — see step 2), update that older file's frontmatter in place: set status: superseded and add superseded_by: "solutions/<category>/<this-new-file>.md". Leave the rest of the old file untouched — it stays as an immutable historical record, just no longer the authoritative guidance for its topic. Stage it alongside the new file in step 7.

6. Link in Code

After writing the solution file, insert a reference at the most directly affected code location:

  • Function/class fix → WHY comment at the changed line:
    // See solutions/<category>/YYYY-MM-DD-HHmm-<slug>.md
    
  • Module-wide decision → reference in the module's top comment
  • Use the relative path from the repo root (grep-able)

Stage the code change together with the solution file.

7. Commit

git add solutions/<category>/YYYY-MM-DD-HHmm-<slug>.md <affected-file-if-linked> <superseded-file-if-any>
git commit -m "Solution compounded for #<issue> — <slug>"

Do not push here — let the caller handle pushing.

8. Report

"Solution documented at:

solutions/<category>/YYYY-MM-DD-HHmm-<slug>.md

Key insight: "

Rules

DO:

  • Let ops-insight decide whether the work is worth documenting
  • Focus on the WHY (root cause) and the LESSON (prevention)
  • Use specific, searchable tags
  • Reference related past solutions when they exist

DO NOT:

  • Ask the user for input — the system decides autonomously
  • Document trivial changes — skip them silently
  • Write solutions that just describe the diff without insight
  • Skip the prevention strategy — this is the compounding value
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall