jmagly/rlm-mode

RLM Mode Skill

You detect when users need large-scale operations that would benefit from recursive decomposition and route to RLM commands instead of attempting to load everything into context.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "RLM" / "recursive language model" → explicit RLM mode activation
• "process in chunks" → chunk-based decomposition request
• "decompose and process" → explicit decomposition shorthand
• "fan out" → parallel fan-out processing across files or modules

Core Problem

Loading entire codebases or directory trees into context causes:

• Context window overflow: Exceeding model limits
• Degraded quality: Agent struggles with too much information
• Poor performance: Slow processing, truncated responses
• Memory exhaustion: System crashes on large repos

RLM solution: Decompose → Process in chunks → Aggregate results

Trigger Patterns Reference

| Pattern | Example | Why RLM? | |---------|---------|----------| | analyze all files | "analyze all TypeScript files for security issues" | Scope exceeds context window | | search the entire codebase | "search the entire codebase for authentication logic" | Need to traverse full tree | | review every module | "review every module for proper error handling" | Many independent reviews | | find all instances | "find all instances of deprecated API usage" | Requires exhaustive search | | summarize the whole repository | "summarize the whole repository structure" | Hierarchical decomposition | | check every file | "check every file for missing tests" | File-by-file evaluation | | scan all directories | "scan all directories for outdated dependencies" | Directory tree traversal | | across the entire project | "find TODOs across the entire project" | Project-wide aggregation | | throughout the repository | "identify duplicated code throughout the repository" | Cross-file comparison | | recursively process | "recursively process src/ and generate docs" | Explicit recursion request | | batch process | "batch process all markdown files for formatting" | Parallel batch operation | | apply to all | "apply linting rules to all JavaScript files" | Bulk transformation | | update every | "update every component to use new API" | Mass refactoring | | generate for each | "generate tests for each module in lib/" | Templated generation |

Detection Logic

High Confidence (Auto-Suggest)

Patterns that almost always need RLM:

1. Quantifiers: "all", "every", "entire", "whole", "throughout"
2. Scope words: "codebase", "repository", "project-wide"
3. Recursive terms: "recursively", "nested", "hierarchical", "tree"
4. Batch terms: "batch", "bulk", "mass", "apply to multiple"

Heuristics:

• User mentions directory paths (src/, lib/, test/)
• User wants aggregated output ("list all", "summarize", "generate report")
• Task involves file count estimation >20 files
• User explicitly says "this might be a lot" or "there are many files"

Medium Confidence (Suggest with Alternatives)

Patterns that might need RLM:

1. User asks about "multiple files" without quantity
2. User wants to "find patterns" without specifying scope
3. Task could be done with grep but user phrases it as analysis

In these cases: Ask user to clarify scope before recommending RLM

