researching-code

name	researching-code
description	Investigates codebase to find minimum context needed for planning. Use when starting a new feature, analyzing unfamiliar code, or preparing for implementation. Identifies files to touch, patterns to follow, and risks to mitigate.
model	opus
metadata	{"version":"2.0.0","category":"workflow-automation"}

Code Research

Mindset: Understand just enough to plan effectively. Skip comprehensive documentation.

Goal

Find the minimum context needed to answer:

1. What files will this touch?
2. What patterns should we follow?
3. What are the main risks?

Instructions

Step 0: Code Intelligence Pipeline

Load context through a multi-level pipeline: structural overview → dependency graph → targeted search → reranking → context pack assembly.

Step 0a — Repo Map + Symbol Index (Level 1):

Check if 01_DISCOVERY.md exists for this issue (in .antigravity/planning/{issue-name}/) and contains ## Repository Map and ## Symbol Index sections.

• If both exist: Read them. Use the map to identify relevant directories/files and the symbol index to identify relevant symbols (classes, functions, types) by name.
• If only the map exists: Use it without the symbol index — existing Level 1 behavior.
• If no discovery doc exists (user jumped straight to /research): Generate a quick repo map on-the-fly using Glob + Grep:
  1. Run Glob for source files (exclude node_modules/, vendor/, dist/, build/, .git/, *.lock, *.min.js)
  2. Auto-detect the primary language from file extensions
  3. Run Grep with the appropriate language pattern to extract top-level symbols
  4. Mentally note the repo structure and candidate files

From the map + index, identify 5-15 candidate files most relevant to the feature.

Small-repo bypass: If the repo has < 50 source files, skip Steps 0b and 0d. Go directly from Level 1 → Level 2 → Step 0e. The repo map provides sufficient guidance for small codebases.

Step 0b — Build Dependency Graph (repos ≥ 50 files):

For each candidate file from Step 0a, run Grep to find import/export statements. Build a mental adjacency list: file → [imports, imported-by, tested-by].

Language	Import Pattern
JS/TS	^import .+ from ['"](.+)['"] and require\(['"](.+)['"]\)
Python	^import (\S+) and ^from (\S+) import
Go	"([^"]+)" inside import blocks
PHP/Rust	^use (.+);
Generic	^import|^require|^use|^from .+ import

Also find test files via naming conventions: {name}.test.*, {name}.spec.*, test_{name}.*, {name}_test.*, __tests__/{name}.*.

Graceful degradation: If import patterns don't match the language, skip this step and proceed to Level 2.

Step 0c — Targeted Search (Level 2):

• If search_code MCP is available: Call search_code with the project path and a natural language description of the feature. Cross-reference results with your candidate list from the map.
• If MCP is not available: Use Grep for feature-related terms scoped to the candidate directories identified from the map, then Read the top matches.

Step 0d — Rerank Results (repos ≥ 50 files, >5 candidates):

If Level 2 returned > 5 candidate files, apply reranking. Otherwise, use all candidates directly.

Score each candidate on 3 factors:

• Keyword overlap (40%): Count task-description keywords found in file path + symbol names. Score 0-3.
• Dependency proximity (35%): 3 = directly imported by seed file, 2 = imports a seed, 1 = shares a dependency, 0 = unrelated. Requires Step 0b graph.
• File-type priority (25%): source=3, test=2, config=1, doc=0.

Composite = (keyword × 0.4) + (proximity × 0.35) + (filetype × 0.25). Re-order by score, take top-8.

Graceful degradation: If no dependency graph (Step 0b was skipped), score using keyword + file-type only.

Step 0e — Assemble Context Pack:

1. Start with top-5 reranked files (or all Level 2 candidates if reranking was skipped)
2. For each seed file, check the dependency graph: add up to 2 direct imports not already in the pack
3. Add corresponding test files for seed files if they exist
4. Hard cap: ≤ 8 files total. If over, drop test files first, then lowest-scored imports
5. Read the context pack files with progressive depth:
   • Small files (< 100 lines): read entirely
   • Medium files (100-300 lines): read imports + exported symbols + relevant functions
   • Large files (> 300 lines): read only sections matching task keywords

Graceful degradation: If no dependency graph or reranking was performed (small repo), use Level 2 candidates directly as the context pack.

Step 1: Think Deeply Before Searching

Use the context pack from Step 0e as your primary reference. Think deeply about:

• What are the hidden dependencies?
• What could break if we change X?
• What's the simplest approach?

Use phrases like "think deeper", "think about edge cases" to trigger extended thinking.

Step 2: Targeted Analysis (using context pack)

The context pack from Step 0e replaces broad searching. Read the pack files and answer the three questions. Only use additional Grep if the pack doesn't cover one of them.

What files will this touch?

• Start from context pack files; trace outward only if needed

What patterns should we follow?

• Look for similar implementations among the context pack files

What are the main risks?

• Check for tests in related areas (test files may already be in the context pack)
• Look for shared utilities/dependencies (visible in the dependency graph from Step 0b)
• Identify tight coupling

Step 3: Create RESEARCH.md

Write docs/{issue_name}/RESEARCH.md with this structure:

# Research: {issue_name}

**What:** {feature_description}
**When:** {timestamp}

---

## Summary

- **Risk:** Low | Medium | High
- **Approach:** {Brief approach recommendation}
- **Effort:** Quick | Moderate | Significant

---

## What We Found

### Files to Touch
- `path/to/file.ts` - {why}

### Patterns to Follow
- `{pattern}` from `path/to/reference.ts`

### Key Dependencies
- `{package}` - existing | needed

---

## Risks

| Risk | Severity | Mitigation |
|------|----------|------------|
| {risk} | Low/Med/High | {how to address} |

---

## Open Questions

1. **{Question}?**
   - Options: {A or B}
   - Recommendation: {A because...}

Step 4: Update STATUS.md

Update docs/{issue_name}/STATUS.md to reflect research completion.

Output Format

• docs/{issue_name}/RESEARCH.md
• docs/{issue_name}/STATUS.md (updated)

Quality Check

• Used repo map + symbol index (Level 1) to identify candidate files?
• Built dependency graph for candidate files (if repo ≥ 50 files)?
• Used targeted search (Level 2) for candidate files only?
• Reranked results when > 5 candidates returned (if repo ≥ 50 files)?
• Assembled context pack (≤ 8 files) before deep analysis?
• Answered: What files to touch?
• Answered: What patterns to follow?
• Answered: What are the risks?
• RESEARCH.md created (not CODE_RESEARCH.md + RESEARCH_SUMMARY.md)
• STATUS.md updated

Common Issues

• Over-researching: Don't document the entire architecture. Don't trace full data flows. Don't create 30+ file analyses.
• Wrong artifact name: Create RESEARCH.md, not CODE_RESEARCH.md + RESEARCH_SUMMARY.md.
• Too many files: The context pack caps at 8 files. If you need more, you're over-researching.
• Ignoring the pipeline: Don't skip Level 1 and go straight to broad Grep. Follow the pipeline: map → graph → search → rerank → pack.
• Over-engineering small repos: For repos < 50 files, skip dependency graph and reranking. The map is enough.