research

Files (1)

• SKILL.md

SKILL.md (first lines)

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

## Research Query:
{{args}}

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

## Initial Setup:

When this command is invoked, respond with:
```
I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.
```
*(Note: If a query was already provided via arguments, proceed immediately to step 1 using that query.)*

## 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_file` 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 Task agents to research different aspects concurrently.
   - We now have specialized agents that know how to do specific research tasks:

   **For codebase research:**
   - Use the **@context-mapping** (or **context-mapping**) agent to find WHERE files and components live.
   - Use the **@codebase-analyzer** (or **codebase-analysis**) agent to understand HOW specific code works (without critiquing it).
   - Use the **@pattern-recognition** (or **pattern-recognition**) agent to find examples of existing patterns (without evaluating them).
   - **Mandatory**: Search `docs/adr/` for Architecture Decision Records to understand historical design rationale.

   **IMPORTANT**: All agents are documentarians, not critics. They will describe what exists without suggesting improvements or identifying issues.

   **For web research:**
   - Use the **google_web_search** tool with the **generalist** agent for external documentation and resources.
   - Use the **web_fetch** tool to extract content from specific URLs.
   - IF you use web-research agents or tools, 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 context mapping/scout agents to find what exists.
   - Then use codebase analysis agents on the most promising findings to document how they work.
   - Run multiple agents in parallel when they're searching for different things.
   - Each agent knows its job - just tell it what you're looking for.
   - Don't write detailed prompts about HOW to search - the agents already know.
   - 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.
   - Connect findings across different components.
   - Include specific file paths and line numbers for reference.
   - Highlight patterns, connections, and architectural decisions.
   - Answer the user's specific questions with concrete evidence.

5. **Gather metadata for the research document:**
   - Run `run_shell_command` to generate all relevant metadata (git hash, branch, repo name).
   - **Filename**: `plans/<feature-name>/<YYYY-MM-DD_HHMM>/03_EXTRACTION.md`
     - *Note*: If a feature context (name and timestamp) is provided, use this path. 
     - *Fallback*: For general research outside of a feature workflow, use `plans/thoughts/YYYY-MM-DD-ENG-XXXX-Research-Report.md`.
   - **UI Visibility / Artifact Mirroring**: In addition to saving the document in the workspace, run `python3 scripts/manage_dashboard.py auto-sync --plan-dir "plans/<feature-name>/<timestamp>"` (or `python3 scripts/manage_dashboard.py sync-extraction ...`) to populate Stage 3 in `visual-dashboard.html` and mirror `03_extraction.md` into the assistant's private system artifacts directory (`/home/robedwards/.gemini/antigravity-cli/brain/<conversation-id>/03_extraction.md`).

6. **Generate research document:**
   - Use the metadata gathered in step 5.
   - Structure the document with YAML frontmatter followed by content:
     ```markdown
     ---
     date: [Current date and time with timezone in ISO format]
     researcher: [Researcher name]
     git_commit: [Current commit hash]
     branch: [Current branch name]
     repository: [Repository name]
     topic: "[User's Question/Topic]"
     tags: [research, codebase, relevant-component-names]
     status: complete
     last_updated: [Current date in YYYY-MM-DD format]
     last_updated_by: [Researcher name]
     ---

     # 02 Research Report: [User's Question/Topic]

     **Date**: [Current date and time]
     **Researcher**: [Researcher name]
     **Git Commit**: [Current commit hash]
     **Branch**: [Current branch name]
     **Repository**: [Repository name]

     ## 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]

From sapientcoffee/bean-brewer, Apache-2.0.

More from sapientcoffee/bean-brewer