plan-tickets

name	plan-tickets
description	Use when the user asks to plan a feature or change by breaking it into GitHub Issues for this repo's ticket tracker. Triggers: "plan this feature", "break this into tickets", "create tickets for", "draft tickets", "what tickets do we need".

Planning and creating tickets

The output of planning here is GitHub Issues, not code. Planning ends when the tickets exist with priorities and dependencies set. Do not begin implementing in the same session — implementation is a separate ticket-driven loop (see the work-on-ticket skill).

Every planned feature lands as a single top-level issue. How that issue is structured depends on size:

• Single-ticket feature — the top-level issue is the implementation ticket. Its body carries the implementation plan and work-on-ticket picks it up directly.
• Multi-ticket feature — the top-level issue is a tracking issue. The units of work are GitHub sub-issues attached via the native sub-issues API. The tracking issue stays open until the last sub-task's commit lands on main.

1. Design the plan

Break the work into tickets sized so each can be implemented in roughly one commit and reviewed as one PR. If a ticket feels too large to review in one sitting, split it.

Decide single vs. multi: does the feature fit in one commit-sized ticket, or does it need to be broken up? If unsure, default to single-ticket — splitting later is cheap.

For multi-ticket plans, identify which sub-tasks block which — the dependency graph matters for prioritization.

2. Get user acceptance

Walk the user through the proposed shape (single ticket, or tracking issue + sub-tasks) before writing anything to GitHub. Capture corrections; do not create issues for a plan the user hasn't agreed to.

3. Create the top-level issue

Always create this first.

gh issue create \
  --title "Imperative-voice title here" \
  --body  "Description of what the feature is and why" \
  --label P2

Title in imperative voice ("Add X", "Refactor Y", "Fix Z").

• Single-ticket feature: the body also contains the implementation plan — the detail that would have gone in a normal ticket. This issue is the work item. Skip to step 7 for the priority label, then stop.
• Multi-ticket feature: the body describes the feature and lists the planned sub-tasks as human-readable bullets (sub-issues will also render natively on the issue page). This issue is the tracking parent; it is not implemented directly. Continue to step 4.

4. Create sub-task issues (multi-ticket only)

One gh issue create per commit-sized unit. Each sub-task body should include the implementation detail for that unit and a Part of #<tracking> line for grep-ability.

5. Link sub-tasks to the tracking issue (multi-ticket only)

Use GitHub's native sub-issues API so the parent renders the sub-issue list and progress bar. The endpoint takes the sub-issue's internal id, not its issue number:

# Look up the sub-issue's internal id
SUB_ID=$(gh api repos/:owner/:repo/issues/<sub_number> --jq '.id')

# Attach to the tracking issue
gh api repos/:owner/:repo/issues/<parent_number>/sub_issues \
  -f sub_issue_id=$SUB_ID

Docs: https://docs.github.com/en/rest/issues/sub-issues

6. Set ordering dependencies (multi-ticket only)

Sub-issues express hierarchy, not order. If sub-task B can't start until sub-task A is done, also record that with the issue dependencies API so work-on-ticket's -is:blocked filter sees it.

Docs: https://docs.github.com/en/rest/issues/issue-dependencies?apiVersion=2026-03-10

7. Assign priority labels

• P1 — bugs or critical features.
• P2 — default.
• P3 — nice-to-have.

Apply to the top-level issue and to every sub-task. For tracking issues, the parent's priority should equal the highest priority among its sub-tasks so it surfaces correctly in work-on-ticket's candidate list.

8. Stop

Planning is done once the tickets exist with priorities and dependencies set, and (for multi-ticket features) sub-issues are linked. Do not begin implementing in the same session. Hand the work back to the user; they (or a future session via work-on-ticket) will pick up implementation.

Conventions

• Title in imperative voice ("Add X", "Refactor Y", "Fix Z").
• One sub-task per commit-sized unit of work.
• For single-ticket features, the top-level issue is the implementation issue — no separate sub-tasks.
• Tracking issues are not closed manually. The final sub-task's commit message resolves both the sub-task and the tracking issue (see work-on-ticket); landing on main closes both.