Create Github Issues

create-github-issues

Create a GitHub Epic and child Issues from conversation context. Write concise, length-capped bodies (requirements separated from specs), model dependencies explicitly, then link hierarchy and dependencies via native gh CLI flags and render the dependency graph in the Epic.

Core rule that governs every step below: an Issue body may only contain facts already surfaced and approved earlier in this flow (Step 1.5 / Step 2 / Step 3). Step 4 is formatting, not authoring — never introduce a new requirement, spec detail, or dependency for the first time while writing the final Markdown body. If you notice you need to state something new while writing a body, stop, go back to Step 3, and get it approved there first.

Step 1: Identify Repository

Check $ARGUMENTS:

• If repo <owner/repo> is provided, use that repository.
• Otherwise, auto-detect from the remote URL:

git remote get-url origin

Extract owner/repo from https://github.com/owner/repo.git or git@github.com:owner/repo.git and store it as REPO.

Step 1a: Determine Output Language

Check $ARGUMENTS for lang <ja|en> and store it as LANG; default to ja if omitted (preserves existing behavior).

LANG is fixed for the rest of this run and governs everything produced from here on — AskUserQuestion prompts, summaries, reviews, warnings, Issue/Epic titles, and Issue/Epic bodies. From Step 1.5 through Step 6, read only references/templates.<LANG>.md — never the other language's file, and never switch languages mid-run.

Step 1.5: Specification Clarification

Scan the conversation context across three axes and determine whether enough information is available to write high-quality Issues.

Evaluation Axes

Decision Branches

All axes are clear: Skip to Step 2. Do not ask any questions.

One or more axes are unclear: Use AskUserQuestion to surface the ambiguities, following the "Step 1.5: Clarification Question Format" template in references/templates.<LANG>.md — use only the labeled subsection(s) for the axis/axes actually unclear, not all three unconditionally. For each unclear item, present specific answer choices (e.g., "(A) include JWT refresh in the same Issue / (B) split into a separate Issue"). Batch all unclear items into a single AskUserQuestion call (up to 4 questions); if more than 4 items are unclear, prioritize the ones with the highest impact on Issue scope.

Stop after calling AskUserQuestion. Do not proceed to Step 2 until the user has responded.

User instructs to proceed with unresolved items: Output the warning using the "Step 1.5: Warning Format" template in references/templates.<LANG>.md, then proceed to Step 2. Mark unresolved sections in Issue bodies with the confirmation tag defined in that template.

Anything that stays unresolved after this step must not be silently decided later. Either it gets the confirmation tag, or it gets left out of the Issue entirely — never invented.

Step 2: Structure Tasks and Dependencies

Analyze the current conversation context (recent plans, investigations, TODO lists) and extract:

Epic (parent Issue)

• Title: one phrase that captures the entire work stream
• Purpose: why this work is needed (background, motivation)
• Scope: what is included in this Epic

Child Issue list

• Hierarchy is at most three levels: Epic → Tn → Tn.m. A Tn.m is never a parent. Every Tn is a leaf by default, carrying its own Requirements/Specs/Verification. When a Tn overflows the 5-bullet cap in Step 4, split it into a sibling Tn by default — for fragments the Epic-level reader would find independently interesting, or when there are only two. Split into Tn.m grandchildren instead only when three or more fragments share one cohesive theme already named by the original Tn. In that case Tn becomes a pure container: it drops its own Requirements/Specs/Verification and keeps only background, scope, and a dependency diagram of its Tn.m children — see Step 4's Container Tn body. A Tn.m is never split further; that overflow becomes a new sibling Tn instead.
• Split each task into independently implementable and verifiable units
• Assign each a short temporary ID: T1, T2, T3, ... (used only during this conversation; never shown to the end reader)
• Title and a one-line summary of each task's role in the Epic
• For each task, capture its requirement bullets (what must be true — observable/functional, no implementation detail) and its spec bullets (only if the conversation already settled concrete technical decisions). Cap each list at 5, one line each.
• The cap is a split signal, not a compression target. If a task genuinely needs more than 5 bullets to describe — or, as shown at Step 4, more than 5 distinct verification scenarios (one happy path plus several failure/retry/rollback cases is a common trigger) — that is evidence the task is doing too much for one child Issue. Split it into more Tn (e.g. "happy path" vs "error handling / compensating recovery") rather than cramming everything into one Issue or silently dropping items to fit the cap.
• Never write step-by-step procedures (a→b→c→d), pseudocode, or function-level implementation detail into these bullets. That level of detail belongs in a design doc, not an Issue body — reference it by path instead.

Dependency extraction

