aldengolab/research-report

Research Report

Your job is to produce a purely descriptive technical map of a codebase. You are not reviewing code, suggesting improvements, or making recommendations — you are documenting what exists, where it lives, and how it connects.

Core principles

• Describe, don't evaluate. No judgements, no suggestions, no "could be improved" or "consider refactoring". Only what is.
• Be precise. Use path/to/file.py:123 references whenever pointing to specific logic.
• Stay in the codebase. No internet searches. Derive everything from the code itself.

Process

Step 1: Check for existing research document

Look for ./research/[project_name]-research.md.

• If it exists: Read it first. Use it as your baseline — only update sections that have changed or add new findings. Do not rewrite accurate sections.
• If it does not exist: Proceed to full research below.

Step 2: Identify starting point

If the user mentioned specific files, read those first and follow their imports. If no files are specified, find the main entrypoint (e.g., main.py, index.ts, app.py, server.js, __init__.py of the primary package) and use it to navigate.

Step 3: Decompose into research areas

Based on your initial read, identify 2–5 distinct research areas (e.g., data models, API layer, authentication, background jobs, config system). These should reflect the actual structure of this codebase, not a generic template.

Step 4: Spawn sub-agents in parallel

For each research area, launch a sub-agent using the Agent tool with isolation: "worktree", tasked with reading the relevant files and reporting back:

• What exists (files, classes, functions, data structures)
• How components connect to each other (imports, calls, data flow)
• Specific file:line references for key logic

Wait for all sub-agents to complete before proceeding.

Step 5: Consolidate and write

Merge findings into a single research document saved at:

./research/[project_name]-research.md

Create the research/ directory if it doesn't exist. If the document already existed, patch it in place rather than replacing it wholesale.

Output document format

# Research: [Topic]

## Research Question
[1 sentence summary of what was researched]

## Summary
[3–6 sentences of high-level findings — architecture, major patterns, key dependencies]

## Detailed Findings

### [Component 1]
- What exists, with `file:line` references
- How it connects to other components

### [Component 2]
- What exists, with `file:line` references
- How it connects to other components

[Continue for each research area]

## Open Questions
[Anything that couldn't be determined from the code alone — missing files, unclear ownership, ambiguous logic]

After saving the file, tell the user where it was written.