inception/discovery-map Phase 11 — migration for legacy epics#276
Open
leeovery wants to merge 16 commits into
Open
inception/discovery-map Phase 11 — migration for legacy epics#276leeovery wants to merge 16 commits into
leeovery wants to merge 16 commits into
Conversation
leeovery
added a commit
that referenced
this pull request
May 11, 2026
…n to Phase 6 The phase doc lists Phase 5 as the base, but Phase 6's refinement-session.md is a hard dependency for the empty-summary walkthrough hook, and Phase 7 strips the surfaced_topics/gap_topics arrays the migration needs to read. Phase 6 is the only viable base. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…e from legacy state Walks in-progress epic manifests that pre-date the inception phase and seeds phases.inception.items.* from existing research/discussion items plus the legacy surfaced_topics and gap_topics arrays. Research wins on dedup; phase items win over legacy arrays for source classification. Back-fills a placeholder session-001.md so refinement-session's 'Initial Framing' anchor exists for migrated epics. Per-topic idempotent. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Covers happy paths (research-only, discussion-only, both, surfaced-only, gap-only, end-to-end mixed), source-classification rules (phase items win over legacy arrays), skip cases (cross-cutting, feature/bugfix/ quick-fix, completed/cancelled epics), per-topic idempotency (partial re-run preserves user-curated values; full re-run is byte-identical), session-001.md back-fill and preservation, and the legacy 'exploration' topic edge case. 41 assertions across 17 test functions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… provenance
Locks the colon-strip behaviour of computeSourceProvenance for the three
migration-seeded variants the Phase 11 migration emits. Without these
fixtures, a future regression to the colon-handling rule (e.g., comma-
split logic merging from main) could silently change the rendered
'from {source}' label without breaking any existing test.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
After Phase 11's migration seeds the discovery map for legacy epics, inception items land with no summary field. Surface this state in the discovery-map render so the user sees the migration happened and knows where to populate: an inline callout immediately below the convergence line, counting items where summary is null/missing. Vanishes naturally as summaries get populated via refinement. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…efinement entry Inserts a new section E. Empty-Summary Walkthrough between D and the prior E (now F). Detects items with null summary — typical after the Phase 11 migration seeds the discovery map — and offers to walk through them sequentially with a per-item skip option. Renames cascade E→F→G→H→I→J→K→L. B. Resume Check's continue path routes directly to F, skipping the walkthrough on resume so an in-flight refinement isn't interrupted by a one-shot post-migration prompt. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…n to Phase 6 The phase doc lists Phase 5 as the base, but Phase 6's refinement-session.md is a hard dependency for the empty-summary walkthrough hook, and Phase 7 strips the surfaced_topics/gap_topics arrays the migration needs to read. Phase 6 is the only viable base. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
leeovery
force-pushed
the
idea/inception-pr-11-migration
branch
from
9cf102f to
aa8f7da
Compare
leeovery
changed the base branch from
idea/inception-pr-6-refinement
to
idea/inception-pr-10-direct-entry
After rebasing 8 → 7, 9 → 8, 10 → 9, 11 → 10 (with Phase 7's drop-arrays migration reverted), every phase now branches off the immediately preceding phase's branch. No parallel siblings anywhere in the chain. - Dependencies diagram redrawn as a single linear column. - "Phases 8, 9, 10 can be parallelised" line replaced with a strict-linear statement. - Convention bullet updated to reflect linear-only stacking. - "Reviews can happen in parallel" bullet dropped (still possible across PRs, but no longer the design intent of the stacking model). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…); renumber cleanup to Phase 16 Two new phases for work surfaced during Phase 11 design discussion: - Phase 14 (provenance): add a `description` field to inception items alongside `summary`. Every write surface populates both; entry skills load `description` as session opening context. Folds in Phase 10's direct-entry gap (currently writes no summary) by deriving summary + description from the entry skill's opening question. - Phase 15 (KB index analysis caches): index the research-analysis and discussion-gap-analysis cache files into the knowledge base so the analysis content is queryable. The original Phase 14 (final cleanup) moves to Phase 16 — cleanup genuinely belongs at the very end of the initiative. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…esearch/discussion items Migrating the legacy phases.research.surfaced_topics and phases.discussion.gap_topics arrays produced "ghost" inception items with no context — just topic names. Phase 7's self-healing analyses re-run on next continue-epic and surface fresh themes with proper summaries from current source content, so the array data isn't needed. Migration now walks only research.items and discussion.items keys. Resolves routing via research-precedence on dedup; every item gets source: migration-seeded (no sub-tags needed). Legacy arrays sit inertly on disk as a free safety net. Test coverage stripped of surfaced-only / gap-only / phase-items-win / end-to-end-mixed cases. New test covers the inverse: legacy arrays are explicitly NOT migrated and stay in place untouched. Dropped the two migration-seeded sub-tag provenance fixtures from test-discovery-utils.cjs (they're no longer emitted by anything). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…legacy-recovery surfaces Both the empty-summary callout in epic-display-and-menu.md and the E. Empty-Summary Walkthrough section in refinement-session.md were sub-optimal — they wove a one-time legacy-recovery concern into live flows, leaving dead code that's hard to remove cleanly later. This commit reverts both. Letter cascade in refinement-session.md unwinds from F→L back to E→K. The legacy-recovery flow moves to a dedicated reference (next commit) loaded from one conditional point in continue-epic, with a data-driven kill switch that lets it be deleted in a one-line cleanup PR once unreachable. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ional load New reference at skills/continue-epic/references/legacy-recovery.md handles the one-time summary backfill for inception items seeded by migration 038. Reads the corresponding research/discussion file for each migration-seeded item, drafts a one-line summary, presents a batch review (y/yes accept-all, e/edit, s/skip-all), writes via manifest set, single commit. New Step 6 (Legacy Recovery) in continue-epic SKILL.md sits between Step 5 (Self-Healing) and Step 7 (Display). Trigger is data-driven: discovery_map.filter(t => t.source === 'migration-seeded' && !t.summary). Old Step 6 renumbered to Step 7, old Step 7 to Step 8. Once all migration-seeded items have summaries, the trigger never fires and this reference is provably unreachable — deletable in a one-line cleanup PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…utput Adds a fixture in test-discovery-for-continue-epic.cjs that verifies discovery_map exposes `source` and `summary` per item with the right nullable semantics, so the legacy-recovery filter (source === 'migration-seeded' && !summary) finds exactly the items migration 038 seeded with no summary — and no others. The legacy-recovery flow itself is a skill reference (instruction-driven, interactive), so its conversational logic is verified by the existing manifest CLI and discovery test surfaces plus the compliance self-check on the reference file. This test locks the trigger contract — the shape the reference depends on. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…filter, placeholder syntax
Audit findings on Phase 11 work:
1. Step 6 (Legacy Recovery) in continue-epic SKILL.md was missing the
signpost blockquote after the step marker. CONVENTIONS line 61
requires every step marker to be followed by one.
2. Filter was too strict — `source === 'migration-seeded'` misses items
re-surfaced by Phase 7's analyses (which append their tag to existing
source, producing 'migration-seeded,research-analysis' etc., without
writing a summary). Changed to `startsWith('migration-seeded')` in
continue-epic SKILL.md Step 6, legacy-recovery.md description, and
the filter contract test. New test case covers the combined-source
variant.
3. legacy-recovery.md section B was using an undefined `|` placeholder
operator for the source-file-missing fallback. Switched to standard
@if/@else conditional directives.
4. INDEX.md "And so on through Phase 13" stale reference updated to
"through Phase 16" after the recent phase additions.
5. Migration script's session-001.md back-fill wording adjusted from
"walk through populating" to "draft summaries ... for review" — more
accurately reflects the legacy-recovery batch-review UX.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
leeovery
force-pushed
the
idea/inception-pr-11-migration
branch
from
4cff99e to
5979416
Compare
…ion fixes Three small wording adjustments surfaced by a second-pass audit: 1. continue-epic SKILL.md Step 6 — the "On return, re-read detail (legacy-recovery re-ran discovery before returning)" parenthetical was unconditionally true, but legacy-recovery's skip branch doesn't re-run discovery. Reworded to make the conditional explicit. 2. legacy-recovery.md section A — explicitly states where the derived summary is stored (item.derived_summary in conversation memory) so section B's reference is unambiguous. 3. Migration session-001.md back-fill — "N existing research/discussion item(s)" implied raw items, but the count is deduped topics (research wins over discussion on dedup). Reworded to "N topic(s) found in existing research/discussion items" for precision. Test updated. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Restructured for progressive disclosure — keep the backbone silent unless work is actually needed, then defer all output to the loaded reference. Backbone changes (skills/continue-epic/SKILL.md): - Step 6 stripped to filter + early return + conditional load. No step marker, no signpost, no explanatory prose. Renamed from "Legacy Recovery" to "Summary Backfill" — the loop is about backfilling inception summaries, not a recovery concept Claude needs to reason about. - Step 5's reference to "Step 6 (legacy recovery)" updated to "(summary backfill)". Reference changes (renamed legacy-recovery.md → summary-backfill.md): - H1 + step marker now "Summary Backfill" (no "legacy" or "migration" language in user-visible output). - Section A opens with the step marker and a single merged signpost describing what's happening, not why. "Inception items missing summaries. Drafting them from the existing research and discussion files for review." - "On exit, re-runs discovery" documented in the caller-contract block at the top of the reference so the backbone doesn't need to restate it. - Internal doc comments dropped references to "Phase 7", "migration 038", "carried over" — anything Claude doesn't need to do the job. No logic changes — the filter, batch review, edit loop, and write/commit flow are unchanged. Test contracts unaffected. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…rence Removed the "Loaded by continue-epic Step 6 when..." prefix. Claude doesn't need caller-context reasoning to do the job. The parameter list and on-exit contract are the only relevant framing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
phases.inception.items.*for in-progress epics that pre-date the inception phase, sourced from research/discussion items plus legacysurfaced_topicsandgap_topicsarrays. Per-topic idempotent; non-destructive (legacy arrays preserved; Phase 7's migration 038 drops them separately).migration-seededfor items with phase work,migration-seeded:research-analysis/migration-seeded:gap-analysisfor legacy-array-only items. Phase items win over legacy arrays on dedup; research wins over discussion.session-001.mdso refinement-session's "Initial Framing" numbering anchor exists for migrated epics.continue-epicshows a⚑ Migrated to discovery map. N items have no summary — open f/refine to populate.callout; refinement entry detects empty summaries and offers a sequential walkthrough with a per-itemskip.computeSourceProvenancecolon-strip behaviour for the threemigration-seeded[:...]variants against future regression.Stacking
Base:
idea/inception-pr-6-refinement(Phase 6). The phase doc lists Phase 5 as the base but Phase 6'srefinement-session.mdis a hard dependency for the walkthrough hook, and Phase 7's migration would strip the very arrays this migration needs to read. Phase 11's038-*.shfilename is correct relative to Phase 6 (highest there is037); if Phase 7 lands first, this PR rebases to039.Test plan
bash tests/scripts/test-migration-038.sh— 41 assertions across 17 test functions greentests/scripts/test-migration-*.shgreen (regression sanity)node --test tests/scripts/test-discovery-utils.cjs— 101 tests green (3 newcomputeSourceProvenancefixtures)node --test tests/scripts/test-refinement-session.cjs tests/scripts/test-discovery-for-refinement.cjs— 148 tests greennode --test tests/scripts/test-discovery-for-*.cjs tests/scripts/test-discovery-utils.cjs— 412 tests green{a, b}+ discussion items{b, c}+surfaced_topics: [d]+gap_topics: [e]): all five inception items created with correct routing/source; legacy arrays untouched; session-001.md back-filled/continue-epiccallout appears when empty-summary items exist, decrements as summaries land, vanishes at zero🤖 Generated with Claude Code