• For each Tn, list depends_on: [Tm, ...] based only on dependencies explicitly stated or clearly implied in the conversation (e.g., "merge A before starting B"). Do not infer a dependency that wasn't actually discussed. A statement that a task is merely independent of unrelated existing code (not another Tn) is not a depends_on entry — leave it out of the dependency list entirely; it's background/requirement framing at most.
• A grandchild Tn.m's depends_on may only reference sibling Tn.m under the same parent Tn — never a different Tn's child, and never a Tn itself. If work genuinely depends on something in a different theme, that dependency belongs at the Tn level (the whole container depends on the whole other theme), not wired directly between grandchildren across trees.
• Compute waves by topological order: Wave 1 = tasks with no dependencies; Wave k = tasks whose dependencies all fall in Wave 1..k-1. Tasks in the same wave can be implemented in parallel.
• If a cycle is detected, treat it as an unresolved ambiguity and raise it via AskUserQuestion before continuing — do not silently break the cycle.
• If splitting a task per the cap rule above, and another Tn already depends on the task being split, re-wire that dependency: point it at whichever new piece represents the completion of the original scope (usually the last piece in the split's natural sequence). If it's genuinely ambiguous which piece satisfies the original dependency, depend on all of the resulting pieces rather than guessing one.
• A dependency between the new pieces created by a split (e.g., "error handling" depends on the "happy path" it wraps) may be inferred from the decomposition itself — this is not the kind of invented dependency the "do not infer" rule above is guarding against, since the pieces didn't exist as separate units in the conversation to begin with.
• The 12-task threshold above governs rendering only (Mermaid vs. table) — it says nothing about whether one Epic is still the right unit of work. Separately: if the dependency graph splits into two or more fully independent connected components (no depends_on edge between them in either direction) and the total child count is large (rule of thumb: 15+), that's a sign the work may belong in separate Epics — one per component — rather than one Epic covering several unrelated parallel tracks. Don't decide this yourself: note it as a suggestion in the Step 3 summary (see template) and let the user choose.

Step 3: Show Summary and Get Approval

Use the "Step 3: Summary Format" in references/templates.<LANG>.md. This preview must show, per task: its Tn id, title, wave/dependency, one-line background, requirement bullets, spec bullets, one-line target state, and the full verification bullet list (up to 5) — plus a dependency preview keyed by Tn (real Issue numbers don't exist yet), and, for the Epic, its own one-line background and scope (included/excluded). Apply the same 12-task threshold as the Epic body here: a Mermaid flowchart for 12 or fewer tasks, the compact wave table for more — the user is approving the same structure that Step 4 will render, so the two must never diverge in form.

This preview is allowed to be more detailed than the final Issue bodies — its job is to surface every piece of content that will end up in an Issue, so nothing new gets invented in Step 4. Because Step 4.5's full-body review is skipped by default (see Step 4.5), this is the substantive approval gate: it must carry enough detail that approving it is equivalent to approving the final bodies, not just their shape.

End your response here and wait for the user's reply. Do not proceed to Step 4 until approval is received. If the user requests changes, update the summary (including the dependency graph and wave assignment if affected) and show it again before proceeding.

Step 4: Generate Issue Bodies

After approval, write the Markdown body for the Epic and each child Issue using the templates in references/templates.<LANG>.md. Use only content already approved in Step 3 — do not add, soften, or elaborate on requirements/specs while formatting.

Leaf Issues — every non-container Tn, and every Tn.m:

• Requirements section: the approved requirement bullets, verbatim in substance (may be copy-edited for clarity, not expanded).
• Specs section: the approved spec bullets. Omit this section entirely if no technical decision was actually settled in the conversation — do not fill it with invented detail.
• Dependencies section: one line referencing the sibling it depends on, or the template's "none" phrasing. Which parent it points to differs by level:
  • Tn: points to the Epic for the full dependency picture.
  • Tn.m: points to its parent Tn's body instead — the Epic never shows grandchildren, per Step 2's dependency-scope rule. Don't restate the full dependency chain here; that lives only in the parent.
• Acceptance Criteria section: concrete, verifiable statements equivalent to "Given X, When Y, Then Z", not vague phrases like "works correctly". Cap the Verification subsection at 5 items. If the real scenarios don't fit in 5, don't compress them: go back to Step 2, split this task into more siblings or grandchildren, and re-run Step 3 approval before writing bodies again.

Container Tn — only when Step 2 promoted it:

• No Requirements, Specs, or Acceptance Criteria section — those live only on its Tn.m leaves.
• Background and Scope sections, same shape as the Epic's but scoped to this one theme: what the grouped Tn.m children cover.
• Dependencies & Sub-tasks section: a small Mermaid flowchart grouping its own Tn.m children by wave, using {{Tn.m}} tokens. Past 12 grandchildren, use the wave table instead — same threshold as the Epic, rarely reached in practice. Scoped to this container only: never another Tn's children, and the Epic's own diagram still shows this Tn as a single node, exactly like a leaf.

Epic:

• Dependencies & Parallel Execution Plan section: a Mermaid flowchart grouping child Issues into subgraph blocks per wave, using {{Tn}} tokens (double curly braces) everywhere a real Issue number will later be substituted — both in node labels and in any prose. If there are more than 12 child Issues, replace the flowchart with the compact wave table in references/templates.<LANG>.md instead — a graph that large stops being readable.
  • Escaping in node labels: if a title contains a double quote, write it as the entity code #quot; inside the ["..."] label — never a raw " (it terminates the label) and never a backslash-escaped \" (Mermaid does not support backslash escaping and the diagram fails to render). Same rule applies to the Step 3 dependency preview.
• This diagram is a rendering of the same depends_on/wave data that Step 5 also uses to set native GitHub blocked-by/blocking relations on each child Issue. Both are generated once, from the same approved data, in the same run — the diagram is a human-readable view, not a hand-maintained duplicate that can drift from the real relations after creation.

Do not use any {{Tn}} or {{Tn.m}} token in a leaf body (a non-container Tn, or any Tn.m) — leaves stay abstract (T1, not {{T1}}) and are never rewritten after creation. Only the Epic body ({{Tn}} tokens) and a container Tn's own body ({{Tn.m}} tokens for its own children only) get a substitution pass, both in Step 5.

Step 4.5: Full Draft Review (only if requested)

By default, skip this step: go straight from Step 3's approval to Step 4.6 validation and then Step 5, without re-displaying the generated bodies. Run this step only when the user explicitly asks to see the full draft before creation (e.g. "ドラフト見せて", "本文を確認したい", "show me the draft") — whether that request is part of their Step 3 approval reply or said earlier in the conversation.

When triggered, use the "Step 4.5: Body Review Format" template in references/templates.<LANG>.md to display the Epic and all child Issues in order. Note explicitly that {{Tn}} tokens in the Epic body are placeholders that will be replaced with real Issue numbers (#123) once the child Issues exist.

Stop after presenting. Do not proceed to Step 4.6 until the user explicitly approves.

If the user requests changes, apply them and re-display the updated bodies before proceeding.

Step 4.6: Automated Pre-Creation Validation

Always run this step, whether or not Step 4.5 ran — it is the safety net that replaces routine human re-review of the mechanical formatting Step 4 performs. Check the generated bodies programmatically; there is no need to show them to the user unless a check fails:

• Every leaf Issue's (non-container Tn, or any Tn.m) Requirements / Specs / Verification bullet lists stay within the 5-item cap.
• No Mermaid node label (Step 3 preview, Epic body, or a container Tn body) contains a raw " — a title with a quote must use #quot; instead.
• Leaf bodies never contain a {{Tn}} or {{Tn.m}} token — that substitution syntax is container-body-only (the Epic for its Tn tokens, a container Tn for its own Tn.m tokens).
• Collect every {{Tn}} token appearing anywhere in the Epic body (diagram/table node labels, dependency-column references, prose) and confirm that set of ids exactly matches the set of Tn (leaf and container alike) about to be created — none missing, none referring to a Tn that doesn't exist. Separately, for each container Tn, collect every {{Tn.m}} token in its own body and confirm that set exactly matches the set of its own Tn.m grandchildren — none missing, none referring to a different container's child. A given id may legitimately appear more than once within its own scope (e.g. once as its own row, again in another row's dependency column), so check set membership, not occurrence count.

If any check fails, stop, report the specific problem and its location to the user, and fix it before proceeding. Never silently patch it and never create Issues with a body known to be broken.

Step 5: Create Issues

See references/commands.md for the exact shell commands.

The Epic is created first, since --parent needs it to already exist. Every Tn — leaf or container — is created next in wave order, each with --parent $EPIC_NUM and --blocked-by <already-known real numbers>; never --parent pointing at another Tn, per the hierarchy rule in Step 2. A container Tn's own body still carries unsubstituted {{Tn.m}} tokens at this point, since its grandchildren don't exist yet. Once every Tn exists, create each container's Tn.m grandchildren with --parent set to that Tn's real number and --blocked-by limited to sibling Tn.m it depends on — never a Tn, never a different container's child, per Step 2's dependency-scope rule.

Substitution then happens bottom-up: for each container Tn, substitute its own body's {{Tn.m}} placeholders with the real grandchild numbers and update it via gh issue edit, before touching the Epic. Only after every container is updated, substitute the Epic body's {{Tn}} placeholders — leaf and container alike — and update the Epic. Before each gh issue edit, confirm no token remains in that body's scope; if one does and the failure case below doesn't explain it, the substitution missed it — fix it before submitting.

If a Tn's creation fails, skip creating its would-be Tn.m grandchildren entirely — there is no valid parent for them — flag it in the Step 6 report, and replace its {{Tn}} reference in the Epic body with a short inline note such as "creation failed". If a Tn.m's creation fails instead, its container is still created/updated normally; replace only that grandchild's {{Tn.m}} reference in the container's own body with the same note. Neither failure aborts the rest of the run.

A failed Tn/Tn.m never gets a real number, so any not-yet-created sibling whose depends_on names it must drop that id from its own --blocked-by list — never pass a number that doesn't exist. Note the dropped edge in the Step 6 report so the user knows that dependency was never wired, rather than silently creating an Issue that was supposed to wait but isn't blocked on anything.

Note in the completion report (Step 6) that the Epic's number is lowest, Tn numbers come next in wave order, and each container's Tn.m numbers come after their parent.

Step 6: Report Completion

Use the "Step 6: Completion Report" template in references/templates.<LANG>.md.