nixos-configs/home/roles/development/skills/beads_research.md

description, model

description	model
Research a bead topic comprehensively and store findings in thoughts/	opus

Beads Research

You are tasked with conducting comprehensive research for a bead issue. This skill integrates with the beads issue tracker and stores findings in the thoughts/ directory.

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
• 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:

1. Parse the input for bead ID:

   • If a bead ID is provided (e.g., nixos-configs-abc123), use it
   • If no bead ID provided, run bd ready --type=research to find research beads, or ask which bead to research

2. Load bead context:

   bd show {bead-id}
   

   • Read the bead description to understand the research question
   • Note any linked files or references in the bead

3. Create artifact directory:

   mkdir -p thoughts/beads-{bead-id}
   

4. Respond with:

   Starting research for bead {bead-id}: {bead-title}
   
   Research question: {extracted from bead description}
   
   I'll analyze this thoroughly and store findings in thoughts/beads-{bead-id}/research.md
   

Research Process

Step 1: Read any directly mentioned files

• If the bead or user mentions specific files, read them FULLY first
• Use the Read tool WITHOUT limit/offset parameters
• Read these files yourself in the main context before spawning sub-tasks

Step 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
• Consider which directories, files, or patterns are relevant

Step 3: Spawn parallel sub-agent tasks

Use specialized agents for research:

For codebase research:

• codebase-locator - Find WHERE files and components live
• codebase-analyzer - Understand HOW specific code works
• codebase-pattern-finder - Find examples of existing patterns

For thoughts directory:

• thoughts-locator - Discover what documents exist about the topic
• thoughts-analyzer - Extract key insights from specific documents

For web research (only if explicitly requested):

• web-search-researcher - External documentation and resources

Key principles:

• Run multiple agents in parallel when searching for different things
• Each agent knows its job - tell it what you're looking for, not HOW to search
• Remind agents they are documenting, not evaluating

Step 4: Synthesize findings

Wait for ALL sub-agents to complete, then:

• Compile all results (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
• Highlight patterns, connections, and architectural decisions

Step 5: Gather metadata

# Git metadata
git rev-parse HEAD                    # Current commit
git branch --show-current             # Current branch
basename $(git rev-parse --show-toplevel)  # Repo name
date -Iseconds                        # Current timestamp

Step 6: Write research document

Write to thoughts/beads-{bead-id}/research.md:

---
date: {ISO timestamp with timezone}
bead_id: {bead-id}
bead_title: "{bead title}"
researcher: claude
git_commit: {commit hash}
branch: {branch name}
repository: {repo name}
status: complete
---

# Research: {bead title}

**Bead**: {bead-id}
**Date**: {timestamp}
**Git Commit**: {commit hash}
**Branch**: {branch name}

## Research Question
{Original question from bead description}

## Summary
{High-level documentation answering the research question}

## Detailed Findings

### {Component/Area 1}
- Description of what exists (file.ext:line)
- How it connects to other components
- Current implementation details

### {Component/Area 2}
...

## Code References
- `path/to/file.py:123` - Description
- `another/file.ts:45-67` - Description

## Architecture Documentation
{Current patterns, conventions found in codebase}

## Historical Context (from thoughts/)
{Relevant insights from thoughts/ with references}

## Open Questions
{Any areas needing further investigation}

Step 7: Update the bead

# Add artifact link to bead notes
bd update {bead-id} --notes="Research complete: thoughts/beads-{bead-id}/research.md"

Step 8: Autonomy decision

For research beads (type=research):

• If research is complete and comprehensive, close the bead:

  bd close {bead-id} --reason="Research complete. See thoughts/beads-{bead-id}/research.md"
  

• Present summary to user

For other bead types:

• Do NOT close the bead
• Present findings and ask how to proceed

Step 9: Handle follow-up questions

If the user has follow-up questions:

• Append to the same research document
• Add a new section: ## Follow-up Research [{timestamp}]
• Update the bead notes with the new findings

Important Guidelines

• Always use parallel Task agents to maximize efficiency
• Always run fresh codebase research - never rely solely on existing documents
• Focus on finding concrete file paths and line numbers
• Research documents should be self-contained
• Document cross-component connections
• Include temporal context (when research was conducted)
• Keep the main agent focused on synthesis, not deep file reading
• CRITICAL: You and all sub-agents are documentarians, not evaluators
• REMEMBER: Document what IS, not what SHOULD BE

Example Invocation

User: /beads:research nixos-configs-abc123
Assistant: Starting research for bead nixos-configs-abc123: Investigate auth flow
...

Or without bead ID:

User: /beads:research
Assistant: Let me check for research beads...
[runs bd ready]
Which bead would you like me to research?