Create Work Item

!${CLAUDE_PLUGIN_ROOT}/bin/accelerator config context --skill create-work-item --fail-safe !${CLAUDE_PLUGIN_ROOT}/bin/accelerator config agents --fail-safe

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}/bin/accelerator config path work --fail-safe Active integration: !${CLAUDE_PLUGIN_ROOT}/bin/accelerator config work integration --fail-safe

The Active integration line gates the post-draft push offer (Step 5). The accelerator config work integration command above prints an empty line when no integration is configured, so branch on the string: a non-empty value means integration configured (offer the push); an empty value means not configured (no push offer — behave exactly as today). This is the single resolution of the active tracker for this invocation; the push dispatcher is told which tracker to use from this value, so the gate and the route cannot diverge.

Work Item Template

The template below defines the sections and frontmatter fields that every work item must contain. Read it now — use it to guide what information you gather in Step 1 and what structure you produce in Steps 3–4.

!${CLAUDE_PLUGIN_ROOT}/bin/accelerator config template work-item --fail-safe

You are tasked with guiding the user through creating a well-formed work item — a structured document capturing a feature, bug, task, spike, or epic for tracking and implementation. This is a collaborative, challenging conversation: the model contributes its own knowledge and research alongside the user's input rather than simply transcribing what the user says. The goal is a work item that is well-reasoned and well-specified — one that would stand on its own without needing the author present to explain it.

The work item template has three sections that look similar but capture different things — populate each deliberately:

• Assumptions are interpretations you made that affect what gets built. Flag one only when using the wrong interpretation would lead someone to build something different. Example: "Treating 'users' as end users rather than internal staff — if wrong, scope changes."
• Open Questions are genuine unknowns a reader or implementer needs resolved before work can proceed. Example: "What does 'better results' mean — improved relevance, faster delivery, or both?"
• Drafting Notes capture interpretations you made while filling out the work item — business-context calls, scope decisions, or technical choices that someone should review if they turn out to be wrong. Actively populate this section. If you inferred who the stakeholders are, what a vague term means, where the scope boundary sits, or which technical approach is implied, write it down. Routine field selections (kind, priority, tags) don't need an entry unless the choice reflects a substantive scope or meaning interpretation a reviewer should be aware of.

Step 0: Parameter Check

When this command is invoked:

1. If an argument was provided:

   First, try to resolve the argument as a reference to an existing work item by invoking the resolver:

   ${CLAUDE_PLUGIN_ROOT}/bin/accelerator work resolve <argument>
   

   The resolver respects work.id_pattern and accepts paths, full IDs (PROJ-0042), legacy bare numbers (0042), and short numbers (42, resolved against work.default_project_code when set).

   • Exit 0 (single match): the resolver echoes the absolute path on stdout. Continue to frontmatter validation below.
   • Exit 1 (input invalid — neither path, full ID, nor bare number): proceed to topic-string handling below; treat the argument as a topic.
   • Exit 2 (ambiguous match): the resolver lists every candidate with a source-category tag (legacy, project-prepended, pattern-shape, or a project code). Present the list to the user and ask them to disambiguate by re-running with a full ID (e.g. PROJ-0042) or a path.
   • Exit 3 (no match): print "No work item matching <argument> — interpreting as topic string. If that's wrong, abort and re-run with a different argument (or /list-work-items to find a valid reference)." and proceed to topic-string handling below.

   Frontmatter validation (only reached after a file was successfully resolved). Run:

   ${CLAUDE_PLUGIN_ROOT}/bin/accelerator work show <path> --field id
   

   The own-identity field is id on unified-shape files and work_item_id on legacy files; work show resolves both transparently, so either key name passed here would return the same value.

   If it exits non-zero (frontmatter missing or unclosed), print:

   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.
   

   and exit without spawning agents or writing any file. (The file clearly resolved, so the user intended a path — no fallback applies.)

   If validation passes, read the file fully (frontmatter and body) and cache the identity fields in conversation state: id (or work_item_id on legacy files), date, author, status, title, kind, priority, parent, tags. For any missing optional field, use the template default — do not abort. Set the conversation into enrich-existing mode with existing_work_item_path cached, and skip directly to Step 1 in that mode — do not run the vagueness check.

   Topic-string handling: if no resolution succeeded (discriminators did not trigger, or they triggered with a fallback warning), check whether the argument is too vague (no clear deliverable or subject).

   • Vague examples: "improve things", "fix the API", "add more features"
   • Clear examples: "add full-text search to the docs index page", "fix login timeout after password reset"
   • If vague, ask at least one clarifying question and wait for a more specific description before proceeding to Step 1.
   • If clear, proceed directly to Step 1.

