Phase 6 — Refinement Session#271
Open
leeovery wants to merge 19 commits into
Open
Conversation
…ment-source signal Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ep 0 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…d-state, open, conclude) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ion, writes, commits) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… flow Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…p in refinement-session Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…manifest surface Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…to H2-only with per-branch routing Promote per-operation handlers (Add, Edit summary, Remove, Rename, Change routing) from H3 sub-sections to H2 letters D-H. Replace the single trailing "→ Proceed to the next operation" with explicit "→ Return to **C. Apply** for the next group." routing on every If yes/If no branch. Inline B.1/B.2 lifecycle and collision gates as bold paragraphs in B. Validate. C. Apply becomes the dispatcher, routing each parsed group by op type. Adds I. Done as the terminal return-to-caller. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…) Conclusion the resume signal Make the (none) placeholder explicit at initialisation under Self-Healing Arrivals, Changes, and Conclusion. Document that the Conclusion is replaced at finalisation — including a "No changes applied — browse only" sentinel for browse-only refinements — so an interrupted session is unambiguously distinguishable from a concluded one on next refinement entry. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…nd latest session log The recovery instructions previously pointed at session-001.md only — wrong for a context refresh that lands during a refinement session. Updated to find the highest-numbered session log and distinguish initial (Topics Identified) from refinement (Changes section, with (none) Conclusion as the in-progress signal that routes through B. Resume Check in refinement-session.md). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
….md to H2-only with Resume Check Promote H3 sub-sections (C.1/C.2, D.1, E.1-E.4) to H2 letters so the file matches the H2-only convention used in other reference files (confirm-and-persist, conclude-inception, session-loop). New structure: A. Read State → B. Resume Check → C. Self-Healing → D. Initialise Session Log → E. Render and Prompt → F. Operations Loop → G. Anything Else? → H. Finalise Session Log → I. Compliance → J. Final Sweep → K. Bridge. Other corrections: - Drop step markers from inside lettered sections — step markers belong at backbone-step boundaries in SKILL.md, not at section transitions in reference files. - Convert F.'s bold "Reserved phrase" preludes to H4 conditionals, matching session-loop.md A. and conclude-inception.md A. - Make J. Final Sweep's dirty/clean branches each carry their own "→ Proceed to **K. Bridge**." routing per the conventional rule that every conditional branch is self-contained. - B. Resume Check adds the previously missing recovery path for a context refresh that lands mid-refinement: detect an in-progress refinement log via its (none) Conclusion, offer continue or restart, and either resume against the existing log or delete and fall through to a fresh seed. H. Finalise replaces (none) on every exit so the next entry sees a clean state. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…n loads in refinement-session Three load directives transfer control to a dependent reference and return — show-dismissed in F., map-operations in F., compliance-check in I. Per CONVENTIONS, reference-file loads that are routing decisions take a → prefix; the inline "use it to create" form (D. Initialise Session Log calling refinement-template.md) stays plain since it's a step-action, not control transfer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…Phase 11 Two forward-looking heads-ups discovered while implementing Phase 6: - Phase 7 — refinement-session.md's B. Resume Check routes the `continue` choice directly to E. Render and Prompt, skipping C. Self-Healing. Phase 7 wires analyses into C and needs to decide whether continue re-runs them. Recommendation: don't. - Phase 11 — refinement assumes session-001.md exists. Legacy epics migrated into inception have no such log. Back-fill a placeholder session-001.md during migration so refinement's counter stays clean and "first refinement" doesn't get mis-titled "Initial Framing". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ep 3
The validate-phase.md reference held three lines: signpost text
(already in Step 3), set source=refinement, return. Per the skill
file structure convention ("simple routing conditionals stay
inline"), there's no progressive-disclosure value in keeping it
separate. Inline the assignment in Step 3 and drop the reference
file. invoke-skill.md doc updated to drop the via-validate-phase
note.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…n into its own reference Step 0 had grown into a flat stack of H4 conditionals at mixed nesting levels — source-route at top, then first-session resume detection (file checks, continue/restart STOP-gate, defensive N>1 guard) all hanging off the same H4 level despite being logically nested under the first-session branch. Visually it read like five peer conditions when it's actually two-deep. Mirror the refinement path: extract first-session resume into references/first-session-resume.md. Step 0 becomes a clean two-branch dispatcher — refinement loads refinement-session.md, first-session loads first-session-resume.md. Each loaded reference owns its own routing back to the appropriate Step (1 for fresh/restart, 2 for continue) or terminates on the defensive inconsistent-state guard. Renamed Step 0 to "Source-Aware Detection" since the resume detection logic now lives in the reference files. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…finement state through it Refinement-session, map-operations, and show-dismissed had been asking Claude to import discovery-utils and call computeTopicLifecycle, read manifest fields, and parse session logs inline. That's not how discovery is handled anywhere else in the workflow system — each consumer skill ships its own scripts/discovery.cjs that imports from workflow-shared/scripts/discovery-utils.cjs and outputs structured text via Bash invocation. Mirror that pattern for refinement: - New skills/workflow-inception-process/scripts/discovery.cjs builds discovery_map (tier-sorted, with lifecycle/source_provenance/ current_phase per item), map_summary, dismissed list, and latest_session detection (filename, number, is_refinement, is_in_progress flag derived from the (none) Conclusion sentinel). Also derives next_session_number so reference files don't need to count files themselves. - SKILL.md allowed-tools whitelists the new script. - refinement-session.md A. Read State invokes discovery once; B. Resume Check, D. Initialise Session Log, E. Render and Prompt, H. Finalise Session Log all consume named output fields. D and H re-run discovery to pick up state changes (restart in B, applied operations in F). - map-operations.md A. Parse Operations re-runs discovery for fresh lifecycle data, B. Validate looks up lifecycle from discovery_map rather than calling computeTopicLifecycle inline, name-collision gate consults discovery_map and dismissed. - show-dismissed.md A re-runs discovery and reads the dismissed array from the output (replacing the manifest CLI get). - New tests/scripts/test-discovery-for-refinement.cjs covers discovery_map shape, sorting, lifecycle reflection, dismissed list extraction, latest_session in-progress detection via the (none) Conclusion sentinel, next_session_number derivation, and format() output. Tests: refinement-discovery 15/15, refinement-session manifest surface 14/14, manifest 214/214, continue-epic discovery 75/75, discovery-utils 94/94. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… to match other discovery suites
Refactor to two top-level describe blocks (discover, format) matching
the test-discovery-for-{bridge,discussion,...}.cjs convention. Use the
shared discovery-test-utils.cjs helpers (setupFixture, cleanupFixture,
createManifest, createFile) instead of bespoke seed helpers.
Coverage added (15 → 59 tests):
discover():
- Bare-manifest shape: missing inception phase, empty inception phase,
empty items dict
- Field defaults: null summary, null routing, default source=inception
- All six lifecycles (fresh, researching, ready_for_discussion,
discussing, decided, cancelled) and the alternate-path-open
fall-through to fresh when only one phase is cancelled
- source_provenance: null for inception, "from {source}" for plain
non-inception sources, colon-prefixed unwrap to "from {parent}"
- Sorting: tier rank order across all five tiers; alphabetical within
the same tier
- map_summary: full distribution across all categories;
zero-shape for empty map
- dismissed: missing/non-array defensive defaults; verbatim ordering;
caller mutations don't leak into manifest
- latest_session edge cases: missing Conclusion section, multi-line
Conclusion (first line wins), trailing section after Conclusion,
10+ numbered files (numeric not alphabetic ordering),
non-matching filenames in inception dir, relative_path shape
- next_session_number: zero, increment past concluded, increment
past in-progress
format():
- Header includes work_unit
- map_summary line shape with all six counts
- "(empty)" placeholder for empty discovery_map
- Map row format with tier/name/lifecycle, routing, source,
current_phase, summary; correct omission when fields are null
or source=inception
- "(none)" placeholder for empty dismissed
- "(no session logs on disk)" when latest_session is null
- All latest_session subfields rendered
- "(empty)" conclusion render when conclusion_text is empty
- next_session_number zero-padding to 3 digits
- Trailing newline; sections render in canonical order
Tests: 59/59. Full node test suite: 242/242 across 30 suites.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
7 tasks
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
Phase 6 of the inception/discovery-map initiative — makes refinement actually work. The
f/refineroute from Phase 5 used to dead-end at a "not yet implemented" terminal stop; now it opens a conversational refinement session with map editing operations gated by destructiveness.validate-phase.mdnow setssource = refinementfor the handoff.refinementloadsrefinement-session.mdinstead of the initial-session flow.freshonly).phases.inception.dismissed[]to avoid re-proposing.inception/session-{NNN}.mdper the design template.session-NNN > 1path with an "inconsistent state" message — the entry skill should never invoke first-session when items exist, but we surface clearly if it ever happens.Stacked on
idea/inception-pr-5-map-render. No merge to main until the initiative completes.Test plan
bash tests/scripts/test-workflow-manifest.sh)node --test tests/scripts/test-discovery-for-continue-epic.cjs)node --test tests/scripts/test-refinement-session.cjs) — covers hard-delete on remove, dismissed-list push/pull/get, rename mechanical sequence, and lifecycle-gate semanticsa/cancelpointer), remove with dismissed-list write, mixed batch, show-dismissed + re-add, rename never-started, change routing, edit summary, conclude/bridge, initial-session regression check,f/refineno longer terminal-stops🤖 Generated with Claude Code