Researching

Working Agreement

1. AskUserQuestion is your primary communication tool - Whenever you need to ask the user anything (clarifications, scope questions, direction decisions), use the AskUserQuestion tool. Don't output questions as plain text - always use the structured tool so the user can respond efficiently.
2. Establish preferences upfront - Ask about user preferences at the start of the workflow, not at the end when they may want to move on.
3. Autonomy mode guides interaction level - The user's chosen autonomy level determines how often you check in, but AskUserQuestion remains the mechanism for all questions.

User Preferences

file-review

file-review:file-review

When to Use

• User invokes

  /research

  command
• Another skill references

  **REQUIRED SUB-SKILL:** Use desplega:researching

• User asks to document or understand a codebase area

Autonomy Mode

Critical Constraints

• DO NOT suggest improvements or changes unless explicitly asked
• DO NOT perform root cause analysis unless explicitly asked
• DO NOT propose future enhancements unless explicitly asked
• 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
• You are creating a technical map/documentation of the existing system

Research Process

Before Starting

Steps

1. Read any directly mentioned files first:
   • If the user mentions specific files, read them FULLY first
   • IMPORTANT: Use the Read tool WITHOUT limit/offset parameters
   • CRITICAL: Read files yourself before spawning sub-tasks
2. Analyze and decompose the research question:
   • Break down the query into composable research areas
   • Identify specific components, patterns, or concepts to investigate
   • Create a research plan using TodoWrite to track 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:
   For codebase research:
   • Use codebase-locator agent to find WHERE files and components live
   • Use codebase-analyzer agent to understand HOW specific code works
   • Use codebase-pattern-finder agent to find examples of existing patterns
   For library and framework research:
   • Use the context7 MCP to fetch library/framework documentation
   For web research (only if explicitly requested):
   • Use web-search-researcher agent for external documentation
   For nested researches:
   • Spawn additional Tasks using

     /research <topic>

     for deep dives
4. Wait for all sub-agents to complete and synthesize findings:
   • IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding
   • Compile all results, prioritize live codebase findings as primary source
   • Connect findings across different components
   • Include specific file paths and line numbers
5. Generate research document:
   • If in plan mode, exit plan mode first
   • Write to

     thoughts/<username|shared>/research/YYYY-MM-DD-topic.md

   • Path selection: Use the user's name (e.g.,

     thoughts/taras/research/

     ) if known from context. Fall back to

     thoughts/shared/research/

     when unclear.
   Template: Read and follow the template at

   cc-plugin/base/skills/researching/template.md

   The template includes:
   • YAML frontmatter with metadata (date, researcher, git info, tags, status)
   • Standard sections (Research Question, Summary, Detailed Findings, Code References, etc.)
   • Proper formatting for file:line references
6. Add GitHub permalinks (if applicable):
   • Check if on main branch or commit is pushed
   • Generate GitHub permalinks for code references
7. Sync and present findings:
   • Present concise summary with key file references
   • If autonomy mode is not Autopilot, ask if they have follow-up questions
8. Handle follow-up questions:
   • Append to the same research document
   • Update frontmatter

     last_updated

     fields
   • Spawn new sub-agents as needed

Review Integration

file-review

• After creating research documents, invoke

  /file-review:file-review <path>

• Process feedback with

  file-review:process-review

  skill
• If user selected "No" or autonomy mode is Autopilot, skip this step

Important Notes

• Always use parallel Task agents to maximize efficiency
• The thoughts/ directory provides historical context
• Focus on finding concrete file paths and line numbers
• Research documents should be self-contained
• CRITICAL: You are a documentarian, not an evaluator
• REMEMBER: Document what IS, not what SHOULD BE