From accelerator
Interactively refines work items by decomposing into children, enriching with codebase context, sharpening acceptance criteria, sizing, or linking dependencies. Use after drafting, before planning.
npx claudepluginhub atomicinnovation/accelerator --plugin acceleratorThis skill is limited to using the following tools:
!`${CLAUDE_PLUGIN_ROOT}/scripts/config-read-context.sh`
evals/benchmark.jsonevals/evals.jsonevals/files/scenario-10/work-item.mdevals/files/scenario-10a/work-item.mdevals/files/scenario-11/work-item.mdevals/files/scenario-11a/work-item.mdevals/files/scenario-11b/target-work-item.mdevals/files/scenario-11b/work-items/0001-stub-work-item-1.mdevals/files/scenario-11b/work-items/0002-stub-work-item-2.mdevals/files/scenario-11b/work-items/0003-stub-work-item-3.mdevals/files/scenario-11b/work-items/0004-stub-work-item-4.mdevals/files/scenario-11b/work-items/0005-stub-work-item-5.mdevals/files/scenario-11b/work-items/0006-stub-work-item-6.mdevals/files/scenario-11b/work-items/0007-stub-work-item-7.mdevals/files/scenario-11b/work-items/0008-stub-work-item-8.mdevals/files/scenario-11b/work-items/0009-stub-work-item-9.mdevals/files/scenario-11b/work-items/0010-stub-work-item-10.mdevals/files/scenario-11b/work-items/0011-stub-work-item-11.mdevals/files/scenario-11b/work-items/0012-stub-work-item-12.mdevals/files/scenario-11b/work-items/0013-stub-work-item-13.mdInteractively guides creation of structured work items for features, bugs, tasks, spikes, or epics using templates and agents. Outputs to meta/work/ directory for tracking.
Generates well-structured work items with titles, descriptions, acceptance criteria, journals, and notes using govctl. Useful for creating tasks, adding criteria, or WI/task/ticket mentions.
Decomposes GitHub issues into structured Beads epics, tasks, and sub-tasks with objectively verifiable acceptance criteria and dependencies. Useful for planning actionable work in Beads projects.
Share bugs, ideas, or general feedback.
!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-context.sh
!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-skill-context.sh refine-work-item
!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-agents.sh
If no "Agent Names" section appears above, use these defaults: accelerator:reviewer, accelerator:codebase-locator, accelerator:codebase-analyser, accelerator:codebase-pattern-finder, accelerator:documents-locator, accelerator:documents-analyser, accelerator:web-search-researcher.
Work items directory: !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-path.sh work meta/work
The template below defines the sections and frontmatter fields that every work item must contain. Read it now — use it to know valid types, statuses, priorities, and section names without re-reading the file at runtime.
!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-template.sh work-item
You are tasked with refining a work item through one or more of five operations: decompose it into child work items, enrich it with codebase context, sharpen vague acceptance criteria, add a t-shirt size indicator, or populate its dependencies. Every operation is interactive and targeted — you propose, the user approves, and the Edit tool makes the minimum change needed.
If no work item path or number was provided, respond with:
I'll help you refine a work item. Please provide the path or work item number.
Example: `/refine-work-item {work_dir}/0042-user-auth.md`
Or by number: `/refine-work-item 42`
Run `/list-work-items` to see available work items.
Then wait for the user's input.
If a path or number was provided: proceed to Step 1.
Accepted forms:
meta/work/0042-user-auth.md)0042 or 42, resolved against {work_dir})If the resolved path does not exist, report:
No work item file at <path> — run `/list-work-items` to see available work items.
and exit without reading any other file, spawning any agent, or writing anything.
If the YAML frontmatter cannot be parsed (missing closing --- or syntax
error), report:
Could not parse frontmatter in <path> — the file may be corrupted. Re-open it
and check that the YAML frontmatter is bracketed by two `---` lines and
contains all nine required fields, or run `/update-work-item <path>` which
surfaces the same diagnostic with field-level detail.
and exit without editing the file or spawning agents.
Read the target work item fully. If the parent field is non-empty, also read
the parent work item. The work item template (loaded above) tells you the valid
types, statuses, and priorities — do not re-read it at runtime.
Spawn BOTH agents in the same tool-use turn (parallel, not sequential):
Wait for both before presenting the menu. Even if the work item seems straightforward, always spawn these agents — the menu previews depend on their findings.
Present the five operations with one-line descriptions. Reference agent findings in the previews so the user can pick informed:
Operations that have nothing to do should be marked as such (e.g. "sharpen — all criteria already testable").
User can select one, multiple, or "all relevant". Regardless of selection
order, always execute in canonical order: decompose → enrich → sharpen
→ size → link. This ensures Technical Notes content is in place before
size's **Size**: line is prepended, and decompose's children exist before
any link operation references them.
Propose 2–5 candidate children (2–4 for story decomposing to tasks) with draft titles and one-line Summaries derived from the Requirements section.
Bug/spike challenge: if the work item type is bug or spike, first ask:
bug/spike work items don't typically decompose — are you sure? (y/n)
Only proceed on explicit y. On n, exit decompose and return to the menu.
Existing children: if the Requirements section already contains a
### Child work items subsection, offer:
append (add new children to the existing list) / skip (do not decompose further) / cancel
Never replace the existing list silently. For the append path, use the
anchor described below under "append to existing ### Child work items".
Approval grammar: each proposal MUST include a one-line grammar legend immediately under the numbered child list:
Commands: approve all | edit N: <title> | drop N | add: <title> | regenerate | cancel
The legend appears on every proposal turn — the first proposal and after every grammar iteration.
Process user input:
approve all, yes, lgtm → proceed to the pre-write warningedit N: <new title> → update child N's title, re-show updated proposal
with legend restated. Do NOT write.drop N → remove child N, renumber remaining children 1…M, re-show
with legend. Do NOT write.add: <title> → append a new child with that title, re-show with legend.
Do NOT write.regenerate → discard current proposal, generate a fresh set of 2–5
candidates from the same Requirements. Do NOT write.cancel, abort → print "decompose cancelled — no children written"
and return to the menu. No numbers allocated.Pre-write warning: before writing, emit:
This will allocate N work item numbers and write N files; aborting mid-write
leaves partial state — use `jj restore <file>` to discard any children
written. Proceed? (y/n)
Wait for explicit y. On n, cancel without writing.
On approval:
Call work-item-next-number.sh --count N exactly once to allocate N
consecutive numbers.
For each child, write NNNN-kebab-slug.md with all nine frontmatter
fields:
work_item_id — from the script, zero-padded four-digit stringtitle — per-child proposal title; body H1 matches exactlydate — current UTC timestamp via date -u +%Y-%m-%dT%H:%M:%S+00:00author — first match in chain: parent work item's author field → configured
author value (from context config) → jj config get user.name →
git config user.name → ask the user once and apply to all childrentype — derived: epic → story, story → task, bug/spike → ask
user to confirm before proceeding (already done in the challenge step),
any other type → story with a one-line noticestatus — literal draftpriority — inherit from parent; if parent has none, ask once and
apply to every child written in this sessionparent — the target work item's work_item_id, canonicalised to a
zero-padded four-digit string (e.g. "1" → "0001")tags — verbatim copy of the parent's tags array (empty array []
if the parent has none)Immediately before writing each child, verify the computed filename does not already exist. If it does, abort with:
Collision: <path> already exists (concurrent session?). Aborting.
Allocated: NNNN, NNNN, …; Wrote: N-1 files (list them).
Use `jj restore <file>` to discard any children written.
Child body includes: Summary (from proposal), Context (linking to
parent with "Child of NNNN — "), Requirements (minimal
but substantive; no [bracketed placeholder] text), Acceptance Criteria
(minimal but substantive; sharpen can tighten these later), Dependencies
(blank), and remaining template sections.
Append ### Child work items to the parent's Requirements section:
After all children are written successfully:
\n## Requirements\n and \n## Acceptance Criteria\n<req_tail>old_string = <req_tail>\n\n## Acceptance Criteria\nnew_string = <req_tail>\n\n### Child work items\n\n- NNNN — title\n…\n\n## Acceptance Criteria\n## Requirements\n\n## Acceptance Criteria\n
as old_string and insert ### Child work items between them.old_string in the parent file. If not
exactly 1, abort the parent update with:
Could not locate a unique '## Acceptance Criteria' anchor in <path>
(matches found: <N>). Parent not updated.
Children NNNN, NNNN, NNNN remain on disk; add their links manually
or run `jj restore <parent-path>` and re-run decompose.
Children already written remain on disk.Append to existing ### Child work items (re-decompose path):
### Child work items subsection, find its last - NNNN — title
line; call this <last_link>old_string = <last_link>\n\n## Acceptance Criteria\nnew_string = <last_link>\n- NNNN — title\n…\n\n## Acceptance Criteria\nPrint a completion ledger, one line per child:
Wrote NNNN — title
Wrote NNNN — title
Allocated 3 numbers, wrote 3 files.
On aborted or partial write, show allocated vs. written counts and list any written filenames.
After a successful decompose, proceed to Step 5 (hierarchy display) before running any remaining operations.
Read the target work item's existing Technical Notes content.
If the codebase agents returned nothing concrete (no specific files or components identified), report:
no enrichment could be grounded in code — skipping enrich
and make no Edit.
Otherwise propose Technical Notes content with specific path:line
references drawn from agent results. Do not invent references.
If non-trivial Technical Notes content already exists (anything beyond a
**Size**: line), ask:
replace (deletes existing Technical Notes) / append (add after existing content) / skip?
replace → show a unified diff (old struck, new added) and require an
explicit second y/n confirmation before invoking Editappend → add new content after existing content. Preserve any leading
**Size**: line placed by a prior size operation — never overwrite itskip → make no EditOn approval via Edit: modify only the Technical Notes section. Do not touch Requirements, Acceptance Criteria, Summary, or any frontmatter field.
Read the target work item's Acceptance Criteria. Identify criteria that are vague or untestable (non-measurable phrases like "should be fast", "handles errors gracefully", "works correctly").
If every criterion is already specific and testable, report:
all acceptance criteria already testable — nothing to sharpen
and make no Edit.
Otherwise, for each vague criterion propose a specific, measurable rewrite (e.g. "p95 latency under 200ms under default benchmark dataset"). Skip criteria that are already testable — only propose rewrites for vague ones. Iterate with the user until each proposed rewrite is agreed.
On approval via Edit: modify only the Acceptance Criteria section with the agreed rewrites. Preserve criteria that were not sharpened byte-for-byte.
Read the target work item's Technical Notes. Check whether a **Size**: line
already exists as the first line.
Propose a t-shirt size (XS, S, M, L, XL) with a rationale
referencing specific files or subsystems from agent results. Iterate with
the user.
On approval:
**Size**: line: insert **Size**: <value> — <rationale>
as the FIRST line of Technical Notes, followed by a blank line separating
it from any existing content. Do NOT add as a frontmatter key.**Size**: line, proposed value AND rationale match byte-for-byte
(ignoring leading/trailing whitespace): report "size unchanged — "
and make no Edit.**Size**: line with a different value or rationale: show a
unified diff of the proposed change (existing line struck, new line added)
and require an explicit second y/n confirmation before invoking Edit.
On y, replace the line in place. On n, make no Edit.Count NNNN-*.md files in {work_dir} using a single Glob invocation.
{work_dir}Propose Blocked by: and/or Blocks: entries in Dependencies, referencing
only real work item numbers (verify each proposed number exists before
including it). If no related work items are found, print:
no related work items found — link skipped
and make no Edit.
If Dependencies already has non-empty content, ask:
replace (overwrites existing entries) / append (add new entries after existing) / skip?
replace → show a unified diff and require a second y/n confirmationappend → add only net-new entries, skipping any that duplicate existing
entriesskip → make no EditOn approval via Edit: modify only the Dependencies section.
Run immediately after decompose writes at least one child (skip if decompose was cancelled, declined by user, or the parent Edit failed).
Render the parent → children tree using the format pinned in /list-work-items:
Unicode box-drawing characters, two-space indent per depth level, ├── for
all children except the last, └── for the last child. The canonical fence
below MUST appear verbatim in this step's prose so
scripts/test-hierarchy-format.sh can verify byte-equality with the matching
fence in list-work-items/SKILL.md:
NNNN — parent title (type: , status: ) ├── NNNN — child 1 title (type: , status: ) ├── NNNN — child 2 title (type: , status: ) └── NNNN — last child title (type: , status: )
Concrete work item IDs and titles replace the placeholders in the actual
output (e.g. 0042 — User Auth Rework (type: epic)). The status field
of the parent is omitted only if blank; all present fields are shown.
Step 5 runs inline after decompose completes, before enrich, sharpen, size, and link operate on the parent. The hierarchy is not re-rendered after subsequent operations.
After the entire selected operation set completes, offer:
Would you like to run `/review-work-item` on this work item now?
If decompose was in the selection, also offer to run review on each child
written. Do NOT invoke /review-work-item automatically — only make the offer.
The skill exits after this offer regardless of the user's response.
### Child work items to
the parent's Requirements (never touching existing Requirements prose)**Size**: <value> — <rationale> line, always as
the FIRST line of Technical Notes; replace in place on re-runwork_item_id,
title, date, author, type, status, priority, parent,
tags) — those transitions are /update-work-item's concern. Children of
decompose are new work items getting their initial frontmatter.**Size**: line —
each must show a unified diff and require a second y/n confirmation./update-work-item), e.g. "1" → "0001"./create-work-item or /extract-work-items — create the work item/refine-work-item — decompose and enrich (this command)/review-work-item — automated multi-lens quality review/stress-test-work-item — interactive adversarial examination/update-work-item — status/metadata transitions (not this skill's concern)/create-plan — plan implementation from an approved work item!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-skill-instructions.sh refine-work-item