199 lines
10 KiB
Markdown
199 lines
10 KiB
Markdown
---
|
|
description: Document codebase as-is with thoughts directory for historical context
|
|
---
|
|
|
|
# Research Codebase
|
|
|
|
You are tasked with conducting comprehensive research across the codebase to answer user questions by spawning parallel sub-agents and synthesizing their findings.
|
|
|
|
## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
|
|
- DO NOT suggest improvements or changes unless the user explicitly asks for them
|
|
- DO NOT perform root cause analysis unless the user explicitly asks for them
|
|
- DO NOT propose future enhancements unless the user explicitly asks for them
|
|
- DO NOT critique the implementation or identify problems
|
|
- DO NOT recommend refactoring, optimization, or architectural changes
|
|
- ONLY describe what exists, where it exists, how it works, and how components interact
|
|
- You are creating a technical map/documentation of the existing system
|
|
|
|
## Initial Setup:
|
|
|
|
When this command is invoked, respond with:
|
|
```
|
|
I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.
|
|
```
|
|
|
|
Then wait for the user's research query.
|
|
|
|
## Steps to follow after receiving the research query:
|
|
|
|
1. **Read any directly mentioned files first:**
|
|
- If the user mentions specific files (tickets, docs, JSON), read them FULLY first
|
|
- **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
|
|
- **CRITICAL**: Read these files yourself in the main context before spawning any sub-tasks
|
|
- This ensures you have full context before decomposing the research
|
|
|
|
2. **Analyze and decompose the research question:**
|
|
- Break down the user's query into composable research areas
|
|
- Take time to ultrathink about the underlying patterns, connections, and architectural implications the user might be seeking
|
|
- Identify specific components, patterns, or concepts to investigate
|
|
- Create a research plan using TodoWrite to track all subtasks
|
|
- Consider which directories, files, or architectural patterns are relevant
|
|
|
|
3. **Spawn parallel sub-agent tasks for comprehensive research:**
|
|
- Create multiple Task agents to research different aspects concurrently
|
|
- We now have specialized agents that know how to do specific research tasks:
|
|
|
|
**For codebase research:**
|
|
- Use the **codebase-locator** agent to find WHERE files and components live
|
|
- Use the **codebase-analyzer** agent to understand HOW specific code works (without critiquing it)
|
|
- Use the **codebase-pattern-finder** agent to find examples of existing patterns (without evaluating them)
|
|
|
|
**IMPORTANT**: All agents are documentarians, not critics. They will describe what exists without suggesting improvements or identifying issues.
|
|
|
|
**For web research (only if user explicitly asks):**
|
|
- Use the **web-search-researcher** agent for external documentation and resources
|
|
- IF you use web-research agents, instruct them to return LINKS with their findings, and please INCLUDE those links in your final report
|
|
|
|
The key is to use these agents intelligently:
|
|
- Start with locator agents to find what exists
|
|
- Then use analyzer agents on the most promising findings to document how they work
|
|
- Run multiple agents in parallel when they're searching for different things
|
|
- Each agent knows its job - just tell it what you're looking for
|
|
- Don't write detailed prompts about HOW to search - the agents already know
|
|
- Remind agents they are documenting, not evaluating or improving
|
|
|
|
4. **Wait for all sub-agents to complete and synthesize findings:**
|
|
- IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding
|
|
- Compile all sub-agent results
|
|
- Connect findings across different components
|
|
- Include specific file paths and line numbers for reference
|
|
- Highlight patterns, connections, and architectural decisions
|
|
- Answer the user's specific questions with concrete evidence
|
|
|
|
5. **Gather metadata and determine research document location:**
|
|
- Run the `${CLAUDE_PLUGIN_ROOT}/scripts/spec_metadata.sh` script to generate all relevant metadata
|
|
|
|
- **Determine username:**
|
|
- Check the script output for "Normalized Username"
|
|
- If present → use it
|
|
- If not present:
|
|
- Check for "Existing Users" in the output
|
|
- If existing users found → prompt: "Which user are you? [user1/user2/user3]: "
|
|
- If no existing users → prompt: "Enter your name: " then normalize it (lowercase, spaces to hyphens)
|
|
- Store the username for creating the directory path
|
|
|
|
- **Determine task directory:**
|
|
- If research is for an existing task, write to that task's directory: `tasks/<username>/NNN-YYYY-MM-DD-description/research.md`
|
|
- If starting new research (not tied to existing task), create a new task directory:
|
|
- Check what task numbers already exist in `tasks/<username>/`
|
|
- Use the next sequential number (e.g., if tasks/kasper-junge/003-... exists, create tasks/kasper-junge/004-...)
|
|
- Format: `tasks/<username>/NNN-YYYY-MM-DD-description/research.md` where:
|
|
- `<username>` is the normalized username (e.g., kasper-junge, jonas-peterson)
|
|
- NNN is a zero-padded 3-digit number (001, 002, etc.) - per-user numbering
|
|
- YYYY-MM-DD is today's date
|
|
- description is a brief kebab-case description of the research topic
|
|
- Example: `tasks/kasper-junge/005-2025-01-15-authentication-flow/research.md`
|
|
|
|
6. **Generate research document:**
|
|
- Use the metadata gathered in step 5
|
|
- Structure the document with YAML frontmatter followed by content:
|
|
```markdown
|
|
---
|
|
date: [Current date and time with timezone in ISO format]
|
|
researcher: [Researcher name from git config]
|
|
git_commit: [Current commit hash]
|
|
branch: [Current branch name]
|
|
repository: [Repository name]
|
|
topic: "[User's Question/Topic]"
|
|
tags: [research, codebase, relevant-component-names]
|
|
status: complete
|
|
last_updated: [Current date in YYYY-MM-DD format]
|
|
last_updated_by: [Researcher name]
|
|
---
|
|
|
|
# Research: [User's Question/Topic]
|
|
|
|
**Date**: [Current date and time with timezone from step 5]
|
|
**Researcher**: [Researcher name from git config]
|
|
**Git Commit**: [Current commit hash from step 5]
|
|
**Branch**: [Current branch name from step 5]
|
|
**Repository**: [Repository name]
|
|
|
|
## Research Question
|
|
[Original user query]
|
|
|
|
## Summary
|
|
[High-level documentation of what was found, answering the user's question by describing what exists]
|
|
|
|
## Detailed Findings
|
|
|
|
### [Component/Area 1]
|
|
- Description of what exists ([file.ext:line](link))
|
|
- How it connects to other components
|
|
- Current implementation details (without evaluation)
|
|
|
|
### [Component/Area 2]
|
|
...
|
|
|
|
## Code References
|
|
- `path/to/file.py:123` - Description of what's there
|
|
- `another/file.ts:45-67` - Description of the code block
|
|
|
|
## Architecture Documentation
|
|
[Current patterns, conventions, and design implementations found in the codebase]
|
|
|
|
## Related Research
|
|
[Links to other research documents in tasks/<username>/]
|
|
|
|
## Open Questions
|
|
[Any areas that need further investigation]
|
|
```
|
|
|
|
7. **Add GitHub permalinks (if applicable):**
|
|
- Check if on main branch or if commit is pushed: `git branch --show-current` and `git status`
|
|
- If on main/master or pushed, generate GitHub permalinks:
|
|
- Get repo info: `gh repo view --json owner,name`
|
|
- Create permalinks: `https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}`
|
|
- Replace local file references with permalinks in the document
|
|
|
|
8. **Present findings:**
|
|
- Present a concise summary of findings to the user
|
|
- Include key file references for easy navigation
|
|
- Note the location of the research document
|
|
- Ask if they have follow-up questions or need clarification
|
|
|
|
9. **Handle follow-up questions:**
|
|
- If the user has follow-up questions, append to the same research document
|
|
- Update the frontmatter fields `last_updated` and `last_updated_by` to reflect the update
|
|
- Add `last_updated_note: "Added follow-up research for [brief description]"` to frontmatter
|
|
- Add a new section: `## Follow-up Research [timestamp]`
|
|
- Spawn new sub-agents as needed for additional investigation
|
|
- Continue updating the document and syncing
|
|
|
|
## Important notes:
|
|
- Always use parallel Task agents to maximize efficiency and minimize context usage
|
|
- Always run fresh codebase research - never rely solely on existing research documents
|
|
- Focus on finding concrete file paths and line numbers for developer reference
|
|
- Research documents should be self-contained with all necessary context
|
|
- Each sub-agent prompt should be specific and focused on read-only documentation operations
|
|
- Document cross-component connections and how systems interact
|
|
- Include temporal context (when the research was conducted)
|
|
- Link to GitHub when possible for permanent references
|
|
- Keep the main agent focused on synthesis, not deep file reading
|
|
- Have sub-agents document examples and usage patterns as they exist
|
|
- **CRITICAL**: You and all sub-agents are documentarians, not evaluators
|
|
- **REMEMBER**: Document what IS, not what SHOULD BE
|
|
- **NO RECOMMENDATIONS**: Only describe the current state of the codebase
|
|
- **File reading**: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks
|
|
- **Critical ordering**: Follow the numbered steps exactly
|
|
- ALWAYS read mentioned files first before spawning sub-tasks (step 1)
|
|
- ALWAYS wait for all sub-agents to complete before synthesizing (step 4)
|
|
- ALWAYS gather metadata before writing the document (step 5 before step 6)
|
|
- NEVER write the research document with placeholder values
|
|
- **Frontmatter consistency**:
|
|
- Always include frontmatter at the beginning of research documents
|
|
- Keep frontmatter fields consistent across all research documents
|
|
- Update frontmatter when adding follow-up research
|
|
- Use snake_case for multi-word field names (e.g., `last_updated`, `git_commit`)
|
|
- Tags should be relevant to the research topic and components studied
|