Investigate milestone preflight suggestions through dogfooding #568

Suggestion

Investigate whether github-plan guidance or tooling should more consistently prompt an agent to inspect, suggest, or discuss a milestone when durable work expands into multiple implementation issues and no active phase gate exists.

This is a suggestion to test, not a commitment to add automatic milestone creation or to change the planning model.

Why Investigate

A recent TV Volume Bridge planning session had a durable parent issue and an emerging multi-issue implementation graph, but no milestone existed until the user explicitly suggested one. Once created, the milestone provided a useful phase-exit boundary while dependencies and Project Focus continued to determine execution order.

Completed work in #557 and #559 already makes milestones first-class and exposes them to dependency-aware next-work selection. The remaining question is whether agent behavior around discovering or proposing a missing milestone is appropriately calibrated.

Questions to Explore

• When should an agent check for an active milestone: every planning turn, only when a plan fans out, after a foundation merge, or only when release/phase language appears?
• Should a missing milestone produce no signal, an advisory suggestion, or an explicit planning question?
• Can a useful phase-exit gate be distinguished reliably from a themed backlog container?
• How should the suggestion interact with parent issues, sub-issues, native blockers, and Project Focus?
• Does milestone prompting help users finish work, or does it create planning ceremony and excess containers?
• Should gh-plan next remain purely descriptive, or could separate advisory output mention the absence of a phase gate without mutating anything?

Dogfood and Testing Ideas

• Review recent multi-issue workstreams with and without milestones and classify whether a milestone would have clarified closure.
• Run forward scenarios covering a single issue, a parent with parallel sub-issues, a release train, an indefinite backlog, and unrelated concurrent work.
• Observe false positives: cases where suggesting a milestone adds no useful closure condition.
• Observe false negatives: cases where work expands repeatedly because no phase boundary is represented.
• Dogfood any proposed guidance across several real repositories before changing default behavior.
• Compare agent recovery quality when only the parent issue exists versus when a strict milestone description is also present.

Possible Outcomes

• Keep current behavior unchanged.
• Clarify skill prose with an optional milestone preflight at phase boundaries.
• Add non-mutating advisory evidence to an existing read command.
• Add a separate explicit investigation/check command rather than changing next.
• Document repository patterns where milestones are actively discouraged.

Guardrails

• Do not replace session execution plans, durable parent issues, sub-issues, dependencies, or Project Focus with milestones.
• Do not auto-create milestones merely because none exists.
• Do not make milestone ordering authoritative over native blockers.
• Do not invent due dates when the real gate is technical or decision-based.
• Preserve the current rule that a milestone is a strict phase/release/date gate, not another backlog.

Current Status

State: Later; exploratory suggestion parked for future investigation and dogfooding.
Parked until: the owner selects this investigation and its concrete dogfooding question. No implementation direction has been selected.
Next action: decide the bounded question before implementation; a valid conclusion may be that the existing behavior is already correctly conservative.
Last verified: 2026-09-14 UTC; current issue contents still record no selected direction. The underlying exploratory observation remains dated August 24, 2026.

The waiting status reflects the existing parked state. This reconciliation does not select implementation work or add a new dependency.

Relationships

• Follows the completed milestone foundation in Make GitHub milestones first-class in github-plan #557.
• Related to dependency-aware next-work selection in Add dependency-aware next-milestone selection to github-plan #559.
• Motivated by dogfooding in cbusillo/tv-volume-bridge-for-samsung issue Document local GitHub workflow overlay #1 and milestone 0.1 — Mac Integration Proof.

Evidence That Would Be Useful

• A compact scenario matrix with expected and observed agent behavior.
• Examples where milestone prompting materially improved or degraded planning.
• An explicit recommendation to change guidance, add advisory tooling, or leave behavior unchanged.
• Forward-test results from more than one repository and workstream shape.