recursive-boil-down
Decompose a system, repository, or architecture into four tiers — Macro (whole system), Bricks (components), Elements (conceptual primitives), Primitives (base operations) — reading target source plus its seed.yaml, then output a comparison table of the new system against existing substrates to expose reuse and overlap before anything new is built. Triggers on "boil down", "decompose into primitives", "recursive boil-down", or analyzing a new repo/architecture against what already exists.
Best use case
recursive-boil-down is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Decompose a system, repository, or architecture into four tiers — Macro (whole system), Bricks (components), Elements (conceptual primitives), Primitives (base operations) — reading target source plus its seed.yaml, then output a comparison table of the new system against existing substrates to expose reuse and overlap before anything new is built. Triggers on "boil down", "decompose into primitives", "recursive boil-down", or analyzing a new repo/architecture against what already exists.
Teams using recursive-boil-down should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/recursive-boil-down/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How recursive-boil-down Compares
| Feature / Agent | recursive-boil-down | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Decompose a system, repository, or architecture into four tiers — Macro (whole system), Bricks (components), Elements (conceptual primitives), Primitives (base operations) — reading target source plus its seed.yaml, then output a comparison table of the new system against existing substrates to expose reuse and overlap before anything new is built. Triggers on "boil down", "decompose into primitives", "recursive boil-down", or analyzing a new repo/architecture against what already exists.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Recursive Boil-Down Protocol Strip a system down to what it *is made of*, tier by tier, until it can be compared honestly against everything that already exists — so the verdict "build new" is earned rather than assumed. ## Why this exists Delegated agents reinvent existing tools because they meet a system at its surface (the Macro tier) where everything looks unique. Two systems that look unrelated at the surface usually share most of their Elements and nearly all of their Primitives. Decomposing before building converts "this is new" into a precise statement of *which tier* is actually new — and routes everything below that tier to reuse. ## The four tiers | Tier | Question | Granularity | Example (a prompt-registry system) | |------|----------|-------------|-----------------------------------| | **Macro** | What is the whole thing for? | 1 system | "durable registry of every prompt issued across sessions" | | **Bricks** | What components compose it? | 3–12 components | capture hook, session parser, index generator, archive store | | **Elements** | What concepts do the bricks manipulate? | 5–20 concepts | session, prompt-atom, capture-event, index-entry, archive-path | | **Primitives** | What base operations recur beneath the concepts? | small closed set | append-only write, content-hash dedupe, frontmatter parse, glob-walk, ID-mint | Decomposition is **recursive**: any Brick too large to state in one sentence gets its own four-tier pass. ## Workflow ### 1. Read the declared intent - Read `seed.yaml` (or the repo's manifest/charter equivalent) **read-only** — it declares what the system believes itself to be. - If no seed exists, record that as a governance finding (undeclared system), and reconstruct intent from README + entry points. - Capture the declared Macro statement verbatim before forming your own. ### 2. Walk the source top-down - Entry points → major modules → data files. At each level ask the tier question, not "what does this code do" but "what is this *made of*". - Derive the Bricks list from actual structure (directories, services, scripts), not from documentation claims; diff against the seed's claims and note divergence. ### 3. Extract Elements and Primitives bottom-up - Elements: nouns that survive across multiple Bricks — the shared conceptual vocabulary. If a noun appears in only one Brick it's internal detail, not an Element. - Primitives: verbs/operations that recur beneath Elements. Test for primitive-hood: could this operation be lifted into a library with no domain knowledge? If yes, it's a Primitive. - Keep the Primitive set small and closed; a sprawling primitive list means you stopped one tier too high. ### 4. Build the substrate comparison table For each existing substrate in scope (sibling repos, platform services, prior systems), compare per tier: ```markdown | Tier | New system | Substrate A | Substrate B | Verdict | |------|-----------|-------------|-------------|---------| | Macro | prompt registry | session archive | atom pipeline | distinct | | Bricks | capture hook | ✅ has (PostToolUse) | ❌ | reuse A's | | Elements | prompt-atom | ≈ message-atom | ✅ identical | absorb into B | | Primitives | ID-mint | ✅ | ✅ | reuse, never re-mint | ``` Cell vocabulary: `✅ identical` / `≈ overlapping (name the delta)` / `❌ absent`. ### 5. Issue the reuse verdict The highest tier with genuine novelty determines the build posture: - Novel **Macro**, shared below → thin composition over existing substrates. Build only the composition. - Novel **Bricks** → new components inside an existing system; extend, don't fork. - Novel **Elements/Primitives only** → almost always a misreading; re-examine before believing it. - Nothing novel → **absorb**: the "new system" is a view over an existing one; route the requirement there. State the verdict explicitly with the tier that justifies it. Commit the decomposition + table as an artifact; it is the evidence the build decision cites. ## Anti-patterns - **Decomposing from documentation alone.** READMEs describe aspiration; walk the source. - **Stopping at Bricks.** Brick-level comparison hides reuse — most theft happens at Elements and Primitives. - **Comparing against zero substrates.** A boil-down without a comparison table is a diagram, not a protocol; the table is the deliverable. - **Treating the seed as ground truth.** It's the system's self-image; divergence between seed and source is itself a top-tier finding. - **Open-ended primitive lists.** If Primitives exceed ~12, you've mixed tiers; promote the domain-specific ones back up to Elements.
Related Skills
recursive-systems-architect
Designs self-referential and recursive systems that examine, modify, or generate themselves, including metacognitive architectures and strange loops.
taxonomy-modeling-design
Phase 2 of the pentaphase structural-overhaul protocol. Classifies entities, standardizes attributes, establishes relationships, and designs the access framework. Use when the user invokes phase 2 of an overhaul, asks to "design the taxonomy" or "model the structure", or has completed a landscape audit and is ready to redesign. Consumes phase-1-landscape-report.md; produces phase-2-taxonomy-model.md.
systemic-ingestion-normalization
Phase 4 of the pentaphase structural-overhaul protocol. Purges redundancies, enriches and aligns legacy entities to the new schema, executes phased ingestion into the new environment, and audits integrity. Use when the user invokes phase 4 of an overhaul, asks to "migrate the data" or "ingest into the new system", or has a configured environment ready to accept legacy entities. Consumes phase-3-environment-spec.md; produces phase-4-ingestion-report.md.
system-environment-configuration
Phase 3 of the pentaphase structural-overhaul protocol. Translates the taxonomy model into objective technical criteria, evaluates candidate mechanisms or frameworks, instantiates the chosen architecture, and programs validation rules. Use when the user invokes phase 3 of an overhaul, asks to "select a system" or "configure the environment", or has a taxonomy model and is ready to choose technology. Consumes phase-2-taxonomy-model.md; produces phase-3-environment-spec.md.
pentaphase-orchestrator
Threads the full five-phase structural-overhaul protocol — landscape discovery, taxonomy design, environment configuration, systemic ingestion, governance evolution — for any substrate the user names. Use when the user requests a structural overhaul, system redesign, or end-to-end restructuring of a documentation system, asset registry, code monorepo, knowledge base, or operational workflow; or when they explicitly invoke the pentaphase methodology. Coordinates handoffs between phase-skills and seats validation gates between phases.
landscape-discovery-audit
Phase 1 of the pentaphase structural-overhaul protocol. Inventories assets, maps current flow, identifies friction, and defines value metrics for any substrate. Use when the user invokes phase 1 of an overhaul, requests a baseline audit, asks to "discover the landscape" of a system, or wants to understand current state before redesigning. Produces phase-1-landscape-report.md.
governance-evolution-protocol
Phase 5 of the pentaphase structural-overhaul protocol. Codifies operational protocols, onboards the ecosystem of participants, programs behavior monitoring, and establishes an iteration cadence so the substrate evolves rather than calcifies. Use when the user invokes phase 5 of an overhaul, asks to "establish governance" or "lock in the protocols", or has completed ingestion and is ready to declare the substrate operational. Consumes phase-4-ingestion-report.md; produces phase-5-governance-charter.md, which closes the protocol.
dimension-surfacing
Surfaces the parallel domain dimensions implicit in a dense or minimal prompt. Use when a user prompt is small on the surface but plainly implies multiple independent domains needing different expertise; when explicitly invoked by the coliseum-orchestrator skill as Phase 1; or when the user asks "what dimensions does this prompt encode" or "what axes does this break into." Produces a named dimension set where each dimension is independently executable and not a paraphrase of another.
coliseum-dispatch
Dispatches a composed set of assignment envelopes to domain-expert subagents in parallel, in a single message with multiple Agent tool calls. Enforces the no-pingpong gate via the pingpong-detector agent before any dispatch fires. Use when invoked by the coliseum-orchestrator as Phase 3; when envelopes are already composed and the next step is parallel execution; or when the user asks to "fan out" or "dispatch in parallel." Produces a dispatch log capturing what was sent, when, and where returns land.
assignment-composition
Wraps each surfaced dimension as a self-contained 9-section autonomous-work-assignment envelope — scope, context, success criteria, allowed tools, return format, handoff — all the recipient subagent needs to execute without coming back. Use when invoked by coliseum-orchestrator as Phase 2; when dimensions are named and the next step is to make each independently dispatchable; or when the user asks "compose this as an assignment." The no-pingpong gate validates each envelope before dispatch.
workspace-autopsy-governance
Conducts a full automated autopsy of the current workspace directory to map files, identifies structural issues, proposes a restructuring plan (the signal), and establishes unified governance using templates. Use this skill when a user asks to map, restructure, reorganize, or apply new governance to an existing messy repository.
workshop-presentation-design
Design engaging workshops, conference talks, and educational presentations. Covers learning objectives, activity design, slide craft, and facilitation techniques. Triggers on workshop design, presentation prep, talk structure, or training session requests.