Use when creating any beads task — auto-researches the codebase, links related tasks, and produces a rich self-contained description from a structured template. Accepts minimal intent and outputs a complete task ready for agent implementation.
Instrucciones de origen · Vista previa de solo lectura
name
create-task
description
Use when creating any beads task — auto-researches the codebase, links related tasks, and produces a rich self-contained description from a structured template. Accepts minimal intent and outputs a complete task ready for agent implementation.
Create Task
Creates high-quality, self-contained beads tasks by researching the codebase and
assembling a structured description. Every task produced by this skill should give
an implementing agent 90% of the context it needs inline.
Core principle: Invest effort at creation time to save 10x at implementation time.
Invocation
/create-task "Fix off-by-one in window boundary check" --type=bug --priority=1
/create-task --quick "Add capacity hint to Vec in compile_rules" --type=task --priority=3
/create-task --dry-run "Refactor transform chain error handling" --type=task --priority=2
/create-task --from-plan docs/plans/2026-02-23-feature-v3.md --step=3
If only a title with no brief description, ask the user:
What's the 1-2 sentence context for this task? (What problem does it solve or what need does it address?)
If --from-plan is specified:
Read the plan file at the given path
Extract the step indicated by --step=N
Map plan fields: Problem Statement -> Context, Codebase Context -> Current State,
step What -> Desired State, step Files -> Files to Modify, step Tests -> Testing Strategy,
step Acceptance criteria -> Acceptance Criteria
Proceed to Phase 3 (skip research — plan already has codebase context)
Phase 1 --- Research (Explore Agent)
Skip when --quick is passed.
Spawn one subagent_type=general-purpose agent with the structured research prompt
below. The agent performs up to ~30 tool calls across 6 steps.
Research Agent Prompt
You are a codebase researcher preparing context for a new task. Your job is to
gather specific, concrete information — NOT to implement anything.
## Task Being Created
**Title**: {TITLE}
**Brief**: {BRIEF_DESCRIPTION}
**Type**: {TYPE}
**Files hint**: {FILES_HINT or "none provided"}
## Research Steps (follow in order)
### Step 1: Find Affected Files
Use Grep and Glob to search for identifiers, types, functions, and concepts
mentioned in the title and brief. Search broadly:
- Exact names and keywords from the title
- Related concepts (synonyms, adjacent functionality)
- File paths mentioned in files-hint
List every file that is likely touched by this task.
### Step 2: Read Relevant Code
Read the specific functions, structs, and modules most relevant to this task.
- Maximum 8 files
- For each, extract the most relevant 5-20 line snippet with file:line header
- Note function signatures, struct definitions, trait impls
### Step 3: Trace Blast Radius
For the primary functions/types affected:
- Grep for callers and call sites
- Note which modules depend on the affected code
- Identify downstream effects of changes
### Step 4: Find Reusable Patterns
Check for existing utilities that could be reused (per duplication prevention rules):
- Search `crates/gossip-stdx/src/` for related helpers
- Check sibling modules for similar patterns
- Note any existing abstractions that should be extended rather than duplicated
### Step 5: Search Related Beads Tasks
Run: `bd search "{keywords from title}" --limit 10`
For each result, classify the relationship:
- **blocks**: This new task cannot start until that task completes
- **blocked-by**: That task cannot start until this new task completes
- **relates-to**: Related but independent work
- **possible-duplicate**: May be the same task — FLAG THIS
### Step 6: Assess Scope
Based on your research, classify:
- **files_affected**: count of files that will be modified
- **modules_crossed**: count of distinct modules (top-level src/ directories)
- **touches_hot_path**: true/false — does this touch engine/, coordination/, stdx/, or hot loop code?
- **has_unsafe**: true/false — does affected code contain unsafe blocks?
## Output Format
Return a structured markdown document with these sections:
### Affected Files
| File | Relevance | What Changes |
|------|-----------|-------------|
### Code Snippets
For each relevant snippet:
```rust
// {file_path}:{start_line}-{end_line} — {brief description}
{actual code}
Blast Radius
Caller/Dependent
File
Relationship
Reusable Utilities
Utility
Location
How to Reuse
(or "None found")
Related Tasks
Task ID
Title
Relationship
Notes
(or "None found")
Scope Assessment
files_affected: {N}
modules_crossed: {N}
touches_hot_path: {true/false}
has_unsafe: {true/false}
IMPORTANT: Be concrete. Every file path must be real. Every code snippet must
be copied from the actual codebase, not invented. Every task ID must come from
bd search output.
---
## Phase 2 --- Link Related Tasks
Process the Related Tasks output from the research agent:
1. **Possible duplicates**: Present to the user with details. Ask before proceeding.
> Found a possible duplicate: {task_id} "{title}". Should I:
> (a) Skip creating this task (it's already covered)
> (b) Create anyway (different scope)
> (c) Show me more details
**Never silently create a duplicate.**
2. **Blocking relationships**: After the task is created (Phase 4), run:
```bash
bd dep add <new-id> <blocker-id>
Relates-to: Include in the Related Work section of the description.
Phase 3 --- Compose Description
Assemble the full task description from the template below, filling sections
with explore agent output (Phase 1) or available information (if --quick).
Complexity Scaling
Complexity
Criteria
Sections
Expected Length
Trivial
1 function, clear fix
Mandatory only
30-60 lines
Standard
1-3 files, 1 module
All mandatory
80-150 lines
Complex
3+ files, multi-module
All mandatory + conditionals
200-400 lines
Determine complexity from the scope assessment (Phase 1) or from the brief
description (if --quick).
Mandatory Sections (ALL Tasks)
## Context
{Why this task exists. What problem or need it addresses. What symptom prompted it.}
## Current State
{What exists today with code snippets and file:line references.}
```rust
// crates/scanner-engine/src/engine/core.rs:142-158 — current boundary check
{actual code from research}
Desired State
{What should exist after. Specific behavior, interface, or structure.}
Implementation Guidance
Files to Modify
File
Change
Rationale
Patterns to Follow
{Existing patterns to mirror, with file:line refs. "None" if nothing specific.}
Utilities to Reuse
{From crates/gossip-stdx/src/ or siblings. "None found" if nothing applies.}
{Where to look for the remaining ~10%: docs, related commits, design docs, files to read.}
### Conditional Sections
Include these based on scope assessment:
| Section | Include When | Content |
|---------|-------------|---------|
| **Design Notes** | modules_crossed >= 2 or multiple valid approaches | Trade-offs, alternatives considered, rationale for chosen approach |
| **Risk Analysis** | priority <= 1 or has_unsafe | What could go wrong, mitigation strategies, rollback plan |
| **Performance Considerations** | touches engine/, stdx/, coordination/ | Hot path impact, allocation concerns, benchmark expectations |
| **Testing Strategy** | files_affected > 1 | What tests to add/modify, test types (unit, property, integration), coverage goals |
Place conditional sections between "Code References" and "Related Work".
### Handling Missing Information
If the research agent didn't find enough for a section, include the section
with a `[NEEDS ENRICHMENT]` marker:
```markdown
### Blast Radius
[NEEDS ENRICHMENT] — Could not trace all callers. The implementing agent should
grep for usages of `FunctionName` before making changes.
