# To Issues > Breaks a plan, spec, PRD, or conversation into independently-grabbable GitHub issues using tracer-bullet vertical slices, then publishes them as native sub-issues under a parent tracking issue via the gh CLI. - Skill: `samuelpatro/to-issues` (Agent Skill) - Install (CLI): `npx skillmds@latest add samuelpatro/to-issues` - Raw SKILL.md: https://api.skillmd.com/api/skills/samuelpatro/to-issues/raw - Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning, Prioritization & Backlog - Tags: Gh Cli, Github, Issues, Planning, Sub Issues, Tracer Bullet, Vertical Slices - Author: samuelpatro (https://skillmd.com/u/samuelpatro) - Updated: 2026-08-22 - Page: https://skillmd.com/skills/samuelpatro/to-issues --- # To Issues Break a plan into independently-grabbable GitHub issues using vertical slices (tracer bullets), then publish them as native sub-issues under a parent tracking issue. The aim is issues an agent or teammate can pick up and finish without needing the rest of the plan in their head. This skill talks to GitHub directly via the `gh` CLI. It infers the repo from the clone's `git remote`, so run it from inside the target repository. If `gh` isn't authenticated, stop and ask the user to run `gh auth login` (suggest they type `! gh auth login` in the prompt). ## Process ### 1. Gather context Work from whatever is already in the conversation. If the user passes an issue reference (number, URL, or a file path to a plan/PRD), fetch and read it fully: ```bash gh issue view --comments ``` If the source is an existing issue, it becomes the parent in step 5. ### 2. Explore the codebase (when it helps) If you haven't already, explore the repo enough to ground the issues in reality. Issue titles and descriptions should use the project's actual domain vocabulary and respect existing conventions and architecture in the area you're touching. Concrete, codebase-aware issues beat generic ones. ### 3. Draft vertical slices Break the plan into **tracer-bullet** issues. Each issue is a thin vertical slice that cuts end-to-end through ALL integration layers, NOT a horizontal slice of one layer. - Each slice delivers a narrow but COMPLETE path through every layer it touches (schema, API, UI, tests). - A completed slice is demoable or verifiable on its own. - Prefer many thin slices over few thick ones. Mark each slice **AFK** (can be implemented and merged with no human interaction) or **HITL** (needs human input first, e.g. an architectural decision or design review). Prefer AFK where possible; pull the human-judgment parts into their own HITL slices so the rest can proceed unblocked. ### 4. Quiz the user before publishing Present the breakdown as a numbered list. For each slice show: - **Title** — short, descriptive - **Type** — AFK / HITL - **Blocked by** — which other slices must land first (if any) - **Covers** — which user stories / goals it addresses (if the source has them) Then ask: - Does the granularity feel right? (too coarse / too fine) - Are the dependencies correct? - Should any slices be merged or split further? - Are the AFK / HITL markings right? Iterate until the user approves. Do not create any issues before approval. ### 5. Publish to GitHub Publish in **dependency order (blockers first)** so each issue can reference the real numbers of the issues that block it. **a. Pick labels — adapt to the repo.** List what already exists and reuse fitting labels rather than inventing new ones: ```bash gh label list --limit 100 ``` Map slices onto sensible existing labels (e.g. an `enhancement`/`feature` label, a `needs-decision`/`blocked` label for HITL). If a genuinely useful label is missing, **ask the user before creating it** (`gh label create "" --color --description "..."`). Never silently invent labels. **b. Create the parent tracking issue.** If the source was an existing issue, use it as the parent. Otherwise create one that frames the whole effort and will hold the slices as sub-issues: ```bash gh issue create --title " — tracking" --body "$(cat <<'EOF' ## Overview ## Slices (sub-issues are linked below once created) EOF )" ``` Capture the parent number from the returned URL. **c. Create each slice issue** using the template below. Capture each new issue's number and its REST id (the sub-issues API needs the id, not the number): ```bash gh issue create --title "" --body "$(cat <<'EOF' EOF )" --label "" # then resolve the numeric id for the sub-issue link: gh api "repos/{owner}/{repo}/issues/" --jq '.id' ``` **d. Attach each slice as a native sub-issue of the parent:** ```bash gh api --method POST "repos/{owner}/{repo}/issues//sub_issues" \ -F sub_issue_id= ``` If the sub-issues endpoint is unavailable on the repo/plan, fall back gracefully: add a `## Sub-issues` task list to the parent body (`- [ ] #`) and tell the user native sub-issues weren't available, so they know why. Do NOT close or modify the parent's original content beyond adding the slice links. ### 6. Report back Give the user the parent issue URL and a short list of the created slice numbers with their titles and dependency order, so they can see the whole tree at a glance. ## Issue body template ## What to build A concise description of this vertical slice. Describe the end-to-end behavior, not a layer-by-layer implementation plan. Avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype or prior discussion produced a snippet that encodes a decision more precisely than prose can (a state machine, reducer, schema, or type shape), inline just the decision-rich part and note where it came from. ## Acceptance criteria - [ ] Criterion 1 - [ ] Criterion 2 - [ ] Criterion 3 ## Blocked by - # (the blocking slice), or "None — can start immediately" ## Anti-patterns - **Horizontal slices.** "Build all the API endpoints" then "build all the UI" is not a tracer bullet. Each issue must reach through every layer it needs. - **Publishing before approval.** Always quiz the user first (step 4). - **Inventing labels silently.** Reuse the repo's labels; ask before creating new ones. - **File paths and code dumps in issue bodies.** They rot. Describe behavior and acceptance criteria instead. - **Touching the parent issue's existing content.** Only add sub-issue links; never close or rewrite it.