Roadmap To Github Issue Wave

Roadmap -> GitHub Issue Wave

Use when you have already produced a roadmap, readiness matrix, or gap analysis and the next step is to create the missing GitHub issues without duplicating existing work.

When to use

• A roadmap identifies future work and the user wants issues created
• The user names a new domain/career lane and asks to research practices, create GitHub features/issues, or build job-ready capability; first create a lightweight roadmap artifact, then turn it into an issue wave
• You have an issue/review/readiness summary and need to convert only the missing items into GitHub issues
• You need one umbrella issue plus a small set of focused child issues

Core pattern

0. If the roadmap does not exist yet, create a lightweight roadmap first

   • Put it under docs/roadmaps/<domain>-<purpose>-roadmap.md when it is durable product/career direction
   • Mine local job-market scans or strategy docs for existing demand signals before fresh web research
   • Check current external practice/tool anchors just enough to avoid stale framing
   • Include a capability-wave sequence and an initial issue set in the roadmap
   • Commit/push the roadmap before or immediately after creating the issue wave when repo policy permits docs-only commits

1. Ground on the roadmap artifact first

   • Read the roadmap/review doc that defines the future work
   • Extract the exact candidate issues to create

2. Audit existing issues before drafting anything

   • Search GitHub by the key nouns/phrases for each candidate
   • Check both open and closed issues
   • Classify each candidate as:
     • already open -> do not recreate
     • already closed/delivered -> do not recreate
     • adjacent but not duplicate -> reference it
     • missing -> eligible to create

3. Reuse existing labels exactly

   • Audit repo labels before creation
   • Only use labels that actually exist
   • Prefer the smallest stable label set needed for routing

4. Create one epic first

   • The epic should explain why the wave exists, list the intended child issues, and link the grounding artifacts
   • Create the epic before the children so child bodies can reference the parent issue number

5. Create child issues only for truly missing work

   • Each child should cover one validation/proof/workstream, not a mixed bundle
   • Include:
     • summary
     • why
     • scope
     • deliverables
     • success criteria
     • parent issue number
     • related existing issues

6. Verify every created issue

   • Immediately gh issue view each issue
   • Confirm title, labels, URL, and rendered body
   • Fix any parent references/placeholders immediately if wrong

Good issue-shaping heuristics

• Prefer one epic + 3-6 children for a tightly related wave
• Use children for family-level proofs/examples, not for already-open infrastructure work
• Do not recreate broad infra issues if they already exist; reference them from the new epic
• If an issue is really a duplicate/sub-scope of an existing open issue, fold it into the existing issue rather than create a new one

Domain / career-lane issue wave pattern

When the user names a new technical domain or career lane and asks to build knowledge, demos, and job-readiness:

• Start with a bounded research/docs taxonomy issue before implementation-heavy demos.
• Use that first issue to inventory current practices, tools, role taxonomy, and job-skill mapping.
• Sequence downstream child issues from lower-risk proof to public portfolio packet, for example:
  1. knowledge base + job taxonomy
  2. solver/benchmark proof in the domain
  3. CAD/layout/process automation demo
  4. full tool-flow demo/report
  5. portfolio/job-application packet
• Keep each child issue one artifact family wide. Do not let the knowledge-base issue absorb downstream benchmark code, CAD automation, full tool-flow execution, or resume/portfolio writing.
• In the first issue plan, explicitly list downstream issue numbers as non-goals / follow-ups so adversarial review can verify scope discipline.
• Lock the first issue to durable artifacts that can guide later execution, such as a report plus a machine-readable taxonomy/skill matrix and a test that verifies required sections/entries.

Recommended body skeleton

Epic

• Summary
• Why now
• Grounding
• Scope
• Deliverables
• Related existing issues

Child

• Summary
• Why
• Scope
• Deliverables
• Success criteria
• Parent
• Related

Commands

# Search for duplicates first
gh issue list --state all --limit 200 --search "<key phrase>"

# Check label existence
gh label list --limit 300

# Create epic
gh issue create --title "epic(...): ..." --body-file /tmp/epic.md --label enhancement --label priority:high

# Create child
gh issue create --title "feat(...): ..." --body-file /tmp/child.md --label enhancement --label priority:medium

# Verify
gh issue view <num> --json number,title,url,labels,body

Pitfalls

• Do not create issues directly from a roadmap without searching for existing open/closed issues first
• Do not recreate issues for already-delivered foundations just because the roadmap mentions them
• Do not assume labels exist; verify them first
• Do not create children before the epic if the child body should reference the parent number
• Do not stop after creation without verification

Learned example pattern

For OrcaWave/OrcaFlex canonical spec-contract work:

• Keep existing infrastructure issues (#1652, #1586, #1637, #1591, #1594) as references when they already cover the area
• Create a new epic only for the genuinely missing validation wave
• Create children for specific structure-family proofs (e.g. FPSO, jumper, riser variants, benchmark promotion) when those are absent from the tracker
• Verify all created issues immediately after creation