research

Add Research Task to Queue

Add a research or investigation task that produces a plan document before implementation begins.

Arguments

• $ARGUMENTS - Brief description of what needs to be researched

When to Use

Use /queue:research instead of /queue:add when:

• The task requires investigation before implementation
• You need to evaluate multiple approaches
• The scope is unclear and needs a plan first
• Architecture decisions need to be documented
• The change is significant enough to warrant review before coding

Process

1. Read .claude/queue/backlog.json to get current items

2. Gather required information:

   • Title: From the arguments (or ask if unclear)
   • Priority: 1 (urgent) to 5 (low) - ask if not specified
   • Owner: Which agent should investigate (e.g., staff-engineer, staff-software-architect)
   • Research Question: What needs to be investigated
   • Scope: What areas/files/systems are involved
   • Expected Output: What the plan document should cover

3. Create the work item:

   {
     "id": "YYYY-MM-DD-{slug}",
     "title": "Research: Brief description",
     "type": "research",
     "priority": 1-5,
     "status": "pending",
     "requires_approval": true,
     "owner": "agent-type",
     "plan_file": ".claude/queue/plans/YYYY-MM-DD-{slug}.md",
     "context": {
       "problem": "What needs investigating",
       "research_questions": ["Question 1", "Question 2"],
       "scope": ["area1", "area2"],
       "expected_output": "What the plan should cover"
     },
     "sizing": "single-context",
     "created": "ISO timestamp",
     "updated": "ISO timestamp"
   }
   

4. Add to backlog.json and write the file

Plan File Template

When the research task is picked up via /queue:work, the agent will create a plan document at the plan_file path using this structure:

# Plan: {title}

**Research Task**: {id}
**Author**: {owner}
**Date**: {date}

## Problem Statement
{What we're trying to solve}

## Investigation Summary
{What was discovered during research}

## Proposed Approach
{Recommended solution with rationale}

## Alternatives Considered
| Approach | Pros | Cons |
|----------|------|------|
| {alt1} | ... | ... |
| {alt2} | ... | ... |

## Implementation Plan
1. {Step 1}
2. {Step 2}
3. {Step 3}

## Files Affected
- {file1}: {what changes}
- {file2}: {what changes}

## Risks & Mitigations
- {risk1}: {mitigation}

## Open Questions
- {Any remaining unknowns}