dotfiles/dot_claude/commands/create-task.md

---
description: Plan a task by decomposing it into beads issues with dependencies, acceptance criteria, and priorities
argument-hint: <task description or goal>
allowed-tools: Bash(bd:*), Bash(git log:*), Bash(git status:*), Bash(rg:*), Task
---

# /create-task — Plan work into beads

<!--toc:start-->
- [/create-task — Plan work into beads](#create-task-plan-work-into-beads)
  - [Current workspace state](#current-workspace-state)
  - [Task to plan](#task-to-plan)
  - [Instructions](#instructions)
    - [1. Understand before creating](#1-understand-before-creating)
    - [2. Decompose](#2-decompose)
    - [3. Create issues](#3-create-issues)
    - [4. Wire dependencies](#4-wire-dependencies)
    - [5. Report the plan](#5-report-the-plan)
<!--toc:end-->

## Current workspace state

- Ready work: !`bd ready 2>/dev/null | head -30`
- In progress: !`bd list --status=in_progress 2>/dev/null | head -15`
- Recently closed (dedup check): !`bd list --status=closed 2>/dev/null | head -10`
- Stats: !`bd stats 2>/dev/null`
- Relevant memories: !`bd memories "$ARGUMENTS" 2>/dev/null | head -40`

## Task to plan

$ARGUMENTS

## Instructions

You are planning this task using **beads as the sole tracker**. Do NOT use TodoWrite, TaskCreate, or markdown checklists. Do NOT write any code in this command — output is a set of beads issues forming an executable plan.

### 1. Understand before creating

- Search for prior art first: `bd search "<keywords>"` — the task (or part of it) may already exist. Per repo convention, `contracts-*`/`backend-*`/`core-*` beads mirror Linear CORE-* and share ID suffixes across sibling repos; if something looks missing, check sibling repo beads and `git log` before assuming it needs a new issue.
- Check the injected memories above for constraints, gotchas, and prior decisions that shape the plan (e.g., root-file serialization, generated-file rules, runtime conventions).
- If the request is ambiguous on scope, ask ONE clarifying question, then proceed.

### 2. Decompose

Break the task into issues sized for a single focused session (roughly ≤ half a day each). For each issue decide:

- **type**: `feature` (new capability), `task` (chore/refactor/infra), `bug` (defect)
- **priority**: numeric only — `0` critical / `1` high / `2` medium / `3` low / `4` backlog. Never "high"/"medium"/"low".
- **description**: WHY the issue exists + WHAT done looks like. Never a bare title restatement.
- **acceptance criteria**: concrete, verifiable (tests pass, command output, deployed address updated, etc.)
- **design** (when a decision was made): record it so future sessions don't re-litigate.

If the plan touches shared root files (`turbo.json`, `pnpm-workspace.yaml`, `pnpm-lock.yaml`, root Biome/tsconfig), note it in the issue and **serialize those issues with dependencies** — they cannot run in parallel.

### 3. Create issues

Use the full quality flags:

```bash
bd create \
  --title="<imperative summary>" \
  --description="<why + what>" \
  --type=<task|bug|feature> \
  --priority=<0-4> \
  --acceptance="<verifiable criteria>" \
  --design="<decisions, if any>" \
  --notes="<gotchas from memories, file paths, related beads/Linear IDs>" \
  --validate
```

- **3+ issues → spawn parallel subagents**, one `bd create` batch each, then collect the returned IDs.
- Quote every string flag (descriptions contain `&`, `$`, backticks).
- NEVER use `bd edit` (opens $EDITOR and blocks). Amend with `bd update <id> --description/--notes/--design`.

### 4. Wire dependencies

```bash
bd dep add <dependent> <blocker>   # dependent depends on blocker
```

- Model the real execution order: tests depend on implementation, redeploys depend on ABI changes, root-file edits form a chain.
- Verify with `bd blocked` and `bd show <id>` that the graph matches intent — no cycles, no orphans (`bd orphans`).

### 5. Report the plan

Output a concise summary:

1. **Created issues** — table of `id | title | type | priority`
2. **Dependency graph** — short text sketch of the ordering (e.g. `x8y → oto → 53x`)
3. **Entry point** — which issue(s) show in `bd ready` right now, i.e., where work starts
4. **Deferred/skipped** — anything that already existed (with the existing ID) or was intentionally left out

Then persist and finish:

```bash
bd ready          # confirm entry points are unblocked
git status        # beads auto-commits to Dolt; push if session ends here
```

If planning surfaced a durable insight (a constraint, a decision, a gotcha), store it: `bd remember "<insight>"` — never a MEMORY.md file.

Do NOT start implementing any issue. Planning ends when the graph is created, validated, and reported. Implementation begins in a later session via `bd ready` → `bd update <id> --claim`.