roadmap-issue-reopen-retarget-balance

# Roadmap Issue Reopen / Retarget Balance

Use when a new analysis or planning wave initially creates fresh GitHub issues, but the better structure is to preserve continuity by reopening an existing roadmap issue and retargeting new work under it.

## When to use
- A closed roadmap/epic already exists for the same domain
- New analysis updates the roadmap rather than replacing it
- New child issues are valid, but the umbrella/anchor should be the original roadmap
- There is a risk of fragmented governance across parallel roadmap issues

## Goal
Keep one canonical roadmap anchor while still allowing genuinely new scoped execution issues.

## Recommended pattern
1. Audit existing roadmap and sprint issues first.
   - `gh issue view <id>` for known roadmap issues
   - `gh issue list --state all --search "<domain keywords> roadmap OR sprint OR capability roadmap"`
2. Reopen the existing roadmap anchor if it is the right long-lived parent.
   - `gh issue reopen <roadmap_id>`
3. Comment on the reopened roadmap with:
   - why it was reopened
   - updated analysis focus
   - active existing issue clusters
   - delivered foundations that should no longer be treated as gaps
   - links to the latest roadmap artifact/doc
4. Keep existing active issues in place if they already represent real workstreams.
   Typical buckets:
   - proof/validation
   - hardening/repeatability
   - breadth expansion
   - corpus/input expansion
   - downstream scaling
5. Create new issues only for genuinely missing scoped work.
   Good examples:
   - flagship family validation cases
   - new benchmark-specific promotion tasks
   - narrowly bounded missing proof artifacts
6. If a replacement epic was created prematurely:
   - comment that work is moving back under the reopened roadmap
   - close the replacement epic
   - keep its child issues open if they are still valid
7. Retarget new child issues by editing their bodies.
   Replace parent references like `#<replacement_epic>` with `#<reopened_roadmap>`.
8. Add roadmap-link comments to the major existing issues so future agents see the intended structure.
   Include:
   - role of the issue in the sequence
   - roadmap anchor issue number
   - roadmap document path
   - whether the issue is the canonical anchor for that lane or just a narrow sprint/child tracker
9. Add sequencing comments to the new child issues.
   Make explicit:
   - what phase they belong to
   - which proof issues should land before them
   - what later breadth/scaling issues they should precede
10. Add at least one compact roadmap-governance note back on the reopened anchor.
   Recommended contents:
   - status legend (foundation delivered / proof / hardening / breadth / corpus / scaling)
   - phase map showing the intended execution order
   - compact topology summary naming the single roadmap anchor, the canonical hardening issue, the proof lane, and the bounded new child-wave
11. If two open issues overlap, first do an evidence-based scope comparison instead of immediately forcing closure.
   Compare line by line:
   - deliverables
   - unique scope items
   - parent/anchor role
   - current repo state
   Then comment with a de-dup/re-scope recommendation.
   Preferred wording:
   - compare unique remaining scope
   - if none remains, close as duplicate/superseded
   - otherwise rewrite as a narrow child/sub-scope of the canonical issue
12. When a proof issue is the first execution gate for later child issues, post execution-ready acceptance criteria on that issue.
   Include:
   - fixture/artifact contract
   - live/licensed validation requirement
   - semantic-diff or claim-boundary gate
   - regression/skip behavior on non-licensed machines
   - whether a related issue is a child/follow-on or a peer proof issue
13. Add a reusable proof-template checklist on the reopened roadmap anchor for downstream child issues.
   This should standardize:
   - canonical fixture identification
   - native generation path
   - required evidence artifacts
   - allowed vs blocking difference classes
   - documentation update rule
   - closure rule (do not close on mere generation/template existence)
14. After the proof-standard issue is tightened, add concrete implementation breakdown comments to:
   - the main proof issue
   - its child/follow-on issue
   The breakdown should name likely fixture files, helper/test file targets, artifact filenames, and an execution order so later work becomes mechanical.