Low Confidence (Don't Suggest)

Patterns that DON'T need RLM:

1. Single file operations: "analyze this file", "refactor login.ts"
2. Specific file list: "check auth.ts, user.ts, and session.ts"
3. Interactive exploration: "show me the auth module"
4. Already scoped: "in this directory" (with small directory)

Decomposition Strategies

When RLM is appropriate, suggest the right strategy:

Strategy 1: Recursive Query (rlm-query)

Use when: User wants to find, list, or aggregate information

Example triggers:

• "find all functions that use deprecated API"
• "list all files missing tests"
• "identify all TODO comments"
• "show me all error handling patterns"

Suggested command:

/rlm-query "{context-source}" "{query}" --depth {N}

The first positional argument is the context source — a single file path or glob pattern. The second is the sub-prompt for the spawned sub-agent.

Example:

User: "find all TODO comments across the entire codebase"

Decomposition:
  Context source: "**/*.{js,ts,jsx,tsx}" (all code files)
  Query: "Extract TODO comments with file:line locations"

Suggested: /rlm-query "**/*.{js,ts,jsx,tsx}" "Extract TODO comments with file:line locations"

Strategy 2: Batch Processing (rlm-batch)

Use when: User wants to transform, update, or generate for multiple files

Example triggers:

• "update every component to use new prop types"
• "add JSDoc comments to all functions"
• "refactor all API calls to use new client"
• "generate tests for each module"

Suggested command:

/rlm-batch "{glob-pattern}" "{operation}" --max-parallel {N}

The first positional argument is the glob pattern that selects target files. The second is the operation applied to each file (use {file} as the placeholder for the current file path).

Example:

User: "add TypeScript types to every JavaScript file in src/"

Decomposition:
  Glob pattern: "src/**/*.js"
  Operation: "Add TypeScript type annotations to {file}"
  Max parallel: 4 (concurrent workers)

Suggested: /rlm-batch "src/**/*.js" "Add TypeScript type annotations to {file}" --max-parallel 4

Strategy 3: Hierarchical Summary (rlm-batch with summarize aggregation)

Use when: User wants to understand large-scale structure or relationships

Example triggers:

• "summarize the entire repository structure"
• "explain the architecture of this codebase"
• "show me the dependency tree"
• "what are the main modules?"

Suggested command:

/rlm-batch "{glob-pattern}" "Summarize {file} for repository structure analysis" --aggregate summarize --max-parallel {N}

Pick a glob pattern that matches your repository layout. Common patterns:

• **/README.md — works for monolith and monorepo layouts (use a .gitignore-aware glob to avoid node_modules/)
• apps/*/README.md — multi-app monorepos
• packages/*/README.md — workspace-style monorepos
• src/*/index.{ts,js} — top-level module entry points

Example:

User: "summarize the whole repository so I can understand the architecture"

Decomposition:
  Glob pattern: "**/README.md" (adapt to your layout)
  Operation: "Summarize {file} for architecture overview"
  Max parallel: 3
  Aggregate: summarize (collapse all sub-summaries into one overview)

Suggested: /rlm-batch "**/README.md" "Summarize {file} for architecture overview" --aggregate summarize --max-parallel 3

Response Templates

When RLM is Clearly Needed

This request involves processing {N estimated} files, which exceeds comfortable
context window usage.

I recommend using RLM (Recursive Language Model) processing:

**Suggested approach:**
{command}

This will:
1. Decompose the task into manageable chunks
2. Process files independently (avoiding context overflow)
3. Aggregate results into a coherent summary

Would you like me to proceed with this RLM approach, or would you prefer a
different strategy?

When Scope is Unclear

This could involve processing many files. To choose the right approach:

1. How many files are we talking about?
   - A few (1-5): I can handle directly
   - Several (5-20): Borderline, depends on size
   - Many (20+): RLM processing recommended

2. What's the scope?
   - Specific directory: {suggest path}
   - Whole repository: Definitely use RLM
   - Filtered by pattern: {suggest glob pattern}

Please clarify and I'll recommend the best approach.

When User Insists on Direct Processing (Warning)

I can attempt to load {estimated files} directly, but I should warn you:

⚠️ Risks:
- Context window overflow (may truncate output)
- Degraded quality (too much information to process well)
- Slow response time
- Possible incomplete results

**Recommended**: Use RLM processing instead via:
{command}

Do you want to proceed with direct loading anyway, or use the recommended
RLM approach?

Parameter Extraction

Context Source Construction

The context source is the first positional argument — a single file path or glob pattern. Construct it from explicit and implicit signals.

From explicit mention:

• "in src/" → src/**/*
• "under lib/components/" → lib/components/**/*
• "the test directory" → test/**/*

From implicit context:

• No mention → **/* (whole repo)
• "the codebase" → **/*
• "source files" → src/**/* (if src/ exists)

File Type Filters

Combine the directory scope with a type filter to narrow the glob.

From file type mention:

• "TypeScript files" → append *.ts
• "React components" → append *.{jsx,tsx}
• "test files" → append *.test.{js,ts}
• "markdown docs" → append *.md

From explicit pattern:

• "files matching *.config.js" → use **/*.config.js

Default:

• No mention → leave the context source broad (**/*)

Depth Extraction

From explicit mention:

• "top-level only" → --depth 1
• "two levels deep" → --depth 2
• "recursively" → omit (use default)

From implicit context:

• Summary request → --depth 3 (reasonable overview)
• Search request → omit (exhaustive)
• Transform request → omit (all matches)

