Milestone delivery path reanalysis

Use this skill when you are asked to:

• •Add/remove/move/close/split issues in a GitHub milestone (CRUD), and keep the milestone description as the authoritative delivery path.
• •Detect “gaps”: issues that are in the milestone but not represented in the milestone’s slice ordering.
• •Update the milestone description deterministically while avoiding the repo’s common pitfalls:
  • •auth context surprises (GITHUB_TOKEN precedence)
  • •heredoc / quoting failures

What this skill uses

• •GitHub CLI: gh
• •Optional: jq (for formatting / inspection)
• •Repo automation script: scripts/reanalyze-milestone.mjs

Preconditions

1. •

   You have GitHub CLI authentication:

   • •gh auth status
2. •

   Auth pitfall / guardrail (IMPORTANT):

gh api prefers environment tokens:

• •GH_TOKEN, then GITHUB_TOKEN (in precedence order)

If those tokens lack permission to update milestones, you can get:

• •HTTP 403: Resource not accessible by personal access token

Fix: temporarily unset GITHUB_TOKEN so gh falls back to the keychain / interactive auth token:

• •unset GITHUB_TOKEN

(Only do this for the duration of the update command.)

Inputs

• •owner/repo (e.g. piquet-h/the-shifting-atlas)
• •milestone number (recommended) OR milestone title

Workflow

Fast path (recommended)

Use the repo script to reanalyze and (optionally) update the milestone description:

• •Preview:
  • •node scripts/reanalyze-milestone.mjs --repo <owner>/<repo> --milestone <milestoneNumber> --print
• •Apply:
  • •node scripts/reanalyze-milestone.mjs --repo <owner>/<repo> --milestone <milestoneNumber> --apply

The script:

• •treats existing Order: blocks as the planned delivery path
• •detects milestone “gaps” and updates supporting sections deterministically
• •retries milestone updates if token precedence causes 403
• •treats closed duplicate/split issues as superseded planning noise and reports them for cleanup

1) Gather evidence (milestone + issues)

Fetch milestone metadata:

• •unset GITHUB_TOKEN && gh api repos/<owner>/<repo>/milestones/<milestoneNumber> --jq '{number,title,open_issues,closed_issues,updated_at,description}'

List issues in milestone (open + closed) using the milestone number filter:

• •unset GITHUB_TOKEN && gh api --paginate repos/<owner>/<repo>/issues -f milestone=<milestoneNumber> -f state=all --jq '.[] | {number,title,state,labels:[.labels[].name]}'

Notes:

• •GitHub’s “issues” endpoint includes PRs; filter out items with pull_request if you only want issues.
• •If you need to preserve PRs in planning, keep them but label them explicitly.

2) Parse existing slice ordering from milestone description

Goal: treat the milestone description as the “planned order” and compare it to reality.

Look for a structure like:

• •## Slice ...
• •Order: followed by lines containing #<issueNumber>

Extract:

• •slice names
• •slice order lists (issue numbers)
• •optional “Coordinator” / “Epic” references

3) Reanalyze and compute the updated delivery path

Produce a new ordered plan that is:

• •deterministic (same inputs → same output)
• •conservative (don’t guess when uncertain; instead, surface “Unplaced gaps”)

3a) Detect gaps

Compute:

• •inMilestone: all issue numbers currently assigned to the milestone
• •inDescriptionOrder: all issue numbers referenced in any Order: block

Gaps:

• •gaps = inMilestone - inDescriptionOrder

Also detect drift:

• •missingFromMilestone = inDescriptionOrder - inMilestone (remove from ordering or flag)

3b) Place gaps (heuristics, in priority order)

1. •

   Prerequisites / Infra slice

   • •If issue has label infra OR title prefix infra( OR mentions “Provision”, “RBAC”, “app settings wiring” → place into Slice 0 — Prerequisites (infra).
2. •

   Coordinator / Epic

   • •If issue has label epic → place under a Coordinator: section for the slice it clearly governs.
   • •Do not interleave epics into Order: unless your repo treats epics as executable tasks.
3. •

   Testing / Docs

   • •If label test → near the end of its relevant slice (after the behavior change it validates).
   • •If label docs → last or near-last in its slice.
4. •

   Scope-based placement

   • •scope:observability after core behavior exists but before closing the slice.
   • •scope:world vs scope:ai vs scope:mcp should usually follow the milestone’s slice taxonomy.
5. •

   Uncertain placement

   • •If a gap can’t be confidently placed, list it in an explicit “Unplaced gaps (needs decision)” section.

3c) Handle duplicates / splits

If an issue is marked duplicate/superseded (common after splitting):

• •Remove it from Order: blocks.
• •Prefer linking to the replacement issue(s) in an “Archive / Superseded” note.

4) Update milestone description (without heredocs)

Because heredocs frequently cause shell trouble, prefer:

1. •Write the new description to a temp file using your editor:

• •/tmp/milestone-desc.txt

1. •Update milestone using -F description=@<file> (reads file contents):

• •unset GITHUB_TOKEN && gh api -X PATCH repos/<owner>/<repo>/milestones/<milestoneNumber> -F description=@/tmp/milestone-desc.txt

5) Verify

Re-fetch and compare:

• •unset GITHUB_TOKEN && gh api repos/<owner>/<repo>/milestones/<milestoneNumber> --jq '.description'

Acceptance checks:

• •Description contains all slices and their Order: blocks.
• •Every issue in milestone is either:
  • •placed in an Order: block, or
  • •referenced as a coordinator, or
  • •listed under “Unplaced gaps”.

Output template (recommended)

Within the milestone description, use a stable structure:

• •Intro (1–2 lines)
• •## Slice 0 — Prerequisites (infra)
• •## Exit criteria ...
• •## Delivery slices
  • •### Slice 1 ... (+ optional Coordinator:)
  • •### Slice 2 ...
  • •...
• •Optional ## Unplaced gaps (needs decision)

Notes

• •Prefer milestone number as the primary identifier (stable). Titles can change.
• •Keep ordering rules explicit and minimal; avoid embedding long narratives.

Last reviewed: 2026-01-16