15. If you close a duplicate/subsumed issue, add a compact governance-topology note back on the roadmap anchor summarizing the resulting stable structure.
   Recommended contents:
   - single roadmap anchor
   - proof lane
   - hardening lane
   - bounded new child-wave
   - duplicates removed
16. After the proof-standard issue is tightened, bridge governance into implementation scaffolding before launching the family-wave.
   Recommended pattern for fixture/report/snapshot proof work:
   - create a fixture-artifact directory with a README describing provenance, regeneration, review rules, and snapshot scope
   - commit a stable metadata JSON baseline first
   - add helper modules for loading metadata and normalizing snapshots
   - add fixture-backed integration/snapshot test skeletons in the target test package
   - prefer generating the first real snapshot baseline from deterministic code in the same execution pass instead of leaving a placeholder baseline committed long-term
   This keeps the proof-standard issue execution-ready and makes later family-specific issues mechanical rather than re-designed from scratch.
17. Immediately run the narrow targeted tests for the new scaffold and expect one or two structural fixes before it passes.
   Common real-world fixes discovered in this pattern:
   - pytest collection may fail on relative imports inside new test modules; prefer explicit package imports such as `from tests.solvers.orcaflex.reporting...` when the test package is not guaranteed to be imported as a package
   - fixture helper path calculations are easy to get wrong; verify the actual resolved path to `tests/fixtures/reporting/...` and adjust `Path(__file__).resolve().parents[...]` based on the real package depth
   - once a deterministic render path exists, regenerate the snapshot baseline from live code before finalizing; do not keep an outdated hand-written placeholder snapshot if the real render can be produced now
   - keep report-generation dates or similar fields deterministic in helpers if the snapshot depends on them
18. After the proof-standard lane passes, apply the same artifact/test pattern to the first flagship family issue before broadening further.
   Recommended family-proof pattern:
   - identify one authoritative canonical spec, one native monolithic reference, and one generated modular reference set
   - when multiple candidate fixtures exist, prefer a model-library case that already has the full trio (canonical spec + monolithic native + modular generated references) over a bare template-only case; this gives a stronger bounded proof path and cleaner issue evidence
   - derive a bounded family-specific metadata JSON under `tests/fixtures/reporting/`
   - add family-specific fixture integration and snapshot tests using the shared helper modules rather than creating a parallel testing architecture
   - prefer the highest-leverage flagship case first (e.g. a generic-track FPSO/turret model) so the proof pattern is exercised on the most failure-prone family before rolling out to simpler follow-ons
   - once the first family path works, generalize helper modules to support named fixtures (`generate_fixture_report`, `load_fixture_metadata`, fixture-specific path helpers) instead of cloning one-off helper code per family
   - generate the family snapshot baseline from live deterministic code, then run one focused pytest command that includes both the original proof-standard tests and the new family-specific tests
19. Verify final state.
   - roadmap issue open
   - replacement epic closed if superseded
   - new child issues open and retargeted
   - existing major issues linked back to the roadmap
   - duplicates either closed or explicitly narrowed
   - proof-standard and reusable checklist comments posted where needed

## Output structure to aim for
- Reopened roadmap = canonical sequencing anchor
- Existing issues = preserved where they already describe real active tracks
- New issues = only truly missing scoped analyses/features
- Sequencing comments = make proof -> hardening -> breadth -> scaling explicit

## Pitfalls
- Do not leave two competing roadmap umbrellas open for the same domain
- Do not recreate issues that already exist just to match a new plan artifact
- Do not bury new family-specific validation work inside a broad proof issue if it deserves a bounded child issue
- Do not close overlapping issues without leaving a rationale comment and redirect target
- Do not rely on issue bodies alone; add comments that explain the new sequencing and parentage

## Minimal checklist
- [ ] Existing roadmap audited
- [ ] Best anchor reopened if needed
- [ ] Replacement epic closed if superseded
- [ ] New child issues retargeted to reopened anchor
- [ ] Existing core issues linked back to roadmap
- [ ] Sequencing/de-dup comments added
- [ ] Final state verified