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