Parallelism Extraction

For batch operations (rlm-batch):

• Default: --max-parallel 4 (balanced, mid-sweet-spot)
• User mentions "fast" → --max-parallel 7 (upper bound; see context-budget rule)
• User mentions "careful" → --max-parallel 2 (conservative)

When AIWG_CONTEXT_WINDOW is declared in the project context, the parallel cap is bounded by the context-budget rule. See @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/context-budget.md.

Clarification Prompts

If Query is Ambiguous

To set up RLM processing, I need to clarify:

1. **Scope**: Which directories?
   - [ ] Entire repository (.)
   - [ ] Specific directory: _______
   - [ ] Multiple directories: _______

2. **Files**: Which file types?
   - [ ] All files
   - [ ] Code files only (*.js, *.ts, etc.)
   - [ ] Specific pattern: _______

3. **Operation**: What should I do with each file?
   - [ ] Extract information (use rlm-query)
   - [ ] Transform/update (use rlm-batch)
   - [ ] Summarize structure (use rlm-batch with summarize aggregation)

Please provide these details.

If Scope Seems Too Large

This request would process approximately {N estimated} files.

**Options:**

1. **Narrow the scope** (recommended):
   - Specific directory: {suggest path}
   - File type filter: {suggest pattern}
   - Depth limit: {suggest depth}

2. **Proceed with full scope** using RLM:
   - Command: {command}
   - Estimated time: {estimate}
   - This will process in chunks to avoid overflow

3. **Sample first**:
   - Process a subset to verify approach
   - Then expand to full scope

Which option do you prefer?

Invocation Examples

Example 1: Find Pattern Across Codebase

User: "find all instances of console.log across the entire project"

Detection:

• Trigger: "all instances", "across the entire project"
• Strategy: rlm-query (finding information)

Extraction:

• Context source: "**/*.{js,ts,jsx,tsx}" (JavaScript/TypeScript files)
• Query: "Find all console.log statements"

Response:

This requires searching across the entire codebase. I'll use RLM processing:

/rlm-query "**/*.{js,ts,jsx,tsx}" "Find all console.log statements with file and line number"

This will:
1. Recursively scan all JavaScript/TypeScript files
2. Extract console.log locations
3. Aggregate results into a summary report

Proceeding...

Example 2: Batch Update

User: "update every React component to use the new useAuth hook instead of the old AuthContext"

Detection:

• Trigger: "update every", "React component"
• Strategy: rlm-batch (transformation)

Extraction:

• Glob pattern: "src/**/*.{jsx,tsx}" (React components)
• Operation: "Replace AuthContext with useAuth hook in {file}"
• Max parallel: 4 (default)

Response:

This is a batch refactoring task that will affect multiple components. Using RLM:

/rlm-batch "src/**/*.{jsx,tsx}" "Replace AuthContext with useAuth hook in {file}" --max-parallel 4

This will:
1. Identify all React components using AuthContext
2. Refactor each to use useAuth hook
3. Process 4 files concurrently for efficiency
4. Verify changes compile before proceeding to next

Proceeding with batch operation...

Example 3: Repository Summary

User: "summarize the whole repository structure so I can understand what this project does"

Detection:

• Trigger: "summarize the whole repository"
• Strategy: rlm-batch with summarize aggregation (hierarchical understanding)

Extraction:

• Glob pattern: "**/README.md" (works across layouts; substitute apps/*/README.md or packages/*/README.md for monorepos)
• Operation: "Summarize {file} for architecture overview"
• Max parallel: 3
• Aggregate: summarize

Response:

I'll create a hierarchical summary of the repository using RLM batch aggregation:

/rlm-batch "**/README.md" "Summarize {file} for architecture overview" --aggregate summarize --max-parallel 3

This will:
1. Summarize each README independently (sub-agent per file)
2. Aggregate the summaries into one overview
3. Preserve chunked processing for large repositories
4. Generate a concise architecture summary

Proceeding...

Example 4: Ambiguous Scope (Clarification Needed)

User: "check for missing error handling"

Detection:

