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 (findbyname, grepsearch). - [ ] Analyzer: Understand HOW code works (viewfile). - [ ] 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

---
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 findbyname to act as codebase-locator.
• Use view_file to act as codebase-analyzer.
• Use grep_search to act as codebase-pattern-finder.