rlm-query

What this skill does

# RLM Query

Spawn a focused sub-agent to process a specific portion of context and return a structured result. This is the command equivalent of RLM's `llm_query()` function.

## Core Philosophy

Sub-agents receive ONLY the specified context, not the full conversation history. This prevents context overload and improves output quality by enforcing focused, single-purpose queries.

## Usage

```
/rlm-query <context-file> <sub-prompt>
/rlm-query <glob-pattern> <sub-prompt> --output result.txt
/rlm-query file.ts "extract all function names" --model haiku
/rlm-query "src/**/*.test.js" "count total assertions" --depth 2
```

## Parameters

### context-file (required)
File path or glob pattern specifying the context source.

**Valid patterns**:
- Single file: `src/auth/login.ts`
- Glob pattern: `src/**/*.test.ts`
- Multiple files: `src/auth/*.ts`

**Context loading**:
- Files matching pattern are read and provided to sub-agent
- If pattern matches multiple files, all are included
- Large file sets (>10 files) should be avoided (use filtering)

### sub-prompt (required)
The specific task for the sub-agent. Should be:
- Focused and specific (single responsibility)
- Clear output format expectation
- Self-contained (no references to parent conversation)

**Good sub-prompts**:
- "Extract all exported function names as JSON array"
- "Identify security issues and list in bullet format"
- "Count total test assertions and return as integer"
- "Summarize this function's purpose in one sentence"

**Poor sub-prompts** (avoid):
- "Analyze this" (too vague)
- "Look at this and tell me what you think" (no format)
- "Check if this relates to the earlier discussion" (references parent context)

### --model <model> (optional)
Override the default model for the sub-agent.

**Available models**:
- `opus` - Highest capability (expensive, for complex analysis)
- `sonnet` - Balanced (default for most queries)
- `haiku` - Fast and cheap (for simple extraction)

**Model selection guidance** (per REF-089 Appendix B; GRADE: LOW, peer-review pending):
- Use `haiku` for: counting, extracting simple patterns, yes/no questions
- Use `sonnet` for: summarization, moderate analysis, code review
- Use `opus` for: complex reasoning, architectural decisions, multi-step analysis

**RLM root vs sub-agent**: When `rlm-query` itself dispatches sub-calls (recursion via `--depth >1`), the *root* agent should be coding-capable (sonnet or opus). Per REF-089, "Qwen3-8B (non-coder) struggled without sufficient coding capabilities." Sub-agents performing simple extraction can safely be `haiku`; sub-agents performing analysis or synthesis should be `sonnet` or higher.

**Output token limits**: RLM root agents emit code, which can be verbose. Models with output token limits below 4k will underperform. Surface a warning when the configured model has lower limits.

### --output <file> (optional)
Save the sub-agent's response to a file instead of returning inline.

**Use cases**:
- Intermediate results in multi-stage workflows
- Large outputs that would clutter conversation
- Results that need to persist for later reference

**Behavior**:
- File is created/overwritten with sub-agent response
- Command returns path to file instead of full content
- File can be used as input to subsequent `rlm-query` calls

### --neighbors-of <id> (optional, requires aiwg index)

Resolve the context source from the artifact index's dependency graph instead of from a glob pattern. Pass an artifact ID (path or REF-XXX identifier) — the skill resolves its neighbors and dispatches the sub-prompt over them.

**Requires**: `aiwg index` capability available (built and reachable). When the index is unavailable, the skill errors with a remediation pointer.

**Resolution**:

```bash
# At depth=1 (default), maps directly to the index CLI:
aiwg index neighbors --graph <graph> --node <id> --direction <dir> --json

# At depth >1, the skill expands recursively by calling neighbors on each
# result up to <N> hops, deduplicating along the way.
```

### --direction <in|out|both> (optional, with --neighbors-of)

Restrict which side of the dependency graph to traverse. Defaults to `both`. Aligns with the `aiwg index neighbors` CLI direction flag.

- `in` — upstream (artifacts that depend on the node)
- `out` — downstream (artifacts the node depends on)
- `both` — both directions (default)

### --graph <name> (optional, with --neighbors-of)

Which dependency graph to query. Defaults to `project`. Valid values match the `aiwg index neighbors --graph` flag (e.g., `framework`, `project`, `codebase`, or a user-defined graph name).

### --no-cache (optional, #1203)

Bypass the result cache: do not read existing cache entries, but still write the result for future calls. Use to force a re-run when you suspect external state has changed in a way the cache key would not capture.

### --cache-only (optional, #1203)

Read-only audit: error out if the call would not be a cache hit. Useful to verify reproducibility before committing or to gauge what re-running would cost.

### --depth <n> (optional)

When `--neighbors-of` is set, controls graph traversal depth (default: `1`). Otherwise tracks current recursion depth (internal use).

**Purpose**:
- Prevents infinite recursion if sub-agent spawns sub-queries
- Logs depth for debugging complex query chains
- Default: 0 (top-level query)

**Recursion limit**: Maximum depth of 3 levels
- Depth 0: Parent agent
- Depth 1: First sub-agent
- Depth 2: Sub-agent's sub-agent
- Depth 3: Maximum (further nesting blocked)

## Planned Capabilities

These flags are reserved in the design but not yet implemented. Tracked in Gitea #1201.

- `--save-trajectory <path>` — Persist a structured trajectory of the dispatch + sub-agent result suitable for offline analysis or future fine-tuning. Format: JSON Lines with one entry per call. REF-089 (p. 5) reports a 28.3% performance improvement from 1,000 trajectory samples for fine-tuning RLM-specialized models. When implemented, this flag will be added to `argumentHint` and become enforceable by the canonical command surface contract test.

## Execution Flow

### Phase 1: Context Loading

**Argument resolution** — pick the context-source axis from the parsed flags:

1. **If `--neighbors-of <id>` is present** (graph-bounded; #1206):
   - Verify `aiwg index` is available. Run `aiwg index stats --json` once; on failure, error with "neighbors-of requires aiwg index — run `aiwg index build` first".
   - Resolve direct neighbors:
     ```bash
     aiwg index neighbors --graph "${graph:-project}" \
       --node "<id>" \
       --direction "${direction:-both}" \
       --json
     ```
   - If `--depth N` (N > 1): expand iteratively. For each new neighbor, run the same `aiwg index neighbors` call; deduplicate by node id; stop after N hops or when the frontier is empty.
   - Map the resolved node IDs to file paths via `aiwg index query --id <id> --json` (or use the `path` field returned by `neighbors` directly when present).
   - Treat the deduplicated path list as the context source. Skip the glob/path branch below.
   - On empty result set, error with the offending node id and a suggestion to verify it exists via `aiwg index query "<id>"`.

2. **Else if a glob pattern or single path is supplied**:
   - Resolve the glob with `find` / `glob` semantics
   - Use the matched file list as the context source

3. **Read** all resolved files into memory.
4. **Cache lookup** (#1203, unless `--no-cache`):
   - Compute content hash for each resolved file (or pull from `aiwg index query --id <id> --json`)
   - Compose `CacheKey = { inputs[], query, subPrompt, model, aggregateStrategy }` and call `computeHash(key)` (`src/rlm/cache/hash.ts`)
   - If `aiwg rlm-cache` reports a hit (`get(root, hash)` succeeds): return the cached `result.json` immediately and log `cache_hit=true` in the cost report. Skip dispatch.
   - If miss and `--cache-only`: error with the hash and exit non-zero.
   - Otherwise: conti