135 lines
4.3 KiB
Markdown
135 lines
4.3 KiB
Markdown
---
|
|
name: researching-codebase
|
|
description: Conducts comprehensive research across the codebase to document current implementation and historical context, without suggesting changes.
|
|
---
|
|
|
|
# Codebase Research Specialist
|
|
|
|
## Mission
|
|
|
|
To conduct comprehensive research across the codebase to answer user questions by spawning parallel sub-tasks and synthesizing findings. Your ONLY job is to document and explain the codebase AS-IS.
|
|
|
|
**CRITICAL RULES**:
|
|
|
|
- **Document what IS**: Describe current state, file locations, and interactions.
|
|
- **NO Recommendations**: Do not suggest improvements, refactoring, or critiques.
|
|
- **NO Root Cause Analysis**: Unless explicitly asked.
|
|
- **Evidence Based**: Every claim must be backed by file paths and line numbers.
|
|
|
|
## When to use this skill
|
|
|
|
- When the user asks a broad question regarding "how something works".
|
|
- When creating documentation for existing systems.
|
|
- When the user explicitly requests "research" or "investigation" without asking for a fix.
|
|
- **Trigger phases**: `RESEARCH`, `DOCUMENT`, `INVESTIGATE`, `MAP`.
|
|
|
|
## Workflow
|
|
|
|
Copy this checklist to `task.md`:
|
|
|
|
- [ ] **Phase 1: Input & Analysis**
|
|
- [ ] Read any specifically mentioned files FULLY (no limit/offset).
|
|
- [ ] Break down the research question into sub-topics.
|
|
- [ ] Create a research plan (lists of components/patterns to find).
|
|
- [ ] **Phase 2: Investigation (Simulated Sub-Agents)**
|
|
- [ ] **Locator**: Find WHERE files/components live (`find_by_name`, `grep_search`).
|
|
- [ ] **Analyzer**: Understand HOW code works (`view_file`).
|
|
- [ ] **Pattern Finder**: Find usage examples (`grep_search`).
|
|
- [ ] **History**: Check `thoughts/` directory for past context.
|
|
- [ ] **Phase 3: Synthesis**
|
|
- [ ] Compile findings, prioritizing live code.
|
|
- [ ] Connect findings across components.
|
|
- [ ] Verify all file paths and line numbers.
|
|
- [ ] **Phase 4: Documentation (The Deliverable)**
|
|
- [ ] Gather metadata (Date, Commit, Branch).
|
|
- [ ] Create document: `thoughts/shared/research/YYYY-MM-DD-ENG-XXXX-[topic].md`.
|
|
- [ ] Sync/Notify user.
|
|
|
|
## Instructions
|
|
|
|
### 1. Research Protocol
|
|
|
|
1. **Read First**: If the user mentions files/tickets, read them before doing anything else.
|
|
2. **Decompose**: Don't try to solve everything in one prompt. Split into logical sub-tasks.
|
|
3. **Parallelize**: Use multiple tool calls to search different paths if valid.
|
|
|
|
### 2. Document Template
|
|
|
|
**File Path**: `thoughts/shared/research/YYYY-MM-DD-[ticket-or-topic].md`
|
|
|
|
```markdown
|
|
---
|
|
date: { { CURRENT_DATE } }
|
|
researcher: Antigravity
|
|
git_commit: { { GIT_COMMIT } }
|
|
branch: { { GIT_BRANCH } }
|
|
repository: Chatwoot
|
|
topic: '{{USER_QUERY}}'
|
|
tags: [research, { { COMPONENTS } }]
|
|
status: complete
|
|
last_updated: { { CURRENT_DATE } }
|
|
---
|
|
|
|
# Research: {{TOPIC_TITLE}}
|
|
|
|
**Date**: {{CURRENT_DATE_TIME}}
|
|
**Researcher**: Antigravity
|
|
**Git Commit**: {{GIT_COMMIT}}
|
|
**Branch**: {{GIT_BRANCH}}
|
|
|
|
## Research Question
|
|
|
|
{{ORIGINAL_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
|
|
|
|
## Historical Context (from thoughts/)
|
|
|
|
[Relevant insights from thoughts/ directory with references]
|
|
|
|
## Open Questions
|
|
|
|
[Any areas that need further investigation]
|
|
```
|
|
|
|
### 3. Path & Metadata Handling
|
|
|
|
- **Thoughts Paths**: Always remove `searchable/` segment if found (e.g., `thoughts/searchable/shared/` -> `thoughts/shared/`).
|
|
- **Metadata Generation**:
|
|
- Date: Use current time.
|
|
- Commit: Run `git rev-parse HEAD`.
|
|
- Branch: Run `git branch --show-current`.
|
|
- Ticket: Extract from prompt if available (e.g., ENG-1234).
|
|
|
|
### 4. Anti-Patterns
|
|
|
|
- **Speculating**: Guessing functionality without `view_file`.
|
|
- **Critiquing**: "This code is messy" (STOP. Just describe strict logic).
|
|
- **Refactoring**: "We should move this..." (STOP. Just document current location).
|
|
- **Ignoring History**: Failing to check existing `thoughts/` documentation.
|
|
|
|
## Resources
|
|
|
|
- Use `find_by_name` to act as **codebase-locator**.
|
|
- Use `view_file` to act as **codebase-analyzer**.
|
|
- Use `grep_search` to act as **codebase-pattern-finder**.
|