research

What this skill does

# Research Skill

> **Quick Ref:** Deep codebase exploration with multi-angle analysis. Output: `.agents/research/*.md`

**YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.**

**CLI dependencies:** ao (knowledge injection — optional). If ao is unavailable, skip prior knowledge search and proceed with direct codebase exploration.

## Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--auto` | off | Skip human approval gate. Used by `/rpi --auto` for fully autonomous lifecycle. |

## Execution Steps

Given `/research <topic> [--auto]`:

### Step 1: Create Output Directory
```bash
mkdir -p .agents/research
```

### Step 2: Check Prior Art

**First, search and inject existing knowledge (if ao available):**

```bash
# Pull relevant prior knowledge for this topic
ao lookup --query "<topic>" --limit 5 2>/dev/null || \
  ao search "<topic>" 2>/dev/null || \
  echo "ao not available, skipping knowledge search"
```

**Apply retrieved knowledge (mandatory when results returned):**

If ao returns relevant learnings or patterns, do NOT just load them as passive context. For each returned item:
1. Check: does this learning apply to the current research topic? (answer yes/no)
2. If yes: note how it shapes your research direction — what questions does it answer? what areas does it warn about?
3. Cross-reference prior findings against new discoveries in your research output
4. Cite applicable learnings by filename in the research document's Findings section

After applying, record each citation:
```bash
ao metrics cite "<learning-path>" --type applied 2>/dev/null || true
```

Also look for:
- Prior research on this topic or related topics
- Known patterns or anti-patterns
- Lessons learned from similar investigations

**Search ALL local knowledge locations by content (not just filename):**

Use Grep to search every knowledge directory for the topic. This catches learnings from `/post-mortem`, brainstorms, and plans — not just research artifacts.

```bash
# Search all knowledge locations by content
for dir in research learnings knowledge patterns retros plans brainstorm; do
  grep -r -l -i "<topic>" .agents/${dir}/ 2>/dev/null
done

# Search global patterns (cross-repo knowledge)
grep -r -l -i "<topic>" ~/.claude/patterns/ 2>/dev/null
```

If matches are found, read the relevant files with the Read tool before proceeding to exploration. Prior knowledge prevents redundant investigation.

### Step 2.5: Pre-Flight — Detect Spawn Backend

Before launching the explore agent, detect which backend is available:

1. Check if `spawn_agent` is available → log `"Backend: codex-sub-agents"`
2. Else check if `TeamCreate` is available → log `"Backend: claude-native-teams"`
3. Else check if `skill` tool is read-only (OpenCode) → log `"Backend: opencode-subagents"`
4. Else check if `Task` is available → log `"Backend: background-task-fallback"`
5. Else → log `"Backend: inline (no spawn available)"`

Record the selected backend — it will be included in the research output document for traceability.

**Read the matching backend reference for concrete tool call examples:**
- Shared Claude feature contract → `skills/shared/references/claude-code-latest-features.md`
- Local mirrored contract for runtime-local reads → `references/claude-code-latest-features.md`
- Codex → `references/backend-codex-subagents.md`
- Claude Native Teams → `references/backend-claude-teams.md`
- Background Tasks → `references/backend-background-tasks.md`
- Inline → `references/backend-inline.md`

### Effort and Session Hints

- Set effort to `low` for explore agents — research is breadth-first scanning, not deep reasoning.
- Use `--from-pr <url>` to scope research to a specific PR's changed files when investigating PR-related topics.

### Step 3: Launch Explore Agent

**YOU MUST DISPATCH AN EXPLORATION AGENT NOW.** Select the backend using capability detection:

#### Backend Selection (MANDATORY)

1. If `spawn_agent` is available → **Codex sub-agent**
2. Else if `TeamCreate` is available → **Claude native team** (Explore agent)
3. Else if `skill` tool is read-only (OpenCode) → **OpenCode subagent** — `task(subagent_type="explore", description="Research: <topic>", prompt="<explore prompt>")`
4. Else → **Background task fallback**

#### Exploration Prompt (all backends)

Use this prompt for whichever backend is selected. The exploration uses **iterative retrieval** (see `references/iterative-retrieval.md`): start broad, score relevance, extract new search terms from high-relevance files, and repeat for up to 3 cycles.

```
Thoroughly investigate: <topic>

Use iterative retrieval: after each discovery tier, score results 0-1 for relevance.
From files scoring 0.5+, extract new search terms (function names, imports, config keys).
Use extracted terms in subsequent tiers. Max 3 refinement cycles.

Discovery tiers (execute in order, skip if source unavailable):

Tier 1 — Code-Map (fastest, authoritative):
  Read docs/code-map/README.md → find <topic> category
  Read docs/code-map/{feature}.md → get exact paths and function names
  Skip if: no docs/code-map/ directory

Tier 2 — Semantic Search (conceptual matches):
  mcp__smart-connections-work__lookup query="<topic>" limit=10
  Skip if: MCP not connected

Tier 2.5 — Git History (recent changes and decision context):
  git log --oneline -30 -- <topic-related-paths>   # scoped to relevant paths, cap 30 lines
  git log --all --oneline --grep="<topic>" -10      # cap 10 matches
  git blame <key-file> | grep -i "<topic>" | head -20  # cap 20 lines
  Skip if: not a git repo, no relevant history, or <topic> too broad (>100 matches)
  NEVER: git log on full repo without -- path filter (same principle as Tier 3 scoping)
  NOTE: This is git commit history, not session history. For session/handoff history, use /trace.

Tier 3 — Scoped Search (keyword precision):
  Grep("<topic>", path="<specific-dir>/")   # ALWAYS scope to a directory
  Glob("<specific-dir>/**/*.py")            # ALWAYS scope to a directory
  NEVER: Grep("<topic>") or Glob("**/*.py") on full repo — causes context overload

Tier 4 — Source Code (verify from signposts):
  Read files identified by Tiers 1-3 (including git history leads from Tier 2.5)
  Use function/class names, not line numbers

Tier 5 — Prior Knowledge (may be stale):
  Search ALL .agents/ knowledge dirs by content:
    for dir in research learnings knowledge patterns retros plans brainstorm; do
      grep -r -l -i "<topic>" .agents/${dir}/ 2>/dev/null
    done
  Read matched files. Cross-check findings against current source.

Tier 6 — External Docs (last resort):
  WebSearch for external APIs or standards
  Only when Tiers 1-5 are insufficient

Return a detailed report with:
- Key files found (with paths)
- How the system works
- Important patterns or conventions
- Any issues or concerns

Cite specific file:line references for all claims.
```

#### Spawn Research Agents

If your runtime supports spawning parallel subagents, spawn one or more research agents with the exploration prompt. Each agent explores independently and writes findings to `.agents/research/`.

If no multi-agent capability is available, perform the exploration **inline** in the current session using file reading, grep, and glob tools directly.

### Step 4: Validate Research Quality (mandatory in auto mode)

**For thorough research, perform quality validation:**

**Auto mode enforcement:** When `--auto` is set, quality validation is mandatory. If depth rating < 2 for any critical area (Step 4b), emit WARN and log to `.agents/research/quality-warning.md`. In interactive mode, this step remains optional.

#### 4a. Coverage Validation
Check: Did we look everywhere we should? Any unexplored areas?
- List directories/files explored
- Identify gaps in coverage
- Note areas that need deeper investigation

#### 4b. Depth Validation
Check: Do we UNDERSTAND the critical parts? HOW and WHY, not just WHAT?
- Rate depth (0-4) for each critical area
- Flag are