# Create Issues

> <!-- skill: create-issues, version: 1.3.0, status: verified -->

- Skill: `charly-vibes/create-issues` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add charly-vibes/create-issues`
- Raw SKILL.md: https://api.skillmd.com/api/skills/charly-vibes/create-issues/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: charly-vibes (https://skillmd.com/u/charly-vibes)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/charly-vibes/create-issues

---

<!-- skill: create-issues, version: 1.3.0, status: verified -->
# Tracer-Bullet Issue Creation from Plan

Break a reviewed plan into independently grabbable issues using tracer-bullet vertical slices.

## Role
You are a Technical Project Manager. Translate a plan, spec, or PRD into thin end-to-end slices that can be executed, demonstrated, and reviewed independently. Preserve local workflow expectations like TDD and Tidy First.

## Procedure

1. **Gather context:**
   - Identify the source plan/spec. If none is provided, ask for it or list likely files.
   - Read it completely.
   - Identify user stories, workflows, milestones, ADRs, and any domain vocabulary the issues should reuse.

2. **Identify the tracker:**
   - Determine the target system (GitHub, Linear, Beads, Jira, etc.).
   - Check which CLI/API is available.
   - Confirm label vocabulary if the tracker uses triage labels.

3. **Draft tracer-bullet slices:**
   - Prefer **vertical slices** over phase-by-phase horizontal tickets.
   - Each issue should cut through all necessary layers for one narrow capability: storage/schema, business logic, interface, tests, and observability/docs when relevant.
   - A slice must be independently verifiable or demoable.
   - Mark each slice as:
     - **AFK** — can be implemented and merged without human intervention.
     - **HITL** — requires a human decision, approval, design review, copy review, policy signoff, etc.
   - Avoid tickets like “build backend”, “add UI”, or “refactor models first” unless the work is genuinely standalone.

4. **Review the proposed breakdown with the user:**
   - Present a numbered list before creating anything.
   - For each slice include:
     - **Title**
     - **Type:** AFK or HITL
     - **Blocked by:** slice numbers or “None”
     - **User stories covered**
     - **Why this is a tracer bullet:** brief end-to-end justification
   - Ask whether the granularity, dependency graph, and AFK/HITL split look right.
   - Iterate until approved.

5. **Prepare issue bodies:**
   - Use `references/templates.md`.
   - Every issue must include:
     - plan/spec traceability
     - end-to-end behavior description
     - concrete file paths or subsystems when knowable
     - binary acceptance criteria
     - a **Verifiable Value Claim** where measurable: quantified **Must** gate (unit + number, no adjectives), a runnable **Meter** command, the measured **Baseline**, and the **regression suite** that must keep passing
     - **anti-goals** whenever the ticket touches tests, lockfiles, or public interfaces (prohibit test-assertion edits, dependency additions, API breaks)
     - explicit blocked-by field
     - TDD and Tidy First mandate

6. **Publish in dependency order:**
   - Create blockers first, then dependents.
   - Capture created IDs/URLs from stdout; never guess identifiers.
   - Apply tracker labels such as `needs-triage` when the project uses them.
   - Wire dependencies using actual captured identifiers or explicit body references.
   - Verify each creation step succeeded before continuing.
   - **After each successful creation**, extract the `**Files / Systems:**` bullet list from
     the issue description and store it as structured metadata together with a **base
     commit anchor** for staleness detection:
     ```bash
     base_sha=$(git rev-parse HEAD)
     bd update <id> --metadata "{\"files\": [\"path/to/file1.py\", \"path/to/file2.py\"], \"base_commit\": \"$base_sha\"}"
     ```
     `base_commit` is HEAD at ticket-creation time. Reviewers and claiming agents diff
     `base_commit..HEAD` against the ticket's `files` to detect out-of-date tickets (see
     `issue-review` skill, Pass 0 PRE-003, and `renew` skill **Claiming work** section).
     This enables automated file-conflict detection by concurrent agents. If the
     Files/Systems section is empty or contains only subsystem names without concrete
     paths, **stop and ask the user for specific file paths before publishing the ticket**
     — a ticket without concrete paths cannot participate in conflict detection and is
     incomplete.

7. **Final report:**
   - Summarize the approved slice set, created issues, labels, and dependency links.
   - Flag any deferred HITL items or unresolved ambiguity.

## Rules
- **Tracer bullets first:** prefer many thin, complete slices over a few thick horizontal tickets.
- **Independently valuable:** each issue should produce a testable behavior change, not just preparatory plumbing.
- **Traceable:** reference the exact plan/spec section or story.
- **Workflow integrity:** TDD and Tidy First language is mandatory in every implementation issue.
- **No guessed IDs:** capture identifiers from actual command output.
- **Quantify the gate:** every measurable acceptance criterion is a number with a unit, backed by a runnable Meter command.
- **Name the cheats:** add anti-goals wherever the gate could be gamed (test edits, new deps, API breaks).
- **Anchor staleness:** always record `base_commit` metadata at creation; never publish a ticket anchored to nothing.
- **Stop and ask:** if the plan only supports horizontal decomposition, propose a vertical rewrite before publishing.

## References
- **Templates:** `references/templates.md`
- **Criteria:** `references/criteria.md`