research-phase

name	research-phase
description	This skill should be used when mapping or researching a codebase to understand its structure, patterns, and architecture. Use when the user asks to "map the codebase", "research how X works", "find all Y patterns", or needs to understand code organization. Produces factual structural maps in .artifacts/research/—no suggestions, no recommendations, just what exists. Uses ast-grep for structural pattern matching.
writes-to	.artifacts/research/
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep","Agent"]
hard-guards	["Facts only - no recommendations or implementation advice","Store research output in .artifacts/research/","Include exact file paths and line numbers where applicable","Do not modify source code while researching"]

Research Phase

Map and document codebase structure using structural analysis. This skill produces factual maps only—no suggestions, no recommendations, no opinions. Document what exists, where it lives, and how it connects.

Core Principle

Map, don't suggest. The output is a structural map that another developer (or Claude instance) can use to navigate the codebase. Include:

• File paths with line numbers
• Pattern locations
• Dependency relationships
• Symbol definitions

Exclude:

• Improvement suggestions
• Refactoring recommendations
• "Should" or "could" statements
• Opinions about code quality

Available Scripts

scripts/ast-scan.sh - Structural Pattern Scanner

Find code patterns using ast-grep.

# Scan for all function definitions
scripts/ast-scan.sh functions src/

# Find all class definitions
scripts/ast-scan.sh classes

# Find all exports
scripts/ast-scan.sh exports lib/

# Find API routes
scripts/ast-scan.sh routes

# Available patterns: functions, classes, exports, imports, types, components, routes, handlers, all

scripts/structure-map.sh - Directory Tree

Generate filtered directory structure.

# Basic tree (auto-filters node_modules, .git, etc.)
scripts/structure-map.sh ./

# Limit depth
scripts/structure-map.sh ./ --depth 3

# Code files only
scripts/structure-map.sh src/ --code-only

# Include file counts
scripts/structure-map.sh ./ --with-stats

scripts/symbol-index.sh - Public Symbol Index

Extract all exported/public symbols.

# Index all exports
scripts/symbol-index.sh src/

# Shows: exported functions, classes, types, interfaces, constants

scripts/dependency-graph.sh - Import Tracer

Map dependency relationships.

# Show all imports
scripts/dependency-graph.sh src/

# Trace specific file's dependencies
scripts/dependency-graph.sh ./ --file src/core/auth.ts

# Shows: what it imports + what imports it

Research Workflow

Step 1: Deploy 3 Research Tasks in Parallel

If subagents are available: Spawn exactly 3 Task research tasks in parallel for comprehensive coverage.

Deploy these tasks simultaneously in a single message:

1. codebase-locator - Find WHERE files and components live

   • Prompt: "Locate all files related to [topic]. Find directory structure, entry points, and related modules."

2. codebase-analyzer - Understand HOW specific code works

   • Prompt: "Analyze the implementation of [component]. Map function signatures, class hierarchies, and data flow."

3. context-synthesis - Connect findings across components

   • Prompt: "Find connections between [area A] and [area B]. Trace dependencies and shared patterns."

YOU MUST DEPLOY ALL 3 TASKS IN A SINGLE MESSAGE
DO NOT DEPLOY SEQUENTIALLY - USE PARALLEL TASK CALLS

If subagents are NOT available: Execute the workflow in order — locator first, then analyzer, then synthesis.

Step 2: Run Scripts for Structural Analysis

While waiting for agents, run ast-grep scripts:

scripts/structure-map.sh ./ --with-stats
scripts/ast-scan.sh all src/
scripts/symbol-index.sh src/

Step 3: Wait and Synthesize

Wait for ALL research tasks to complete, then compile findings:

• Merge agent results with script output
• Cross-reference file paths
• Identify patterns across different findings

Step 4: Document Findings

Create .artifacts/research/YYYY-MM-DD_HH-MM-SS_<topic>.md using format:

---
title: "<topic> research findings"
link: "<topic>-research"
type: research
ontological_relations:
  - relates_to: [[<related-doc>]]
tags: [research, <topic>]
uuid: "<uuid>"
created_at: "<ISO-8601 timestamp>"
---

## Structure
- Directory layout with purposes

## Key Files
- `path/file.ts:L123` → what it defines

## Patterns Found
- Pattern name: locations where it appears

## Dependencies
- Module A → imports → Module B

## Symbol Index
- Exported symbols with locations

When to Use Each Script

Need	Script
"What's the file structure?"	structure-map.sh
"Where are the functions?"	ast-scan.sh functions
"What does this module export?"	symbol-index.sh
"What depends on this file?"	dependency-graph.sh --file
"Where are the API routes?"	ast-scan.sh routes
"Find all React components"	ast-scan.sh components

Output Requirements

All research output must:

• Include exact file paths
• Include line numbers where applicable
• State only what was found (no interpretation)
• Group related findings together
• Be reproducible (another scan would find the same things)

Handoff

After writing the research document to .artifacts/research/, proceed to plan-phase if the next step is the Plan phase.