2. If no argument was provided, respond with:

I'll help you create a well-specified work item through a collaborative conversation.

To get started, describe what you want to achieve — what's the problem or goal?
For example: "add full-text search to the docs index page", or "users can't log in after resetting their password"

I'll ask a few questions to understand the problem space, do some research, then
work with you to shape a thoroughly reasoned work item.

Then wait for the user's input. Apply the same vagueness check to their response — if still vague, ask a clarifying question before proceeding to Step 1.

Step 1: Gather Business Context

Once the topic is clear, ask 3–5 open questions to understand the business context before investigating. Consult the work item template sections above to understand what the work item will need — use them to guide which questions are worth asking. Tailor the questions to the topic, but cover:

• What pain point or problem does this address, and who experiences it?
• What is the desired outcome — what changes for people once this is done?
• Does the user have a solution or approach in mind? If so, surface it and ask whether it's a constraint or a preference to be explored further.
• Are there any constraints, deadlines, or dependencies worth knowing?
• For bug topics: what is the impact, and is it a blocker?
• Is there anything you are uncertain about, or that I should research?

Ask all relevant questions at once rather than one at a time. Wait for the user's answers before proceeding to Step 2.

In enrich-existing mode

Do not ask the broad discovery questions above. Instead:

1. Identify which body sections of the existing file are substantive (real content beyond [bracketed placeholder] text) and which are gaps (empty, placeholder-only, or missing entirely). Tag each gap with exactly one of the literal tokens:

   • empty — section is absent or contains no content
   • placeholder-only — section contains only template [...] blocks
   • instructional-prose — section contains the template's instructional prose carried over verbatim (e.g. "Describe the business value of this work item here…")
   • partial — section contains one or more substantive sentences alongside residual placeholders

   Use the literal token; do not paraphrase. The eval grader pattern-matches on these exact strings.

2. Present the gap analysis briefly:

   I've read the existing work item (<resolved path>). Here's what looks
   complete and what still needs work:
   
   Complete: [section list, or "none"]
   Gaps:
     - <Section> (<tag>)
     - ...
   
   I'll ask targeted questions about the gaps.
   

3. Ask only questions that address the identified gaps. Do not re-ask questions whose answers are already substantively present in the file.

4. If the existing content is rich enough that no obvious gaps remain, briefly confirm this and ask what the user wants to add or improve, then proceed to Step 2.

Step 2: Investigate

Using the topic and business context from Step 1, run investigation agents in parallel:

1. Spawn {documents locator agent} to search {work_dir} only — look for existing work items with similar titles, descriptions, or scope. Do not search research documents, plans, or other directories — work items capture business requirements, not implementation details.

2. Spawn {web-search-researcher agent} when there is uncertainty or a need for richer context about any aspect of the topic — business rules, domain concepts, competitive landscape, industry standards, external technology, or anything the model lacks confidence on. Skip this agent only when the topic is entirely self-contained and well-understood from the user's description. When in doubt, prefer to spawn research — over-asking is cheaper than producing a vague or poorly-grounded proposal.

Run both agents in parallel where both are warranted.

Once agents complete, synthesise findings — what the model knows from training, what research turned up, what prior work items exist — as the foundation for Step 3.

If a similar existing work item is found: Check its status.

• If the status is done, abandoned, or superseded — mention the work item briefly and note it is already closed, then continue creating the new one.

• Otherwise — surface the work item and offer the user numbered options, for example:

  1. Proceed with a new work item (if the scope genuinely differs)
  2. Exit and update the existing work item instead (use /update-work-item once available; for now, update it manually)
  3. Continue creating a new work item linked to the existing one as a parent

  Adapt the options to what makes sense given the work item's kind and status. Do not silently continue or modify the existing work item inline. Wait for the user's choice before proceeding.

In enrich-existing mode: exclude the resolved input file from the similarity scan. The {documents locator agent} search of {work_dir} will find the file being enriched; do not surface it as a "potential duplicate" of itself. Other near-duplicates discovered are handled per the unchanged rules above.

Step 3: Propose and Refine

Using the business context and investigation synthesis, the model leads with a structured proposal. Do not ask the user to generate requirements or acceptance criteria from scratch — propose them and invite challenge.

