mirror of
https://github.com/dnlbauer/dotfiles.git
synced 2026-09-10 21:45:30 +00:00
add claude commands
This commit is contained in:
Daniel Bauer
139
dot_claude/commands/research_codebase.md
Normal file
139
dot_claude/commands/research_codebase.md
Normal file
@@ -0,0 +1,139 @@
|
||||
---
|
||||
description: Document codebase as-is
|
||||
model: opus
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
## 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 agents to research different aspects concurrently:
|
||||
- Use an agent to locate WHERE files and components live
|
||||
- Use an agent analyze and understand HOW specific code works (without critiquing it)
|
||||
- Use an agent to find examples of existing patterns (without evaluating them)
|
||||
- Use an agent for web research for external documentation and resources, but only if the user epplicitly asks for this. 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
|
||||
- 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 (both codebase and thoughts findings)
|
||||
- Prioritize live codebase findings as primary source of truth
|
||||
- Use thoughts and findings as supplementary historical context
|
||||
- Connect findings across different components
|
||||
- Include specific file paths and line numbers for reference
|
||||
- Verify all thoughts/ paths are correct (e.g., thoughts/allison/ not thoughts/shared/ for personal files)
|
||||
- Highlight patterns, connections, and architectural decisions
|
||||
- Answer the user's specific questions with concrete evidence
|
||||
|
||||
5. **Generate research document:**
|
||||
- Create a structured research document with your findings as markdown file.
|
||||
- Structure the document with YAML frontmatter followed by content:
|
||||
```markdown
|
||||
---
|
||||
repository: [Repository name]
|
||||
branch: [Current branch name]
|
||||
git_commit: [Current commit hash]
|
||||
topic: "[User's Question/Topic]"
|
||||
last_updated: [Current date in YYYY-MM-DD format]
|
||||
---
|
||||
|
||||
# [User's Question/Topic]
|
||||
|
||||
## 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]
|
||||
|
||||
## Historical Context (from thoughts/)
|
||||
[Relevant insights from thoughts/ directory with references]
|
||||
- `thoughts/shared/something.md` - Historical decision about X
|
||||
- `thoughts/local/notes.md` - Past exploration of Y
|
||||
Note: Paths exclude "searchable/" even if found there
|
||||
|
||||
## Related Research
|
||||
[Links to other research documents in thoughts/shared/research/]
|
||||
|
||||
## Open Questions
|
||||
[Any areas that need further investigation]
|
||||
```
|
||||
|
||||
6. **Present findings:**
|
||||
- Present a concise summary of findings to the user
|
||||
- Include key file references for easy navigation
|
||||
- Ask if they have follow-up questions or need clarification
|
||||
|
||||
7. **Handle follow-up questions:**
|
||||
- If the user has follow-up questions, append to the same research document
|
||||
- Spawn new sub-agents as needed for additional investigation
|
||||
- Continue updating the document until no more follow up questions are asked
|
||||
|
||||
## Important notes:
|
||||
- Always use parallel Task agents to maximize efficiency and minimize context usage
|
||||
- Always validate exsisting research documents during research. Don't rely on old documents
|
||||
- Old research documents provide historical context to supplement live findings.
|
||||
- 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
|
||||
- Keep the main agent focused on synthesis, not deep file reading
|
||||
- Have sub-agents document examples and usage patterns as they exist
|
||||
- Explore all existing research documents and documentation.
|
||||
- **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
|
||||
Reference in New Issue
Block a user