# create-issues (Unified Skill)

## Core Instructions (SKILL.md)

<!-- skill: create-issues, version: 1.2.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
     - 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.

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


---

## Reference: criteria.md

# Issue Creation Criteria

Use these criteria to evaluate whether a plan has been translated into strong tracer-bullet issues.

## High-Quality Issue Standards

| Feature | Criteria |
| :--- | :--- |
| **Tracer-bullet shape** | Each issue is a thin vertical slice, not a horizontal layer ticket. |
| **Independent value** | A completed issue is demoable, testable, or otherwise verifiable on its own. |
| **Atomicity** | Each issue covers one logical capability. If it spans multiple unrelated behaviors, split it. |
| **Actionable Title** | Short, specific, and domain-oriented. Prefer behavior over component names. |
| **Traceability** | Contains a direct reference to the source plan/spec section or story. |
| **Verifiability** | Acceptance criteria are binary and observable. |
| **Dependency hygiene** | Only real blockers are encoded; parallel work is not serialized without reason. |
| **Workflow Mandate** | Includes the mandatory TDD and Tidy First block. |
| **Execution mode** | Slice is explicitly marked AFK or HITL. |

## Tracer-Bullet Heuristics

Use these checks before publishing:

- [ ] Does this issue deliver a narrow but complete path through relevant layers?
- [ ] Could someone demo or verify this slice without waiting for a later ticket?
- [ ] Is this a user-visible or system-verifiable outcome rather than plumbing-only work?
- [ ] If the ticket is preparatory, is that preparatory work itself independently valuable?
- [ ] Would splitting by backend/frontend/schema create worse horizontal tickets than the current slice?

## Dependency Reliability Checklist

- [ ] All IDs captured from command output using variables.
- [ ] Dependency commands reference the captured variables.
- [ ] Blockers are real prerequisites, not just preferred order.
- [ ] AFK/HITL designation is explicit.
- [ ] Parallel work is left parallel where the tracker supports it.

## When to Stop & Ask

- [ ] The plan is written as phases/layers only and cannot yet be sliced vertically.
- [ ] Acceptance criteria are too vague to make binary.
- [ ] File paths or impacted surfaces are unknown and need discovery.
- [ ] The target tracker is not accessible via CLI/API.
- [ ] Existing issues already cover part of the plan and would conflict with new tickets.
- [ ] HITL slices need human approval before publishing.


---

## Reference: templates.md

# Issue Creation Templates

Use these templates for proposed slice breakdowns, issue descriptions, and the final creation summary.

## Proposed Slice Review Template

```markdown
1. **[Title]**
   - **Type:** [AFK|HITL]
   - **Blocked by:** [None | Slice 1, Slice 2]
   - **User stories covered:** [Story A, Story B]
   - **Tracer-bullet rationale:** [Why this is a thin end-to-end slice]
```

## Issue Description Template

```markdown
## Parent

[Reference to parent plan/spec/issue, if applicable]

## What to build

[Describe the end-to-end behavior of this slice in domain language.]

**Context:** [Brief explanation tied to the source plan/spec]
Ref: [Link to plan/spec file and section]

**Files / Systems:**
- `path/to/file1`
- `path/to/file2`
- `[subsystem or surface area if exact files are not yet known]`

## Acceptance Criteria

- [ ] [Binary, observable criterion 1]
- [ ] [Binary, observable criterion 2]
- [ ] [Automated tests cover the slice end-to-end]

## Blocked by

- [Issue reference] 

Or: `None - can start immediately`

---
**CRITICAL: Follow Test Driven Development and Tidy First workflows.**
- Write tests *before* writing implementation code.
- Clean up related code *before* adding new functionality.
```

## Issue Creation Summary Template

```markdown
## Issue Creation Summary

**System:** [e.g., GitHub/Beads]
**Plan:** [path/to/plan.md]

### Approved Slice Set
1. **[Title]** — [AFK|HITL], blocked by [None|IDs]
2. **[Title]** — [AFK|HITL], blocked by [None|IDs]

### Summary
- **Total Issues Created:** [count]
- **Dependencies Defined:** [count]
- **Labels Applied:** [e.g., needs-triage]

### Created Issues
1. **[ID] [Title]** - [Link/Reference]
2. **[ID] ...**

### Verdict: [ISSUES_CREATED | FAILED_TO_CREATE | WAITING_FOR_APPROVAL]
**Rationale:** [1-2 sentences explaining the result]
```


---