teamcraft:create-issue

---
name: teamcraft:create-issue
description: Create a work item in the repo's backlog. Interviews for requirements and acceptance criteria, checks for external context, and writes a structured work item to `.teamcraft/work/`. Use when the user says 'create an issue', 'add a work item', 'I need to track this', 'new feature request', 'log this bug', 'add this to the backlog', or describes work they want to capture for later.
argument-hint: "[brief description of the work, or empty to be interviewed]"
disable-model-invocation: false
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - AskUserQuestion
---

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

Read `references/example-work-item.md` first. It shows the work item format, frontmatter structure, and what "light on technical guidance" means 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

Generate an ID from the type and a short slug: `feat-notification-prefs`, `bug-timezone-display`, `chore-upgrade-react-19`. Check `.teamcraft/work/` to ensure the ID doesn't already exist. If it does, differentiate the slug — make it more specific to the actual work rather than appending a number (e.g., `feat-notification-prefs-quiet-hours` not `feat-notification-prefs-2`).

Write the work item file to `.teamcraft/work/<id>.md` with structured YAML frontmatter and markdown body.

Add a row to `.teamcraft/work/INDEX.md` with the ID, status, priority, and one-line summary. If `INDEX.md` doesn't exist, create it with the table header.

Commit both files. Include the work item ID in the commit message (e.g., `chore(feat-notification-prefs): create work item`).

## Relationships vs Bundling

When the developer mentions a connection between this work and other work, ask which kind it is — the answer determines whether you write a relationship or just expand the current item:

- **Same logical change, one PR shape:** make it ONE work item with multiple acceptance criteria. Splitting purely-implementation steps into separate items (e.g., "write the API endpoint" + "wire it to the UI" for one feature) creates fake dependencies and clutters the backlog. If they ship together as one PR, they're one work item.
- **Separate PR-shaped units that must happen in order:** two (or more) work items with `blocked_by` capturing the order. Each is independently picked, planned, reviewed, and merged.
- **Separate units that touch the same area without ordering:** two work items with `relates_to`. Useful so the developer sees the connection when picking either one, but neither blocks the other.
- **Duplicate of an existing item:** one work item with `duplicates: [original-id]` and `status: done`. The original is the canonical record.

The common confusion is treating implementation steps as separate work items. Don't. Steps go in acceptance criteria. Relationships are for things that genuinely ship separately.

## Constraints

- **Light on technical guidance.** Acceptance criteria describe WHAT, not HOW. Technical analysis happens fresh in `plan-and-implement-issue` when the work is actually picked up — by then the codebase may have changed. Don't include file paths, implementation approaches, or architectural decisions in the work item.
- **Status is always `backlog` for new items.** The developer or `plan-and-implement-issue` changes it later.
- **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.
- **Relationships are stored one-way.** Write only `blocked_by`, `relates_to`, and `duplicates` on the item that has knowledge of the dependency. The inverse direction (`blocks` for `blocked_by`) is computed on read by the consumers (work-board, project-status, pick-next-issue) — storing both sides invites drift.

## 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>`.