massimodeluisa/recursive-decomposition

Recursive Decomposition Guidelines

References

Consult these resources as needed:

• ./references/rlm-strategies.md -- Detailed decomposition patterns from the RLM paper
• ./references/cost-analysis.md -- When to apply recursive vs. direct approaches
• ./references/codebase-analysis.md -- Full walkthrough of codebase-wide analysis
• ./references/document-aggregation.md -- Multi-document information extraction

Core Principles

CRITICAL: Treat inputs as environmental variables, not immediate context.

Most tasks fail when context is overloaded. Instead of loading entire contexts into the processing window, treat inputs as environmental variables accessible through code execution. Decompose problems recursively, process segments independently, and aggregate results programmatically.

Progressive Disclosure: Load information only when necessary. Start high-level to map the territory, then dive deep into specific areas.

When Recursive Decomposition is Required

• Tasks involving 10+ files
• Input exceeding ~50k tokens where single-prompt context is insufficient
• Multi-hop questions requiring evidence from multiple scattered sources
• Codebase-wide pattern analysis or migration planning

When Direct Processing Works

• Small contexts (<30k tokens)
• Single file analysis
• Linear complexity tasks with manageable inputs

Operational Rules

• Always identify the search space size first.
• Always use grep or glob before view_file on directories.
• Always partition lists > 10 items into batches.
• Never read more than 5 files into context without a specific plan.
• Verify synthesized answers by spot-checking source material.
• Mitigate "context rot" by verifying answers on smaller windows.
• Treat yourself as an autonomous agent, not just a passive responder.

Large File Handling Protocols

CRITICAL: Do NOT read large files directly into context.

1. Check Size First: Always run wc -l (lines) or ls -lh (size) before view_file.
2. Hard Limits:
   • Text/Code: > 2,000 lines or > 50KB -> MUST use view_file with start_line/end_line or head/tail.
   • PDFs: > 30MB or > 100 pages -> MUST be split or processed by metadata only.
3. Strategy:
   • For code: Read definitions first (grep -n "function" ...) then read specific bodies.
   • For text: Read Table of Contents or Abstract first.

Tool Preferences

• grep / glob not ls -R (unless mapping structure).
• view_file with line ranges (offset/limit) not full file reads for huge files.
• wc -l / ls -lh before reading unknown files.
• run_command (grep) not read_file for searching.
• task tool for sub-agents (recurse).

Empowering Agentic Behavior

To maximize effectiveness:

• Self-Correction: Always verify your own work. If a result seems empty or wrong, debug the approach (e.g., check grep arguments) before giving up.
• Aggressive Context Management: Regularly clear irrelevant history. Don't let the context window rot with dead ends.
• Plan First: For any task > 3 steps, write a mini-plan.
• Safe YOLO Mode: When appropriate (e.g., read-only searches), proceed with confidence without asking for permission on every single step, but stop for critical actions.

Cost-Performance Tradeoffs

• Smaller contexts: Direct processing may be more efficient.
• Larger contexts: Recursive decomposition becomes necessary.
• Threshold: Consider decomposition when inputs exceed ~30k tokens or span 10+ files.

Balance thoroughness against computational cost. For time-sensitive tasks, apply aggressive filtering. For comprehensive analysis, prefer exhaustive decomposition.

Anti-Patterns to Avoid

• Excessive sub-calling: Avoid redundant queries over the same content.
• Premature decomposition: Simple tasks don't need recursive strategies.
• Lost context: Ensure sub-agents have sufficient context for their sub-tasks.
• Unverified synthesis: Always spot-check aggregated results.

Scalability (Chunking & filtering)

1. Filter Before Deep Analysis

Narrow the search space before detailed processing:

# Instead of reading all files into context:
1. Use Grep/Glob to identify candidate files by pattern
2. Filter candidates using domain-specific keywords
3. Only deeply analyze the filtered subset

Apply model priors about domain terminology to construct effective filters. For code tasks, filter by function names, imports, or error patterns before full file analysis.

2. Strategic Chunking

Partition inputs for parallel or sequential sub-processing:

• Uniform chunking: Split by line count, character count, or natural boundaries (paragraphs, functions, files).
• Semantic chunking: Partition by logical units (classes, sections, topics).
• Keyword-based partitioning: Group by shared characteristics.

Process each chunk independently, then synthesize results.

3. Incremental Output Construction

For generating long outputs:

1. Break output into logical sections
2. Generate each section independently
3. Store intermediate results (in memory or files)
4. Stitch sections together with coherence checks

Agent Behavior

Recursive Sub-Queries

Invoke sub-agents (via Task tool) for independent segments:

For large analysis:
1. Partition the problem into independent sub-problems
2. Launch parallel agents for each partition
3. Collect and synthesize sub-agent results
4. Verify synthesized answer if needed

Answer Verification

Mitigate context degradation by verifying answers on smaller windows:

1. Generate candidate answer from full analysis
2. Extract minimal evidence needed for verification
3. Re-verify answer against focused evidence subset
4. Resolve discrepancies through targeted re-analysis

Implementation Patterns

Pattern A: Codebase Analysis

Task: "Find all error handling patterns in the codebase"

Approach:

1. Glob for relevant file types (*.ts, *.py, etc.)
2. Grep for error-related keywords (catch, except, Error, throw)
3. Partition matching files into batches of 5-10
4. Launch parallel Explore agents per batch
5. Aggregate findings into categorized summary

Pattern B: Multi-Document QA

Task: "What features are mentioned across all PRD documents?"

Approach:

1. Glob for document files (*.md, *.txt in /docs)
2. For each document: extract feature mentions via sub-agent
3. Aggregate extracted features
4. Deduplicate and categorize
5. Verify completeness by spot-checking

Pattern C: Information Aggregation

Task: "Summarize all TODO comments in the project"

Approach:

1. Grep for TODO/FIXME/HACK patterns
2. Group by file or module
3. Process each group to extract context and priority
4. Synthesize into prioritized action list