Recursive Decomposition

Install

npx skills add massimodeluisa/recursive-decomposition-skill

This is third-party code. Review the repository files before installing.

What it does

The skill changes how the agent handles large inputs. The agent first sizes the input, narrows it with searches rather than reads, and splits the rest into batches of 5 to 10 files. Each batch goes to a separate sub-agent with a self-contained brief, with recursion limited to one level. The merged answer is checked against sources and returned with file and line references. PDFs and Office files are converted to markdown first.

Who it is for. For developers and analysts who ask an agent to analyze a whole repository or a large document set.

Example request

Find every error handling site across the repository and group them by approach

Limitations

Working through sub-agents costs more tokens and time than reading a small input directly. For PDFs the skill uses Firecrawl's anydoc via npx, and cloud firecrawl parse for scans, which needs a Firecrawl account and spends credits. Performance figures come from the paper, not from the skill author's measurements on your tasks.

How to disable. Uninstall the recursive-decomposition plugin via claude plugin or delete the recursive-decomposition folder from your skills directory.

Security check

• Runs search and file conversion commands via npx
• May send scanned PDFs to the Firecrawl cloud service

README in short

The README describes how models degrade on long context and the six-step protocol. Install via the skills CLI, as a Claude Code plugin or by copying the folder. It includes a table of when to decompose versus read directly, results from the paper and the author's own run on a corpus of mortgage PDFs. MIT licensed.

SKILL.md

---
name: recursive-decomposition
description: "Decompose dense codebase-wide, multi-document, PDF, and aggregation work even when the input fits the context window, following Recursive Language Models (Zhang, Kraska, Khattab, 2025). Use when the user asks to analyse all files, a whole repo, all docs, large PDFs, or to aggregate or multi-hop across scattered sources. Skip one file, one function, a single needle, or a one-page PDF conversion. Triggers: long context, context rot, large codebase, many files, all files, big document, multi-document, PDF, aggregate, summarize everything, codebase-wide, multi-hop, recursive, sub-agents, map-reduce."
license: MIT
metadata:
  author: massimodeluisa
  version: "1.2.0"
  paper: https://arxiv.org/abs/2512.24601
---

# Recursive Decomposition

Long inputs rot. Details get missed, distant parts get glued together by guesswork, and the reasoning drifts. The RLM paper calls it context rot. Do not load the whole input into the window. Treat it as an environment you query: size it, narrow it, split it, hand independent parts to sub-agents, verify on a small window, synthesise in code. Based on [Recursive Language Models](https://arxiv.org/abs/2512.24601) (Zhang, Kraska, Khattab, 2025).

## How to use

- `/recursive-decomposition`: apply the protocol below to the current task.
- `/recursive-decomposition <path or question>`: size that input first, then run the protocol on it.

## When it applies

Fit is not the test. Dense work can rot inside a million-token window. In the paper, OOLONG-Pairs is 32k tokens and GPT-5 scores 0.1% F1; RLM(depth=1) reaches 58.0% (arXiv:2512.24601, Table 1). 30k and 50k below are harness caps.

| Situation | Approach |
|-----------|----------|
| One file, one function, or a single needle | Read directly |
| Linear aggregate or list-everything, and completeness matters | Decompose (this skill) |
| Pairwise, quadratic, or multi-hop across scattered sources | Decompose, even under 30k tokens |
| 10+ files or 50k+ tokens | Decompose |
| Under 30k tokens and a localised answer | Read directly |

## Protocol

1. **Size the input** before reading anything: count files (glob, `find`), lines (`wc -l`), bytes (`ls -lh`), pages for PDFs.
2. **Filter** the search space with searches (content search, file patterns, keywords, file types) before opening any file. Chain filters: file type, then keyword, then meaning.
3. **Chunk** what remains: natural units (functions, classes, sections), line ranges, or keyword partitions. Batches of 5 to 10 files.
4. **Recurse** at depth 1: one sub-agent per independent batch, self-contained brief (files, question, output schema); run one parallel wave. Write the batch count first. If more batches remain, run the next wave after the merge. Sub-agents answer; they do not spawn sub-agents.
5. **Verify** the synthesised answer on a smaller window: extract the minimal evidence and re-check it; settle disagreements with a targeted re-read.
6. **Synthesise programmatically**: aggregate the structured results, deduplicate, categorise, then write the answer with file and line references.

Related