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

---
description: Research a bead topic comprehensively and store findings in thoughts/
model: 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**:
   ```bash
   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**:
   ```bash
   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

```bash
# 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`:

```markdown
---
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

```bash
# 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:
  ```bash
  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?
```