1. Recommend a work item kind with a brief rationale. Valid kinds come from the work item template's kind field (loaded at the top of this skill) — do not hardcode the list. Default to story when the kind is genuinely ambiguous.
2. Draft requirements drawn from the business context and research.
3. Draft acceptance criteria — specific and testable; prefer Given/When/Then format for story/task. Draw on domain knowledge and research to make these thorough, not just what the user explicitly mentioned.
4. Surface interpretations and gaps using the right section:
   • Put scope-changing interpretations you made in Assumptions and invite the user to confirm or correct them.
   • Put genuine unknowns that block progress in Open Questions.
   • Put every meaningful drafting-time interpretation (who stakeholders are, what vague terms mean, scope boundaries, implied technical approach) in Drafting Notes so a reviewer can challenge them.

Present as a structured proposal:

Based on what you've told me and my research, here's what I think this work item needs:

**Suggested kind**: [kind]
**Rationale**: [one sentence]

**Requirements I'd suggest**:
- [requirement]

**Out of scope** (explicitly not captured here):
- [item]

**Acceptance criteria I'd suggest**:
- Given/When/Then...

**Assumptions I've made** (scope-changing calls — confirm or correct):
- [assumption]

**Drafting Notes** (interpretations a reviewer should see):
- [interpretation — e.g. who stakeholders are, what a vague term means,
  scope boundary, implied technical approach]

**Open questions** (unknowns to resolve before work begins):
- [anything the user should clarify before drafting]

Wait for the user to validate, push back, or refine. Challenge vague or untestable responses — if an acceptance criterion is not measurable (e.g., "it works correctly"), first ask a clarifying question to understand the intent ("what would a passing test actually look like here?"). Only after understanding the intent should you help reformulate it into something testable. Do not accept vague criteria into the draft. Iterate until the proposal is well-specified and agreed.

In enrich-existing mode

Do not lead with a from-scratch proposal. Instead present a section-by-section review and augmentation:

Here's how the existing work item reads against my research, with proposed
additions for the gaps:

**[Section name]** — [complete | needs improvement: <reason> | missing]
[existing content excerpt or note that it is missing]
[proposed addition or replacement, when applicable]

[repeat per section]

