chatwoot-develop/skills/researching-codebase/SKILL.md

name	description
researching-codebase	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

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