• No scope quantifiers ("all", "every", "entire")
• Could be single file or entire codebase

Response:

I can check for missing error handling. To choose the right approach:

**Scope unclear**:
1. Current file only? (I can do this directly)
2. Specific module/directory? (Please specify path)
3. Entire codebase? (I'll use RLM processing)

**If entire codebase, I recommend:**
/rlm-query "**/*.{js,ts}" "Identify functions missing try-catch or error handling"

Which scope did you have in mind?

Integration Notes

• Priority: Medium (yields to agent-loop for explicit iteration requests)
• Exclusivity: Partial (suggest RLM, but user can override)
• Confirmation: Always confirm strategy before invoking RLM commands
• Fallback: If user rejects RLM, warn about context limits but proceed if insisted

Model Selection Guidance

Per REF-089 Appendix B (GRADE: LOW, peer-review pending) — RLM relies on the root agent emitting code, so non-coding-capable models underperform.

When suggesting a strategy, also recommend the model:

| Sub-prompt complexity | Recommended sub-agent model | |---|---| | Simple extraction (count, list, yes/no) | --model haiku | | Moderate analysis (summarize, classify, code review) | --model sonnet (default) | | Complex reasoning (architectural review, multi-step inference) | --model opus |

The orchestrating agent (the one invoking /rlm-query or /rlm-batch) should itself be coding-capable — sonnet or opus, never haiku — because it must emit dispatch code, parse sub-agent results, and aggregate. Output token limits below 4k cap orchestrator effectiveness.

Performance Heuristics

File Count Estimation

Quick heuristics for estimating whether RLM is needed:

| Directory | Typical File Count | RLM Recommended? | |-----------|-------------------|------------------| | src/ (small project) | 10-50 | Maybe (depends on size) | | src/ (medium project) | 50-200 | Yes | | src/ (large project) | 200+ | Definitely | | node_modules/ | 10,000+ | Always (if user really wants this) | | test/ | Usually ~50-100 | Probably | | Single directory | <10 | No | | Single directory | 10-30 | Maybe | | Single directory | 30+ | Yes |

Context Window Budgeting

Rule of thumb: If estimated total file size exceeds 50% of context window, use RLM.

Estimates:

• TypeScript file: ~200 lines avg = ~8,000 tokens
• Test file: ~100 lines avg = ~4,000 tokens
• Config file: ~50 lines avg = ~2,000 tokens

Context windows:

• Claude Opus 4.6: 200k tokens → Safe limit ~100k tokens → ~12 large TS files
• GPT-5.3-Codex: 128k tokens → Safe limit ~64k tokens → ~8 large TS files

Related

• /rlm-query command — recursive information extraction (positional: context-source, sub-prompt)
• /rlm-batch command — parallel batch processing (positional: glob-pattern, operation; supports --aggregate summarize for hierarchical summary)
• @$AIWG_ROOT/agentic/code/addons/rlm/schemas/rlm-config.yaml - RLM configuration schema
• @$AIWG_ROOT/agentic/code/addons/rlm/docs/rlm-architecture.md - RLM system design
• @.aiwg/research/findings/REF-087-recursive-decomposition.md - Decomposition research

Version History

• 1.1.0: Aligned command examples with shipped positional command surface; replaced nonexistent rlm-summarize with rlm-batch --aggregate summarize; renamed --parallel to --max-parallel; generalized Strategy 3 example for monolith and monorepo layouts (Gitea #1191, #1193, #1194; tracks upstream PR #103)
• 1.0.0: Initial implementation for RLM mode detection and routing

References

• @$AIWG_ROOT/agentic/code/addons/rlm/README.md — RLM addon overview and architecture
• @$AIWG_ROOT/agentic/code/addons/rlm/schemas/rlm-config.yaml — RLM configuration schema
• @$AIWG_ROOT/agentic/code/addons/rlm/docs/rlm-architecture.md — RLM system design and decomposition strategy
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/subagent-scoping.md — Subagent scoping and context budget rules
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/context-budget.md — Context window budgeting for parallel subagents
• @$AIWG_ROOT/docs/cli-reference.md — CLI reference for rlm commands