create-task

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.

Simplicity principle (MANDATORY): The simplest correct solution wins. Every task this skill produces must bias toward the minimum viable change — reuse over create, extend over abstract, delete over refactor. Distinguish essential complexity (domain-inherent, cannot be removed) from accidental complexity (reducible) and eliminate the accidental. See /reduce-complexity for the full framework. Task descriptions that encourage "flexible", "extensible", "future-proof" designs without concrete current need are anti-patterns — reject them.

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

Input formats:

• Positional string: "title text here"
• Flags: --title, --type, --priority, --labels, --files-hint, --parent
• Pasted paragraph with description

Flags:

Flag	Effect
--quick	Skip research (Phase 1). Apply template with available info only.
--dry-run	Print the full description without creating the beads task.
--from-plan <path> --step=N	Extract task from a plan file step.
--type=<type>	Task type: task, bug, feature, epic, question, docs (default: task)
--priority=<N>	Priority 0-4 (default: 2)
--labels=<a,b>	Comma-separated labels
--files-hint=<paths>	Comma-separated file paths to seed research
--parent=<id>	Parent epic beads ID

---

Phase 0 --- Parse Intent

1. Extract from input:

   • Title (required): Clear imperative statement of what to do
   • Brief description: 1-2 sentence context (if provided)
   • Type: default task
   • Priority: default 2
   • Labels, files-hint, parent: if provided

2. 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?)

3. 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 (simplicity-first search)
Check for existing utilities that could be reused (per duplication prevention rules).
**Rule of thumb:** if a helper exists, extend it; if a pattern exists, mirror it; if
a type exists that is 80% of what you need, grow it instead of cloning it.

- Search `src/utils.rs` and `src/` broadly for related helpers
- Check sibling modules for similar patterns
- Note any existing abstractions that should be extended rather than duplicated
- Flag candidates where the task can be reduced to calling existing code with
  different arguments — these are the cheapest wins

### Step 4.5: Identify Simplification Opportunities
Before writing the Desired State, look for ways the work can be *smaller*:

- Can any step be deleted entirely? (dead paths, unused fields, redundant checks)
- Can two branches merge into one? (guard clauses, early returns, let-else)
- Is there a built-in or stdlib answer that removes a homegrown helper?
- Is the current approach essentially or accidentally complex? If accidentally
  complex, the task should *reduce* it, not just patch around it.

Record these as "Simplification Opportunities" in the research output. They feed
directly into the Desired State and Implementation Guidance so the task biases
toward the minimum viable change.

### 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")

Simplification Opportunities

Opportunity	Where	Effect
(accidental complexity to remove as part of this task, or "None — scope is essential complexity only")

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>

3. 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
// src/cache.rs:42-58 — current boundary check
{actual code from research}

Desired State

{What should exist after. Specific behavior, interface, or structure. Simplicity gate: Describe the minimum viable change. If the task proposes a new abstraction, a new module, a new trait, a new config knob, or a generalization, justify it by naming at least 2 concrete current call sites that need the flexibility. "Future-proofing" and "extensibility" are not justifications.}

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 src/ for or siblings. "None found" if nothing applies.}

Blast Radius

{Callers, downstream effects, call sites needing updates.}

Code References

{3-5 inline snippets of the most relevant current code, each 5-20 lines. Each snippet has a file:line header.}

Related Work

Task ID	Title	Relationship
{Or "None found" — section must always be present.}

Acceptance Criteria

• {Specific verifiable condition}
• All existing tests pass: cargo test
• Code compiles clean: cargo fmt && cargo check && cargo clippy --all-targets -- -D warnings
• No net increase in accidental complexity — run /reduce-complexity on each modified file; any new HIGH/CRITICAL hotspots must be justified as essential or addressed in the same change.
• No duplicated logic introduced (per duplication prevention rules in CLAUDE.md).

Pointers

{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.

---

Phase 4 --- Create Task

1. Write the composed description to a temp file:

   TMPFILE=$(mktemp /tmp/task-desc-XXXXXX.md)
   

   Write the description content to the temp file.

2. Create the beads task:

   bd create --title="{TITLE}" --type={TYPE} --priority={PRIORITY} --body-file="$TMPFILE"
   

   Add --labels={LABELS} if provided. Add --parent={PARENT} if provided.

3. Register dependencies (from Phase 2):

   bd dep add <new-id> <blocker-id>
   

4. Clean up temp file:

   rm "$TMPFILE"
   

5. Show the created task:

   bd show <new-id>
   

6. Present summary to user:

   Created task: {id}
   Title: {title}
   Type: {type} | Priority: P{priority}
   Sections: {count} mandatory + {count} conditional
   Related tasks linked: {count}
   Dependencies added: {count}
   

Dry Run Mode

If --dry-run is passed, skip step 2-4. Instead, print the full description to the user with a header:

--- DRY RUN: Task Description Preview ---
Title: {title}
Type: {type} | Priority: P{priority}

{full description}

--- End Preview (no task created) ---

---

Anti-Patterns

Anti-Pattern	Why It's Wrong	Do This Instead
Creating a task with no description	Agent wastes time rediscovering context	Always use this skill or follow the template
Writing "see review for details"	External reference will rot; agent can't work it	Inline all context in the description
Code references without file:line	Agent can't find the code	Always include file path and line numbers
Acceptance criteria like "it works"	Not verifiable	Specific conditions: "function returns X when given Y"
Skipping Related Work search	Creates duplicates, misses dependencies	Always run bd search
Research agent reading 20+ files	Diminishing returns, bloats context	Cap at 8 files, focus on most relevant
Silently creating a duplicate	Wastes implementation effort	Always present possible duplicates to user
Describing a "flexible" or "generic" solution without current call sites	Premature abstraction — accidental complexity baked in	Require 2+ concrete call sites before allowing abstraction; otherwise specify concrete change
Task that adds a new module/trait/config knob to "make it easier to extend later"	YAGNI violation — pays a complexity tax now for a hypothetical future	Specify the minimum change; open a follow-up task IF extension is actually needed later
Scope-creeping: "while we're here, also refactor X"	Mixes concerns, inflates blast radius, blocks review	Split into separate tasks; each task does ONE thing

Related Skills

• /reduce-complexity — complexity framework this skill relies on to shape Desired State and Simplification Opportunities; invoke directly when in doubt about essential vs. accidental complexity
• /plan-forge — creates implementation plans; use --create-tasks to auto-generate tasks from plan steps
• /execute-review-findings — converts review findings to tasks (uses compatible template)
• /review-dispatch — produces findings that may become tasks
• /review-task — validates a task created by this skill; also runs simplicity checks