**Title**: [keep / propose new title with rationale]
**Kind**: [keep existing <kind> / propose change to <kind> with rationale]
**Priority**: [keep / propose change with rationale]
**Parent**: [keep / propose change]
**Tags**: [keep / propose additions]
**Status**: [keep <cached> — say so if you'd like to transition it]

Apply the canonical Identity Field Rules (see Quality Guidelines): propose only the fields marked Proposable; never propose changes to immutable fields; surface a status transition only if the user makes a direct explicit request for one (the listing offers the affordance but never proposes a change unsolicited).

The refinement loop in this step (challenging untestable criteria, vague requirements, etc.) applies equally to existing and proposed content.

Step 4: Draft Work Item

1. Draft a complete work item from the agreed proposal using the template structure loaded at the top of this skill. Use NNNN as the placeholder work item number throughout. Do NOT call accelerator work next-number at this step.

2. Kind-specific content placement:

   • story/epic: open the Summary section with a user story statement — "As a [role], I want [goal], so that [benefit]." — before the descriptive sentences
   • bug reproduction steps, expected/actual behaviour → Requirements section
   • spike research questions, time-box, exit criteria → Requirements section
   • epic initial stories → Requirements section as a list
   • Do not rename or add sections beyond those defined in the work item template

3. Populate the References section with any external material that informed the work item — research artefacts surfaced by the web researcher, related work items found in Step 2, design docs, or source specs. Leave it empty if nothing external was consulted; do not invent references.

4. Populate the Drafting Notes section with the interpretations carried over from the agreed proposal. If there were none (the user confirmed every call), the section may be omitted or left as an empty list — but do not leave placeholder bracketed text in it.

5. Present the full draft to the user:

Here's my draft work item. Please review and let me know if you'd like any
changes before I write it to disk:

[draft content]

6. Continue to challenge during the review loop — flag untestable criteria, vague requirements, or gaps surfaced by research that remain unaddressed. Iterate until the user explicitly approves. accelerator work next-number is never called during this loop.

In enrich-existing mode

1. Produce a complete updated draft incorporating the existing content plus the additions approved in Step 3.

2. Apply the canonical Identity Field Rules (see Quality Guidelines) when filling frontmatter — the rules are the single source of truth for which fields are immutable, preserved, or proposable.

3. Apply the H1 sync rule (see Quality Guidelines).

4. Apply the Script avoidance rule (see Quality Guidelines).

5. Present the full updated draft, framed as an update preview:

   Here's the updated work item. The Step 5 confirmation will name the file
   path and ask for explicit approval before any write:
   
   [draft content]
   

6. Continue to challenge during review — apply the same rules as the normal-path Step 4. Iterate the draft until the user is happy with it. Do not treat a "looks good" mid-iteration as approval to write — that approval is gated by Step 5's single confirmation.

Step 5: Write Work Item

1. Call accelerator work next-number to get the next full ID under the configured pattern:

${CLAUDE_PLUGIN_ROOT}/bin/accelerator work next-number

The output is the full ID (0001 under default {number:04d}, PROJ-0001 under {project}-{number:04d} with work.default_project_code: "PROJ"). The allocator reads the pattern and default project code from configuration; pass --project CODE if the user explicitly wants a non-default project.

If the command exits non-zero (e.g., overflow, missing project value), abort immediately and surface the error message verbatim — do not proceed.

2. Resolve the target path: {work_dir}/<full-id>-kebab-slug.md where <full-id> is the allocator's output and the slug is a meaningful kebab-case summary of the title (not raw input text).

3. Check that the target path does not already exist. If it does, abort:

Path {path} already exists — another session may have written a work item
concurrently. Please re-run /create-work-item.

4. Create the work items directory if it does not exist.

5. Resolve author: configuration if present, then the current git/jj user identity, then — only if both fail — ask the user once. Never pass a placeholder. This value feeds both branches below.

6. No integration configured — write via accelerator work create. Skip this step (go to step 7) when an integration is configured; the push state machine in step 8 governs that case's single write instead.

   1. Write the drafted body (H1 through References, everything approved across Steps 1–4) to a scratch file, with the NNNN placeholder still literally present everywhere it appears (the H1 line and anywhere else) — do not substitute it yourself. work create performs the one real NNNN → allocated-ID substitution as part of the same atomic write that decides the ID, so the approved content can never end up with an id/H1 mismatch.
   2. Call the dispatcher directly:

   ${CLAUDE_PLUGIN_ROOT}/bin/accelerator work create "<title>" <kind> <priority> \
     --status draft \
     --author "<resolved author>" \
     --producer create-work-item \
     --body-file <scratch-file> \
     [--parent "work-item:NNNN"] \
     [--tag <value>]... [--block "work-item:NNNN"]... \
     [--blocked-by "work-item:NNNN"]... \
     [--derived-from "plan:NNNN"]... [--relates-to <ref>]... \
     [--source "issue-research:NNNN"] [--project <code>]
   

   Include each bracketed flag only when that field has a value — work create itself omits the corresponding frontmatter key when the flag is absent, matching the template's own omit-when-empty convention, so no separate omission logic is needed here. --tag/ --block/--blocked-by/--derived-from/--relates-to are each repeatable for multiple values. external_id has no flag — work create never writes it (nothing to sync yet); this matches today's behaviour of omitting it from a fresh draft. 3. If the command exits non-zero, surface its stderr message verbatim and abort — do not retry and do not attempt a manual Write. Otherwise its stdout is the path of the written file. Skip to step 8.

7. Push state machine (only when Active integration is non-empty; otherwise this whole step is skipped and the file was already written in step 6). The drafted frontmatter is held in memory — no file exists yet.

   1. Offer the push using the fail-safe gate. Preview the fields the push would resolve through the dispatcher's own dry-run so the single keystroke maps to an understood, non-destructive result. Write the drafted body to a temp file and run:

      ${CLAUDE_PLUGIN_ROOT}/bin/accelerator work create "<title>" <kind> <priority> \
        --push --dry-run --body-file <body-tmp>
      

      It resolves the tracker from Active integration, contacts it to resolve the fields, writes nothing, and creates no remote issue. Branch on its exit and the line it prints on stdout:

      • Exit 0, jira → jira\t<issue type>\t<type source>\t<project>\t<project source>. Render the type and project with their sources. A <project source> of unresolvable means the configured work.default_project_code names a project the tracker does not hold — surface that as a pre-create failure before the gate (name work.default_project_code) and do not offer the push; save locally instead. A default source is a benign fallback, not a failure.
      • Exit 0, linear → linear\t(no user-resolvable type/project fields) (the team and issue-type catalogue are fixed by /init-linear). Offer the push.
      • Exit 70 → the tracker was unreachable (distinct from an unresolvable value). Do not hard-block: tell the user the preview could not be resolved and offer to save locally now, or retry the preview. The push itself carries its own retry (below), so a transient outage here must not strand the draft.

      Then, when a push is still on the table:

      Use the AskUserQuestion tool with two options:

      1. Yes, push to [tracker] now — create the remote issue and save locally
      2. No, save locally only — save as unsynced; push it later with /sync-work-items (it offers to create unsynced local drafts on the remote), which shares this external_id contract.