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

---
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.