feature-ideation enhancement backfill + dry-run + marker continuity (prereq to deprecating idea-enhancer)

[don-petry]

Summary

The idea-enhancer → feature-ideation consolidation (#872) folded the new-idea
enhancement path but dropped two idea-enhancer capabilities — the existing-backlog
sweep and the dry-run — and the idempotency marker differs. Restore them as
first-class feature-ideation modes before idea-enhancer is deprecated (#876), so the
existing Discussions that never got ideated can be enhanced safely and repeatably.

Background — verified gaps (2026-06-25)

• No backfill sweep. feature-ideation-reusable.yml enhances only a single idea via
  target_discussion (fired by discussion:created). There is no mode that sweeps the repo's
  open, human-authored, not-yet-enhanced Ideas backlog — the capability idea-enhancer
  provided via scripts/idea-enhancer/{gather-candidates,post-enhancement}.sh + a weekly sweep.
• No enhancement dry-run. feature-ideation's dry_run input covers generation, not
  enhancement-of-existing, so a backfill can't be previewed.
• Marker mismatch. feature-ideation skips on <!-- feature-ideation:enhanced -->
  (reusable lines 308-310); idea-enhancer wrote <!-- idea-enhancer:enhanced -->. After
  cutover, every idea idea-enhancer already enhanced would be re-enhanced — the exact
  failure [Phase 2] Validate the folded feature-ideation enhancement mode on real .github-private Discussions (next ring) #875's Dev Notes warn against.

Goals

1. Marker continuity (E1). feature-ideation's enhancement idempotency check recognizes
   both <!-- idea-enhancer:enhanced --> and <!-- feature-ideation:enhanced --> as
   already-enhanced; new comments emit one canonical marker. No re-enhancement across cutover.
2. Backfill sweep mode (E2). A workflow_dispatch input (e.g. enhance_backlog: true)
   makes feature-ideation sweep the target repo's open, human-authored, not-yet-enhanced
   Ideas Discussions and post exactly one structured enhancement comment each
   (sharpened problem / context / impact-effort / acceptance criteria), idempotent via the
   marker; bot-authored and already-enhanced ideas are skipped. Ports idea-enhancer's sweep.
3. Dry-run the backfill (E3). dry_run=true + backfill logs the intended per-Discussion
   enhancement comments to the JSONL artifact and posts nothing — a safe preview of a backfill.

Acceptance criteria

• E1: a Discussion carrying <!-- idea-enhancer:enhanced --> is not re-enhanced by
  feature-ideation; bats/test coverage for both markers.
• E2: enhance_backlog dispatch posts one structured comment per open, human-authored,
  un-enhanced Idea (idempotent; bots + already-enhanced skipped); a second run is a no-op.
• E3: dry_run=true + enhance_backlog writes the intended comments to the artifact,
  posts nothing; the artifact lists one entry per candidate Discussion.
• Docs: ci-standards §10 / pipeline doc describe the backfill + dry-run modes and the
  operator runbook for backfilling an existing repo's Ideas backlog.
• Re-sequence: [Phase 2] Validate the folded feature-ideation enhancement mode on real .github-private Discussions (next ring) #875 validates the backfill (dry-run over the real .github-private
  backlog, then live); [Phase 3] Deprecate idea-enhancer in .github-private: remove workflow + scripts + test, update the pipeline doc #876 (deprecate idea-enhancer) is blocked until E1-E3 land.

Out of scope

• The weekly generation pipeline's prompt/model.
• Cross-repo ring promotion of feature-ideation (separate; feature-ideation/next already cut).

Companion to #872 (consolidation). Add idea:approved to hand to the BMAD Scrum Master.

[github-actions[bot]]

📋 Initiative planned by the BMAD Scrum Master (Bob).

Epic #934 — feature-ideation enhancement backfill + dry-run + marker continuity (restore idea-enhancer parity before deprecation)

3 stories created (inert — labelled initiative, NOT initiative:auto):

• [Phase 1] Expose the feature-ideation backfill input: sync the stub to forward enhance_backlog #935 (S) — [Phase 1] Expose the feature-ideation backfill input: sync the stub to forward enhance_backlog
• [Phase 1] Document the feature-ideation backfill + dry-run modes and the backfill operator runbook #936 (M) — [Phase 1] Document the feature-ideation backfill + dry-run modes and the backfill operator runbook
• [Phase 2] Validate the feature-ideation backfill on the real .github-private Ideas backlog (dry-run then live) #937 (M) — [Phase 2] Validate the feature-ideation backfill on the real .github-private Ideas backlog (dry-run then live)

Open questions for review:

• Re-sequence [Phase 3] Deprecate idea-enhancer in .github-private: remove workflow + scripts + test, update the pipeline doc #876 (deprecate idea-enhancer): it must NOT start until E1-E3 land and the backfill is validated (Story 3). This plan cannot add a blocked_by edge onto the pre-existing [Phase 3] Deprecate idea-enhancer in .github-private: remove workflow + scripts + test, update the pipeline doc #876 — a maintainer should manually set [Phase 3] Deprecate idea-enhancer in .github-private: remove workflow + scripts + test, update the pipeline doc #876 blocked_by this epic's backfill-validation story (and keep [Phase 3] Deprecate idea-enhancer in .github-private: remove workflow + scripts + test, update the pipeline doc #876 at initiative:hold) until the go/no-go note confirms marker continuity + single-enhancement.
• Should these stories attach to existing consolidation epic Initiative: Consolidate Discussion-triggered ideation into feature-ideation, deprecate idea-enhancer, and ring-release fleet-wide #872 instead of a new epic? feature-ideation enhancement backfill + dry-run + marker continuity (prereq to deprecating idea-enhancer) #933 is framed as a companion restoring capabilities Initiative: Consolidate Discussion-triggered ideation into feature-ideation, deprecate idea-enhancer, and ring-release fleet-wide #872 deferred; a separate epic keeps the human go/no-go gates independent, but a maintainer may prefer to fold them into Initiative: Consolidate Discussion-triggered ideation into feature-ideation, deprecate idea-enhancer, and ring-release fleet-wide #872's DAG.
• For the stub enhance_backlog input (Story 1): is the central standard stub template (petry-projects/.github standards/workflows/feature-ideation.yml) being updated in lockstep, or should the .github-private stub input be recorded as a documented repo-specific exception in AGENTS.md so a template sync does not reset it (as with the existing feature-ideation/next sanctioned-pin exception)?

---

Review the epic and its sub-issue DAG, adjust as needed, then add initiative:auto to epic #934 to hand it to initiative-driver for auto-implementation.

[github-actions[bot]]

Enhancement: Backfill + Marker Continuity — Implementation Status, Migration Pattern & Validation Path

Sharpened problem & goal
This Discussion framed a three-part gap (marker continuity, backfill sweep, dry-run preview) that blocked the idea-enhancer → feature-ideation consolidation (#866/#872). The implementation has since landed (PR #938, epic #934), so the operative question shifts to: how should the validation phase (#937, currently on hold) be structured to give high confidence that the backfill is safe for live execution, and what does the migration pattern teach us about future bot consolidations?

Implementation status (as of 2026-06-27)

• E1 (marker continuity): Landed in PR feat: implement issue #934 — feature-ideation enhancement backfill + dry-run + marker continuity (restore idea-enhancer parity before deprecation) #938. The feature-ideation prompt now recognizes both <!-- idea-enhancer:enhanced --> and <!-- feature-ideation:enhanced --> markers, writing only the canonical new marker. This is confirmed by the current backfill run which correctly skips the 18 discussions already enhanced under either marker.
• E2 (backfill sweep): Landed in PR feat: implement issue #934 — feature-ideation enhancement backfill + dry-run + marker continuity (restore idea-enhancer parity before deprecation) #938. The enhance_backlog workflow dispatch input is functional — this very run is exercising it.
• E3 (dry-run): Landed in PR feat: implement issue #934 — feature-ideation enhancement backfill + dry-run + marker continuity (restore idea-enhancer parity before deprecation) #938. DRY_RUN=1 + enhance_backlog logs intended mutations to $DRY_RUN_LOG via discussion-mutations.sh without posting.
• Remaining: [Phase 2] Validate the feature-ideation backfill on the real .github-private Ideas backlog (dry-run then live) #937 (Phase 2 validation on real backlog) is initiative:hold / dev-lead:hands-off. [Phase 3] Deprecate idea-enhancer in .github-private: remove workflow + scripts + test, update the pipeline doc #876 (deprecate idea-enhancer) is blocked until validation completes.

Prior art / competitive signal — bot migration patterns

Pattern	Example	Relevance
Dual-read, single-write	Database migration pattern; github-comment tool (suzuki-shunsuke)	Exactly what E1 implements: read both marker formats during transition, write only the new one. Markers are append-only — never change old formats.
Marker-based upsert	create-or-update-comment GitHub Action	Find-by-marker-then-upsert pattern; mirrors discussion-mutations.sh approach
Concurrency-gated cutover	GitHub Actions concurrency groups; this org's existing channel-tag model	Prevents race conditions where both old and new bots run simultaneously. Already in place via workflow concurrency keys.
Evaluate mode	GitHub's 2026 Actions security roadmap: workflow execution rules logged but not enforced	Platform-native dry-run for policy changes; analogous to DRY_RUN=1
Canary workflows	initiative-planner-canary.yml, initiative-driver-canary.yml in this repo	Post-merge dry-run canaries that detect silent regressions — the pattern #937 validation should follow

Key lesson from GitHub's April 2026 merge queue incident (2,092 PRs silently reverted): incomplete feature flag migrations create the most dangerous class of failure — the system appears healthy while silently regressing. The marker continuity approach (E1) directly mitigates this by ensuring the new bot respects all prior enhancement work.

Options for validation (#937)

Option	Description	Confidence	Risk
A. Dry-run → human review → live	Run DRY_RUN=1 + enhance_backlog on .github-private; review the JSONL artifact; then run live	High	Slow (manual review step)
B. Single-candidate live test	Live-enhance one known candidate, verify output and marker placement, then backfill the rest	Medium-High	One bad post is low-blast-radius; may miss edge cases in batch
C. Parallel canary	Run the backfill on a sandbox/test repo with synthetic Discussions, verify, then run on production	High	Requires creating a test fixture repo

Recommendation: Option A then B — dry-run the full backlog first (artifact review gives confidence on scope and content quality), then live-enhance a single candidate as a smoke test before the full run. This follows the canary pattern already established by initiative-planner-canary.yml.

Risks / unknowns

Risk	Severity	Mitigation
Rate limits during large backfill (80 mutations/min GitHub secondary limit)	Low (only 3 candidates currently)	gh-safe.sh wraps all API calls; future backfills on larger repos should cap batch size per run
Enhancement quality variance across candidates	Medium	Each candidate gets independent research; adversarial review built into the prompt
Trigger gap during cutover (Discussion created between old bot disable → new bot enable)	Low	Keep both workflows active with marker dedup during transition; disable old schedule last
#876 deprecation removes fallback	Medium	Validate marker continuity end-to-end before deprecation; keep old scripts in git history for rollback reference

Phased validation path (for #937)

1. Dry-run: Execute DRY_RUN=1 + enhance_backlog=true on .github-private. Review the JSONL artifact for: correct candidate selection (human-authored, ideas category, no existing markers), enhancement quality, and marker placement.
2. Smoke test: Live-enhance one candidate (e.g., TEST(875): single-idea enhancement validation #958 which is a test Discussion). Verify: marker appears in comment, re-run is a no-op (idempotent), and the Discussion is correctly skipped on subsequent backfill runs.
3. Full backfill: Live-enhance remaining candidates. Verify total count matches dry-run count.
4. Deprecation gate ([Phase 3] Deprecate idea-enhancer in .github-private: remove workflow + scripts + test, update the pipeline doc #876): Confirm zero re-enhancements across two consecutive weekly runs. Disable idea-enhancer.yml schedule trigger. Keep the workflow file for one release cycle, then remove.

Success metrics

• Zero re-enhancements: no Discussion receives two enhancement comments (from either bot)
• Backfill coverage: 100% of eligible candidates (human-authored, ideas category, no prior marker) receive exactly one enhancement
• Idempotent re-runs: a second enhance_backlog dispatch after the first is a clean no-op
• Clean deprecation: idea-enhancer.yml removed with no regression in enhancement coverage for ≥2 weekly cycles