SuperAPI AI Directory

create-issue-tree

General & other

View repository

Updated 10-15 22:11

About this skill

create-issue-tree

Newly create a Phase-divided GitHub Issue tree from requirements and a task list. Build the 4-level hierarchy of root (tracking issue) → Phase parent issue → issue → sub-issue, and maintain a structure that implement-issue-tree can consume via post-order DFS.

The operational rule in the root issue body, "execution order follows the order of the sub-issues list", by default remains only a post-orderpriority, and during parallel execution there is room for a later Phase to overtake the previous Phase. If you want to strictly guarantee Phase completion order, when running implement-issue-tree specify phaseGate: true (see implement-issue-tree's SKILL.md).

Usage

Pass task requirement text or a file path as an argument.
--phase You can also file only a specific Phase with the option (when filing a large tree in stages).
For the second and subsequent partial filings, pass the existing root issue number with --root to append to the same tree (if not specified, a new root issue will be created in duplicate).
--milestone The option allows you to specify a GitHub Milestone to assign to all filed issues (when--root is specified, it can be omitted. The milestone of the existing root is automatically inherited). --granularity The option allows you to specify the upper limit of implementation time to fit into 1 issue. 2h・4h・1h Specify as a positive integer + time unit (h) such as. The priority order is --granularity explicit > --root existing root issue body marker when specified > default 2h in that order (determined in Step 1). The determined value is persisted in the root issue body as <!-- granularity: Nh --> , and is inherited when update-issue-tree is run for the same root.

create-issue-tree "ユーザー認証機能を実装する"
create-issue-tree requirements.md
create-issue-tree requirements.md --phase 2 --root 123
create-issue-tree requirements.md --milestone "v2.0"
create-issue-tree requirements.md --granularity 4h

Prerequisites

  • gh The CLI is installed and authenticated (check withgh auth status )
  • You have Issue write permission for the target repository

Flow

Step 1: Analyze requirements and decompose tasks

Read the requirements from the input text or file, and decompose tasks from the following perspectives.

  • Granularity guideline: 1 issue should fit within roughly ${GRANULARITY}of implementation (default 2h, changeable with--granularity ). If judged to exceed, re-decompose into sub-issues

--granularity The value of is also verified on Claude's side before assignment using the same regular expression (^[1-9][0-9]*h$), and if it does not match,do not execute this fenceand ask the user to respecify (do not embed untrusted values into an already-generated shell). The priority order is as in the Usage section:--granularity > root's marker > default 2h in that order.

# --granularity で渡された時間を実際の値で代入する(実行時に Claude が置き換える)
# 例: --granularity 4h が指定された場合 → GRANULARITY_ARG="4h" / 未指定の場合は空文字
GRANULARITY_ARG="<--granularity で渡された時間(未指定なら空文字)>"
# --root で渡された Issue 番号(未指定なら空文字)。Step 2.5 で ROOT_NUMBER として
# OPEN 検証込みで正式に確定する前に、粒度継承の参照のためここでも読む
ROOT_ARG="<--root で渡された Issue 番号(未指定なら空文字)>"

if [[ -n "${GRANULARITY_ARG}" ]]; then
  GRANULARITY="${GRANULARITY_ARG}"
  GRANULARITY_SOURCE="--granularity 引数"
elif [[ -n "${ROOT_ARG}" ]]; then
  # ルート本文の取得失敗とマーカー不在は分離する。取得失敗は「粒度を既定へ倒さず中止」する
  # (gh issue view 自体の失敗を || true で握り潰すと、権限エラー・issue 不在等を
  # 「マーカーなし」と誤読して既定 2h へサイレントに倒れてしまうため)
  ROOT_BODY=$(gh issue view "${ROOT_ARG}" --json body --jq '.body') \
    || { echo "エラー: ルート issue #${ROOT_ARG} の本文を取得できません。粒度を既定へ倒さず中止します。"; exit 1; }
  # 既存ルート本文の <!-- granularity: Nh --> マーカーから継承する。マーカーが無ければ既定 2h
  # (|| true は grep のマーカー不在にのみ掛かる。gh issue view 自体の失敗は上で既に処理済み)
  ROOT_GRANULARITY=$(printf '%s\n' "${ROOT_BODY}" \
    | grep -oE '<!-- granularity: [1-9][0-9]*h -->' | head -1 | grep -oE '[1-9][0-9]*h' || true)
  if [[ -n "${ROOT_GRANULARITY}" ]]; then
    GRANULARITY="${ROOT_GRANULARITY}"
    GRANULARITY_SOURCE="ルート issue #${ROOT_ARG} のマーカー"
  else
    GRANULARITY="2h"
    GRANULARITY_SOURCE="既定値"
  fi
else
  GRANULARITY="2h"
  GRANULARITY_SOURCE="既定値"
fi

# 許可する構文は正整数 + h のみ(例: 1h / 2h / 4h)。引用符・空白・コマンド置換・0h・単位なしは
# ここで拒否する(ROOT_GRANULARITY はマーカー抽出時点で同じ正規表現を通しているが、
# GRANULARITY_ARG はユーザー入力の生値のため、代入元によらずこの検証を必ず通す)
if ! printf '%s' "${GRANULARITY}" | grep -qE '^[1-9][0-9]*h$'; then
  echo "エラー: --granularity の値 '${GRANULARITY}' は不正です(許可: 正整数+h、例 2h)。中止します。"
  exit 1
fi

# 確定値と由来を必ず出力する(既定 2h と読み替えないことをここで可視化する)
echo "粒度基準: ${GRANULARITY}(由来: ${GRANULARITY_SOURCE})"

The subsequent Steps use the GRANULARITY Use the value of (do not reinterpret it as the default 2h).

  • Understand each task's dependencies and execution order
  • Count the number of tasks and determine whether Phase splitting is necessary (guideline: consider Phase splitting when there are more than 10 tasks)

Present the decomposition results to the user and confirm the Phase structure and number of issues.
--phase If the option is specified, only target the tasks of the corresponding Phase.

Step 2: Design the Phase structure

Design Phases based on the number of tasks and dependencies.

  • Split Phases into units that can be developed independently (e.g., Phase 1 foundation, Phase 2 features, Phase 3 improvements)
  • Assign a parent issue title (Conventional Commits format recommended) to each Phase
  • Determine the title of the root (tracking) issue that ties everything together
    • Example: chore(global): 全 open issue の Phase 別トラッキング (YYYY-MM-DD)

If there are few tasks (no Phase splitting needed), use a two-level structure of root issue + child issues.

Step 2.5: Determine the milestone

Determine the GitHub Milestone to assign to this tree. Apply the same milestone to all items: the root, Phase parents, children, and sub-issues (one milestone per tree).

--root If is specified, first set ROOT_NUMBER here, and validate the OPEN state before inheriting or writing the milestone (to prevent the accident of rewriting the milestone of a closed root and then aborting. Step 3 does not reassign or revalidate).

# --root で渡された Issue 番号を実際の値で代入する(実行時に Claude が置き換える)
# 例: --root 123 が指定された場合 → ROOT_NUMBER="123" / --root 未指定の場合 → ROOT_NUMBER=""
ROOT_NUMBER="<--root で渡された Issue 番号(未指定なら空文字)>"

# --root 指定時のみ: OPEN でなければ milestone 操作より前に中止する
# (新規ツリー作成で ROOT_NUMBER が空の場合はこの検証をスキップする)
if [[ -n "${ROOT_NUMBER}" ]]; then
  ROOT_STATE=$(gh issue view "${ROOT_NUMBER}" --json state --jq '.state')
  if [[ "${ROOT_STATE}" != "OPEN" ]]; then
    echo "エラー: ルート issue #${ROOT_NUMBER} は OPEN ではありません (state: ${ROOT_STATE})。中止します。"
    exit 1
  fi
fi

Guard for repositories not using milestones: --milestone If is not explicitly specified and the repository has no milestones at all (including closed), treat it as a repository not using milestones, skip all subsequent confirmations, and proceed to Step 3 with MILESTONE left empty (do not add confirmations to the issue creation flow of repositories that do not use milestones).

MILESTONE_COUNT=$(gh api "repos/{owner}/{repo}/milestones?state=all" --jq 'length')
# MILESTONE_COUNT が 0 かつ --milestone 未指定なら、このステップの残りをスキップする

Priority order is --milestone > --root inheritance from > confirmation with the user in that order.

  • --milestone If is specified: use that value as-is as MILESTONE (if--root is also specified at the same time, prioritize --milestone over the root's milestone. If it differs from the root's value, confirm with the user whether the root's milestone may also be updated. If the user answers not to update it, inform them that milestones will be mixed within the tree, then continue)

  • --milestone If is unspecified and --root is specified: automatically inherit the existing root's milestone (no confirmation with the user is needed only if the milestone could be retrieved)

    MILESTONE=$(gh issue view "${ROOT_NUMBER}" --json milestone --jq '.milestone.title // empty')
    

    MILESTONE If is empty (the existing root has no milestone set), do not treat it as automatic inheritance; proceed to the same user confirmation flow as "when neither is specified" (do not silently proceed without a milestone when the repository has milestones. If there are no milestones at all, the non-operational guard at the beginning takes effect first, so this confirmation is not reached).

  • If neither is specified, or --root If the milestone to be inherited is empty when specified: Ask the user whether to assign a milestone. If assigning, present the list of open milestones and have the user select one, or accept input of a new milestone name and MILESTONE set it to . If the user answers not to assign, MILESTONE remains empty and proceed to Step 3 and later (the issue is created without a milestone).

    gh api "repos/{owner}/{repo}/milestones" --jq '.[] | select(.state=="open") | .title'
    

    If the user enters a new milestone name not in the list,gh issue create --milestone only accepts existing milestone names, so create the milestone itself before use. If a closed milestone with the same name already exists, creation fails with 422 (already_exists), so in that case ask the user whether to reopen it or use a different name.

    gh api --method POST "repos/{owner}/{repo}/milestones" -f "title=${MILESTONE}"
    

    --root When the milestone to be inherited is empty when specified and this flow is joined, reflect the decided MILESTONE on the existing root issue as well (this prevents the inconsistency where only children have the milestone and the root remains unset).

    if [[ -n "${ROOT_NUMBER}" && -n "${MILESTONE}" ]]; then
      gh issue edit "${ROOT_NUMBER}" --milestone "${MILESTONE}"
    fi
    

Step 3: Create the root (tracking) issue

Create the root issue as a tracking issue that manages the progress of the entire tree.Do not assign a phase label to the root issue itself(assign it only to issues under the Phase parent).

--root When specified, skip the new creation. --phase In the second and later partial filings with , in order not to duplicate-create the root issue, reuse as-is the ROOT_NUMBER that was set and verified as OPEN in Step 2.5 (do not reassign or re-verify here).

--root Only when is not specified, create a new root issue as follows. The placeholder row in the table is read by scripts/merge-root-body.sh(Step 6 の --root route) as the append position. When changing the wording, also fix the awk and test (n) in the same script accordingly.

# MILESTONE が空でなければ --milestone を付与する(Step 2.5 で決定済み)
ROOT_ARGS=(--title "chore: 全 open issue の Phase 別トラッキング ($(date +%Y-%m-%d))")
if [[ -n "${MILESTONE}" ]]; then
  ROOT_ARGS+=(--milestone "${MILESTONE}")
fi

# gh issue create は issue URL を stdout に出力する(--json 非対応)。URL 末尾から番号を抽出する
ROOT_URL=$(gh issue create "${ROOT_ARGS[@]}" \
  --body "$(printf '<!-- granularity: %s -->\n' "${GRANULARITY}"; cat <<'EOF'
## 概要

全 open issue を Phase 別に 1 ツリーへ整理する。各 Phase 親 issue を sub-issues として紐付け。

## Phase 別実装計画

| Phase | 親 issue | 直下 | 総 open 件数 |
|-------|----------|------|-------------|
| (作成後に更新) | | | |

## 運用

- 新規 issue は起票時に Phase 親へ紐付ける
- 実行順は sub-issues リスト順が正
- closed 親の下に open issue を残置しない
- implement-issue-tree が post-order DFS で消化可能な構造を維持する
EOF
)")
ROOT_NUMBER=$(printf '%s' "${ROOT_URL}" | grep -oE '[0-9]+$')
echo "ルート issue: ${ROOT_NUMBER}"

Step 4: Create and link the Phase parent issue

Create a parent issue for each Phase and link it to the root via the sub_issues API. The following snippet switches the Phase number with the PHASE variable.--phase When specified, set that number; when filing all Phases, set the Phase number being processed (make both the title and labels follow PHASE ).

# 処理対象の Phase 番号(--phase 指定時はその番号、全 Phase 起票時はループ中の番号)
PHASE=1

# phase ラベルが存在しないリポジトリでは issue 作成が失敗するため、必ず事前作成する
# (作成済みの場合は失敗を無視して続行する)
gh label create "phase:${PHASE}" --color "0075ca" 2>/dev/null || true

# --root 再実行時の重複防止: ルート直下に同じ Phase の open な親が既にあれば再利用する
# closed な親は再利用しない(closed 親の下に open issue を残置しない運用ルールと整合させる)。
# phase ラベルだけでは同ラベルの一般 issue がルート直下に混在した場合に誤マッチするため、
# Phase 親のタイトル規約(feat(phase-N): 接頭辞)でも絞り込む。
# 直下が 100 件を超える場合に備えてページングで全件走査する
PHASE_NUMBER=""
PAGE=1
while true; do
  RESULT=$(gh api \
    "repos/{owner}/{repo}/issues/${ROOT_NUMBER}/sub_issues?per_page=100&page=${PAGE}")
  PHASE_NUMBER=$(echo "${RESULT}" | jq -r \
    "[.[] | select(.state == \"open\"
      and (.title | startswith(\"feat(phase-${PHASE}):\"))
      and any(.labels[]?; .name == \"phase:${PHASE}\"))][0].number // empty")
  COUNT=$(echo "${RESULT}" | jq 'length')
  if [[ -n "${PHASE_NUMBER}" || "${COUNT}" -lt 100 ]]; then break; fi
  PAGE=$((PAGE + 1))
done
[[ -n "${PHASE_NUMBER}" ]] && echo "既存の Phase 親 issue を再利用: #${PHASE_NUMBER}"

# 再利用する Phase 親が milestone 未設定の場合はここで揃える(milestone 導入前に
# 作られたツリーへの追記で、新規の子だけに milestone が付く不整合を防ぐ。冪等)
if [[ -n "${PHASE_NUMBER}" && -n "${MILESTONE}" ]]; then
  gh issue edit "${PHASE_NUMBER}" --milestone "${MILESTONE}"
fi

For trees whose title convention differs from feat(phase-N): , do not rely on the above automatic determination; present candidates to the user and confirm which Phase parent should be reused.

PHASE_NUMBER Only when is empty (there is no existing Phase parent), create a new one as follows and link it to the root.

# MILESTONE が空でなければ --milestone を付与する(Step 2.5 で決定済み)
PHASE_ARGS=(--title "feat(phase-${PHASE}): Phase ${PHASE} 基盤整備" --label "phase:${PHASE}")
if [[ -n "${MILESTONE}" ]]; then
  PHASE_ARGS+=(--milestone "${MILESTONE}")
fi

# Phase 親 issue を作成(URL 末尾から番号を抽出)
PHASE_URL=$(gh issue create "${PHASE_ARGS[@]}" \
  --body "$(cat <<'EOF'
## 概要

この Phase の実装タスクをまとめる親 issue。

## タスク一覧

| Issue | タイトル | 分解 |
|-------|---------|------|
| (子 issue 作成後に更新) | | |
EOF
)")
PHASE_NUMBER=$(printf '%s' "${PHASE_URL}" | grep -oE '[0-9]+$')

# ルートへ紐付け。sub_issue_id は issue 番号ではなく database id を渡す(GitHub sub-issues API 仕様)
PHASE_ID=$(gh api "repos/{owner}/{repo}/issues/${PHASE_NUMBER}" --jq '.id')
gh api \
  --method POST \
  "repos/{owner}/{repo}/issues/${ROOT_NUMBER}/sub_issues" \
  -F "sub_issue_id=${PHASE_ID}"

Step 5: Create and link child issues and sub-issues

Create each task as an issue and link it to the Phase parent. Tasks exceeding the granularity standard (default 2h,--granularity) are further broken down into sub-issues.

# MILESTONE が空でなければ --milestone を付与する(Step 2.5 で決定済み)
CHILD_ARGS=(--title "feat: タスク名" --label "phase:${PHASE}")
if [[ -n "${MILESTONE}" ]]; then
  CHILD_ARGS+=(--milestone "${MILESTONE}")
fi

# 子 issue を作成(URL 末尾から番号を抽出)。PHASE は Step 4 で設定した番号を引き継ぐ
CHILD_URL=$(gh issue create "${CHILD_ARGS[@]}" \
  --body "$(cat <<'EOF'
## 概要

...

## 受け入れ条件

- [ ] 条件1
- [ ] 条件2
EOF
)")
CHILD_NUMBER=$(printf '%s' "${CHILD_URL}" | grep -oE '[0-9]+$')

# Phase 親へ紐付け(sub_issue_id は database id)
CHILD_ID=$(gh api "repos/{owner}/{repo}/issues/${CHILD_NUMBER}" --jq '.id')
gh api \
  --method POST \
  "repos/{owner}/{repo}/issues/${PHASE_NUMBER}/sub_issues" \
  -F "sub_issue_id=${CHILD_ID}"

# 粒度基準(既定 2h・--granularity)超の場合は sub-issue を作成して子 issue へ紐付け(同じく MILESTONE を付与)
SUB_ARGS=(--title "feat: サブタスク名" --label "phase:${PHASE}")
if [[ -n "${MILESTONE}" ]]; then
  SUB_ARGS+=(--milestone "${MILESTONE}")
fi
SUB_URL=$(gh issue create "${SUB_ARGS[@]}" --body "...")
SUB_NUMBER=$(printf '%s' "${SUB_URL}" | grep -oE '[0-9]+$')

SUB_ID=$(gh api "repos/{owner}/{repo}/issues/${SUB_NUMBER}" --jq '.id')
gh api \
  --method POST \
  "repos/{owner}/{repo}/issues/${CHILD_NUMBER}/sub_issues" \
  -F "sub_issue_id=${SUB_ID}"

If there are many issues (a guideline is more than 50), use the per_page=100 parameter and check all of them via pagination.

# ページネーション例(全 sub-issues を取得)
PAGE=1
while true; do
  RESULT=$(gh api \
    "repos/{owner}/{repo}/issues/${PHASE_NUMBER}/sub_issues?per_page=100&page=${PAGE}")
  COUNT=$(echo "${RESULT}" | jq 'length')
  echo "${RESULT}"
  if [ "${COUNT}" -lt 100 ]; then break; fi
  PAGE=$((PAGE + 1))
done

Step 6: Update the root issue body with the per-Phase table

Once all issues have been created, update the Phase table in the root issue body with the actual issue numbers and counts.

--root When partially filing with , do not replace the entire body. Since the body of an existing root contains tables for preceding Phases, retrieve the current body and gh issue edit with a body that only appends/updates the rows and sections for the Phase filed this time. Full replacement is performed only when creating a new issue (--root unspecified), and that generation is scripts/create-root-body.sh に、 --root At merge time, leave it to scripts/merge-root-body.sh (do not write body generation logic into SKILL.md). Even for a root that is still the Step 3 template (re-running filing that was interrupted before reaching Step 6), replace the table's placeholder row | (作成後に更新) | with this Phase's row and finish.

--root When specified, scripts/merge-root-body.sh retrieves the existing body and generates and merges this Phase's rows/sections from the actual tree (Issue #556). Since each code fence may be executed in an independent shell, this fence resolves the script self-containedly from the 3 layouts, in the same form as Step 3 / Step 4. If ROOT_NUMBER (root issue number), GRANULARITY (granularity determined in Step 1), PHASE (Phase number N determined in Step 4), or PHASE_NUMBER (that Phase's parent issue number) is unset, stop before starting.

: "${ROOT_NUMBER:?ROOT_NUMBER 未設定}" "${GRANULARITY:?GRANULARITY 未設定}" \
  "${PHASE:?PHASE 未設定}" "${PHASE_NUMBER:?PHASE_NUMBER 未設定}"

MERGE_ROOT_BODY=""
for CANDIDATE in \
  "skills/create-issue-tree/scripts/merge-root-body.sh" \
  ".agents/skills/create-issue-tree/scripts/merge-root-body.sh" \
  ".claude/skills/create-issue-tree/scripts/merge-root-body.sh"; do
  # 存在確認は -f のみ(vendoring で実行ビットが落ちても bash 経由で起動できる)
  if [[ -f "${CANDIDATE}" ]]; then
    MERGE_ROOT_BODY="${CANDIDATE}"
    break
  fi
done
if [[ -z "${MERGE_ROOT_BODY}" ]]; then
  echo "エラー: merge-root-body.sh が見つからない(3 レイアウトいずれにも存在しない)" >&2
  exit 1
fi

# echo を最終コマンドにしない。非ゼロ終了はそのままフェンスの終了ステータスにする
status=0
bash "${MERGE_ROOT_BODY}" --root "${ROOT_NUMBER}" --granularity "${GRANULARITY}" \
  --phase "${PHASE}" --phase-number "${PHASE_NUMBER}" || status=$?
if (( status != 0 )); then
  echo "exit=${status}" >&2
  exit "${status}"
fi

Exit code(the last line of stdout on success is result=merged root=<n> phase=<N>. Error messages go to stderr)

exit Meaning Body update
0 Merge this Phase's portion into the existing body and gh issue edit succeeded Yes
1 Invalid argument (--root・--phase-number is a positive integer,--phase is a number,--granularity は ^[1-9][0-9]*h$), failure to retrieve existing body / Phase parent / sub_issues / descendants, no append position / cannot output Phase row, placeholder remaining / check failure, temp file creation failure No
2 Precondition not met (cannot readtree-lib.sh ,gh・jq is missing) No
Other gh issue edit 's own exit code Unknown (check the actual state)

Merge invariants: Phase rows/sections are created only from the actual tree (sub_issues API), and tables/free-text for preceding Phases are preserved / Issue titles are treated as untrusted data and |sanitize , newlines, and backslashes / do not gh issue edit on a body with placeholders remaining (fail-closed) / delete temp files regardless of success or failure / always rewrite the granularity marker with GRANULARITY. For details, see the scripts/merge-root-body.sh header comment.

--root When unspecified (new creation), scripts/create-root-body.sh generates and updates the body from the actual tree (Issue #555). Helpers (list_subs etc.) share scripts/tree-lib.sh in both paths.

In the same format, if ROOT_NUMBER and GRANULARITY are unset, stop before starting.

: "${ROOT_NUMBER:?ROOT_NUMBER 未設定}" "${GRANULARITY:?GRANULARITY 未設定}"

CREATE_ROOT_BODY=""
for CANDIDATE in \
  "skills/create-issue-tree/scripts/create-root-body.sh" \
  ".agents/skills/create-issue-tree/scripts/create-root-body.sh" \
  ".claude/skills/create-issue-tree/scripts/create-root-body.sh"; do
  # 存在確認は -f のみ(vendoring で実行ビットが落ちても bash 経由で起動できる)
  if [[ -f "${CANDIDATE}" ]]; then
    CREATE_ROOT_BODY="${CANDIDATE}"
    break
  fi
done
if [[ -z "${CREATE_ROOT_BODY}" ]]; then
  echo "エラー: create-root-body.sh が見つからない(3 レイアウトいずれにも存在しない)" >&2
  exit 1
fi

# echo を最終コマンドにしない。非ゼロ終了はそのままフェンスの終了ステータスにする
status=0
bash "${CREATE_ROOT_BODY}" --root "${ROOT_NUMBER}" --granularity "${GRANULARITY}" || status=$?
if (( status != 0 )); then
  echo "exit=${status}" >&2
  exit "${status}"
fi

Exit code(the last line of stdout on success is result=updated root=<n> phases=<k>. Error messages go to stderr)

exit Meaning Body update
0 Generate the body and gh issue edit succeeded Yes
1 Invalid argument (--root must be a positive integer,--granularity は ^[1-9][0-9]*h$), sub_issues retrieval failure, 0 Phase parents, Phase number undeterminable, descendant retrieval failure, placeholder remaining/inspection failure, Phase row count mismatch, temporary file creation failure No
2 Missing prerequisites (tree-lib.sh cannot be read,gh・jq is absent) No
Other gh issue edit own exit code Unknown (check the actual state)

Generation invariants: the table is created only from the actual tree (sub_issues API) / issue titles are treated as untrusted data and |, newlines, and backslashes are sanitized / in a body where placeholders remain, gh issue edit do not (fail-closed) / temporary files are deleted regardless of success or failure. For details, see the comment at the beginning of scripts/create-root-body.sh .

Step 7: Report the creation result

## create-issue-tree 完了レポート

### ルート issue
- #N: タイトル

### Phase 別作成サマリー
| Phase | 親 issue | 起票数 |
|-------|----------|-------|
| Phase 1 | #N | N 件 |

### 作成した issue 一覧
- #N: タイトル(Phase 1 / 親: #M)
...

### 次のアクション
- 実装消化: implement-issue-tree スキルに ルート issue 番号を渡す
- ツリー更新: update-issue-tree スキルでトラッキング issue を棚卸しする

Verification

  • Confirm that each Phase parent issue is listed in the root issue's sub-issues
  • Confirm that child issues are listed in each Phase parent issue's sub-issues
  • gh issue view "${ROOT_NUMBER}" Confirm that the Phase-by-Phase table in the root issue body was generated correctly with
  • gh issue view "${ROOT_NUMBER}" --json body --jq .body に <phaseN_number>・#N・(作成後に更新)Confirm that no bare N cells remain (if any remain, re-run Step 6)
  • MILESTONE If you assigngh issue view <N> --json milestone --jq '.milestone.title' confirm that the root, Phase parents, and children all match ${MILESTONE} Confirm that it matches
# sub-issues は 1 ページ最大 100 件。100 件超のツリーは Step 5 のページネーション
# ループで全件確認する(以下は per_page=100 で先頭ページのみ。件数が 100 未満なら全件)

# ルート直下の sub-issues を確認
gh api "repos/{owner}/{repo}/issues/${ROOT_NUMBER}/sub_issues?per_page=100" --jq '.[].number'

# Phase 親直下の sub-issues を確認
gh api "repos/{owner}/{repo}/issues/${PHASE_NUMBER}/sub_issues?per_page=100" --jq '.[].number'

# phase ラベルの同期確認(Phase 親・子 issue にラベルが付いているか確認)
gh api "repos/{owner}/{repo}/issues/${PHASE_NUMBER}/sub_issues?per_page=100" \
  --jq '.[] | {number: .number, labels: [.labels[].name]}'

Common failures

Problem Workaround
--root The root issue is duplicated on the second partial filing without specifying From the second time onward, always pass --root <既存ルートissue番号> pass
sub_issue_id Pass the issue number as-is to gh api .../issues/<number> --jq '.id' Obtain the database id with
Issue creation fails in a repository where the phase label does not exist At the beginning of Step 4, always run gh label create "phase:${PHASE}" first
--root When appending If the repository has milestones, Step 2.5 automatically joins the user confirmation flow when the inheritance result is empty (if a milestone is selected in the confirmation, it is also reflected in the root issue). In a non-operational repository with no milestones, filing without a milestone via the non-operational guard works normally
Open issues are left under a closed parent Before closing a Phase parent, confirm that all child issues are closed
Leave the Step 6 body as the handwritten placeholder and gh issue edit and the root body is overwritten by the template Generate a table from the actual tree scripts/create-root-body.sh(new creation)・scripts/merge-root-body.sh(--root) is used. If the inspection guard is triggered, the body is not sent and the process is aborted
The process was interrupted before reaching Step 6, and the root remained as the template --root <ルート番号> and re-run. The placeholder line is replaced with the current Phase line
--granularity に 2 h・2・0h etc. is passed and the process is aborted positive integer + h format (^[1-9][0-9]*h$. Example: 2h・4h)

Notes

  • Keep 1 issue to roughly the granularity criterion (default 2h・--granularity can be changed). If it is judged to exceed this, break it down into sub-issues
  • Issue titles are recommended to use the Conventional Commits format (feat:・fix:・chore: etc.)
  • --phase When partially creating issues with the --phase specification, for additional creation of another Phase, always --root <既存ルートissue番号> pass(skip the new creation in Step 3 and append to the existing tree, and in Step 6 do not fully replace but append the diff to the existing body). After creating issues, pass the same root issue number to update-issue-tree and take inventory
  • Pagination: if sub-issues exceed 100, use per_page=100&page=N to page through and retrieve all of them
  • In Step 6 body generation, new creation is scripts/create-root-body.sh、--root merge is scripts/merge-root-body.sh. Do not write the body generation logic back into SKILL.md (to prevent recurrence of bloat and helper duplication)
  • Shell command variables must always "${var}" be quoted with (countermeasure against command injection)
  • gh issue create は --json not supported. Since the issue URL is output to stdout,| grep -oE '[0-9]+$' extract the trailing number with and store it in a variable
  • sub_issues API の sub_issue_id is not the issue number but the database id(GitHub specification).gh api "repos/{owner}/{repo}/issues/<number>" --jq '.id' Get the id with and then POST. If you pass the number as is, you will link the wrong issue / get a 404
  • The phase label must be created with at the beginning of Step 4 before issue creation (no-op in repositories where it has already been created) gh label create "phase:${PHASE}" --color "0075ca" must be created before creating an issue (no-op for already-created repositories)