teamcraft:create-issue

What this skill does

## Goal

Create a well-structured work item in `.teamcraft/work/` that captures what needs to be done and how to know it's done. The work item should contain enough information for a developer (or AI agent) to pick it up later and understand the requirements — but stay light on technical implementation details, which are generated fresh at implementation time.

Create the item to the **work-item standard** — `../references/work-item-standard.md` is the single source of truth for the format, ID rules, relationships, INDEX update, and commit, shared by every skill that creates work items. Read it first, plus `references/example-work-item.md` for worked examples of the shape and what "light on technical guidance" looks like in practice.

## What to Capture

**1. Understand what the developer wants to capture.** `$ARGUMENTS` is a brief description or empty. If it's a description, use it as a starting point. If empty, ask what work they want to track.

**2. Ask about external context.** "Do you have requirements, mockups, user research, or any other context for this work documented somewhere I can access?" Read whatever they point to. Present what you found and let the developer decide what's relevant — never auto-apply external content.

**3. Interview for the essentials.** After reviewing any external context, fill in what's still missing:
- What is this work? (clear title and description)
- Why does it matter? (business context, user need, bug impact)
- What does "done" look like? (acceptance criteria — specific, testable)
- Priority? (critical, high, medium, low)
- Effort estimate? (small, medium, large, xl — optional, developer can skip)
- Is this a feature, bug, or chore? (determines the ID prefix)

**4. Ask about relationships to other work items.** After the essentials, ask whether this item has any structured relationships to existing work items. Phrase it briefly so simple items don't slow down. For example: "Is this blocked by, related to, or a duplicate of any existing work item? (skip if none)". If yes, capture:
- `blocked_by` — work items that must complete before this one can start. Most important to capture; gates pickability.
- `relates_to` — soft links to items that share context or touch the same area without a hard sequence.
- `duplicates` — historical pointer when this item is the same as an earlier one; the duplicate is closed (status `done`) and points to the original.

Validate IDs lightly: glob `.teamcraft/work/*.md` and warn if a referenced ID isn't found ("`feat-xyz` isn't in the backlog — was it spelled differently, or is it not created yet?"). Don't block on this — the developer may be creating items out of order. Don't write `blocks` as the inverse of `blocked_by` — the work-board and the other consumers compute that direction on read; storing both sides invites drift.

See "Relationships vs Bundling" below for when to use relationships at all vs. just making it one work item.

**5. Present the work item for review.** Show the complete work item before writing it, including any relationships. The developer confirms or adjusts.

## Write the Work Item

Write the item to the **work-item standard** (`../references/work-item-standard.md`): generate the ID, write `.teamcraft/work/<id>.md`, add the INDEX row, and commit with the work-item ID in the message. The standard owns all the format and mechanics — ID rules, frontmatter, body shape, INDEX update, one-way relationships, and the relationships-vs-bundling test — so they live in one place rather than being restated here.

## Relationships vs Bundling

When the developer mentions a connection to other work, decide whether it's a real relationship or just part of this one item — the work-item standard's *Relationships vs bundling* section is the test. The trap to watch for in the interview: treating implementation steps as separate work items. They aren't — steps are acceptance criteria. Relationships are only for things that genuinely ship as separate PRs.

## Constraints

- **The developer can create multiple work items in one session.** After creating one, ask if they have more to capture. Don't end the skill after a single item unless they're done.
- Everything about the item's shape and robustness — light-on-technical-guidance, `status: backlog` at creation, one-way relationships, the commit — is defined once in `../references/work-item-standard.md`. Follow it; don't improvise a lighter version.

## When You're Done

Confirm what was created, including the file path and the INDEX.md update. If the developer wants to start working on the item immediately, point them to `/plan-and-implement-issue <id>`.