diff --git a/discovery-map/INDEX.md b/discovery-map/INDEX.md index 6ab303d6..3381e744 100644 --- a/discovery-map/INDEX.md +++ b/discovery-map/INDEX.md @@ -8,47 +8,53 @@ A multi-phase initiative to add an **inception phase** at the start of every epi ## Phases -Each phase is its own PR off main, planned individually via plan mode. - -1. **[Manifest Foundations](phase-01-manifest-foundations.md)** — `inception` phase + `imports` field validation in manifest CLI. **Status:** Not started -2. **[Inception MVP](phase-02-inception-mvp.md)** — entry/process skills, bridge continuation, start-epic wiring. **Status:** Not started -3. **[Discovery Map Render](phase-03-discovery-map-render.md)** — continue-epic display + menu collapse + auto-routing. **Status:** Not started -4. **[Refinement Session](phase-04-refinement-session.md)** — re-entry path, map editing operations, safety-by-destructiveness. **Status:** Not started -5. **[Self-Healing Re-point](phase-05-self-healing.md)** — research-analysis and gap-analysis re-point to map at continue-epic boot-up. **Status:** Not started -6. **[Imports](phase-06-imports.md)** — `imports/` directory, manifest tracking, KB indexing, behaviour change for features. **Status:** Not started -7. **[Topic Splitting and Elevation](phase-07-topic-splitting-elevation.md)** — write inception items alongside; name collision validation. **Status:** Not started -8. **[Direct-Entry Auto-Add](phase-08-direct-entry-auto-add.md)** — `d`/`discuss` and `r`/`research` for unmapped topics auto-create map items. **Status:** Not started -9. **[Migration](phase-09-migration.md)** — seed inception items for existing in-progress epics. **Status:** Not started -10. **[Drop Explore Mode](phase-10-drop-explore-mode.md)** — remove research's `e`/`explore`; collapse start-epic's `route-first-phase`. **Status:** Not started -11. **[Documentation Cleanup](phase-11-documentation.md)** — CLAUDE.md, README, phase tables, compliance checks. **Status:** Not started +Each phase is its own PR off the previous phase's branch (stacked PRs — see *Branching Strategy* below). Each phase is planned individually via plan mode when implementation begins. + +1. **[Manifest Foundations](phase-01-manifest-foundations.md)** — `inception` phase + `imports` field validation in manifest CLI. **Status:** Done (PR #264) +2. **[Inception Entry Skill + Bridge Plumbing](phase-02-inception-entry-bridge.md)** — entry skill scaffold + bridge continuation + discovery.cjs awareness. **Status:** In progress +3. **[Inception Process Skill](phase-03-inception-process.md)** — the conversational inception session itself (initial-session flow). **Status:** Not started +4. **[Wire start-epic to Inception](phase-04-wire-start-epic.md)** — collapses the research/discussion menu; user-visible flip. **Status:** Not started +5. **[Discovery Map Render](phase-05-discovery-map-render.md)** — continue-epic display + menu collapse + auto-routing. **Status:** Not started +6. **[Refinement Session](phase-06-refinement-session.md)** — re-entry path, map editing operations, safety-by-destructiveness. **Status:** Not started +7. **[Self-Healing Re-point](phase-07-self-healing.md)** — research-analysis and gap-analysis re-point to map at continue-epic boot-up. **Status:** Not started +8. **[Imports](phase-08-imports.md)** — `imports/` directory, manifest tracking, KB indexing, behaviour change for features. **Status:** Not started +9. **[Topic Splitting and Elevation](phase-09-topic-splitting-elevation.md)** — write inception items alongside; name collision validation. **Status:** Not started +10. **[Direct-Entry Auto-Add](phase-10-direct-entry-auto-add.md)** — `d`/`discuss` and `r`/`research` for unmapped topics auto-create map items. **Status:** Not started +11. **[Migration](phase-11-migration.md)** — seed inception items for existing in-progress epics. **Status:** Not started +12. **[Drop Explore Mode](phase-12-drop-explore-mode.md)** — remove research's `e`/`explore`; collapse start-epic's `route-first-phase`. **Status:** Not started +13. **[Documentation Cleanup](phase-13-documentation.md)** — CLAUDE.md, README, phase tables, compliance checks. **Status:** Not started ## Dependencies ``` Phase 1 (manifest foundations) │ - └──▶ Phase 2 (inception MVP) + └──▶ Phase 2 (inception entry skill + bridge plumbing) │ - └──▶ Phase 3 (map render) + └──▶ Phase 3 (inception process skill) │ - ├──▶ Phase 4 (refinement) - │ │ - │ └──▶ Phase 5 (self-healing) - │ │ - │ ├──▶ Phase 6 (imports — also depends on Phase 2) - │ │ - │ ├──▶ Phase 7 (split/elevation) - │ │ - │ └──▶ Phase 8 (direct-entry) - │ - └──▶ Phase 9 (migration) + └──▶ Phase 4 (wire start-epic to inception) │ - └──▶ Phase 10 (drop explore mode) + └──▶ Phase 5 (map render) + │ + ├──▶ Phase 6 (refinement) + │ │ + │ └──▶ Phase 7 (self-healing) + │ │ + │ ├──▶ Phase 8 (imports — also depends on Phase 4) + │ │ + │ ├──▶ Phase 9 (split/elevation) + │ │ + │ └──▶ Phase 10 (direct-entry) │ - └──▶ Phase 11 (docs) + └──▶ Phase 11 (migration) + │ + └──▶ Phase 12 (drop explore mode) + │ + └──▶ Phase 13 (docs) ``` -Phases 6, 7, 8 can be parallelised after Phase 5. Phases 9-11 sequence after the rest. +Phases 8, 9, 10 can be parallelised after Phase 7. Phases 11-13 sequence after the rest. ## Branching Strategy — Stacked PRs @@ -58,7 +64,7 @@ To keep `main` clean of incomplete-feature work until the whole initiative is re - **Phase 1** branches off `main` (after the planning branch has merged). - **Phase 2** branches off Phase 1's branch (not main). - **Phase 3** branches off Phase 2's branch. -- And so on through Phase 11. +- And so on through Phase 13. Each phase's PR has its own scope and review. When the implementer is happy with all phases, the PRs merge in turn — Phase 1 first, then Phase 2 (rebased onto main if needed), then Phase 3, etc. — until the whole initiative lands. diff --git a/discovery-map/phase-01-manifest-foundations.md b/discovery-map/phase-01-manifest-foundations.md index 5b33f2bd..f80f6187 100644 --- a/discovery-map/phase-01-manifest-foundations.md +++ b/discovery-map/phase-01-manifest-foundations.md @@ -39,8 +39,8 @@ Foundation for everything that follows. Adds `inception` as a recognised phase a ## Out of scope -- Inception-related skills (Phase 2). -- Display of inception items in `continue-epic` (Phase 3). +- Inception-related skills (Phases 2-4). +- Display of inception items in `continue-epic` (Phase 5). - Anything user-visible. ## Verification diff --git a/discovery-map/phase-02-inception-entry-bridge.md b/discovery-map/phase-02-inception-entry-bridge.md new file mode 100644 index 00000000..dc29ce82 --- /dev/null +++ b/discovery-map/phase-02-inception-entry-bridge.md @@ -0,0 +1,77 @@ +# Phase 2 — Inception Entry Skill + Bridge Plumbing + +**Status:** Not started · **Depends on:** Phase 1 + +## Purpose + +First slice of the original "Inception MVP" (split into Phases 2-4 for reviewable size). + +Establishes the **inception door**: the entry-point skill that routes incoming work into inception, plus the bridge continuation that routes back out, plus minimal awareness in `continue-epic`'s discovery script. The room behind the door (the actual conversation) lands in Phase 3; wiring `start-epic` to walk through the door lands in Phase 4. + +After this phase: `/workflow-inception-entry epic {wu}` is a registered, compliant skill that gathers context and would invoke a processing skill — but the processing skill doesn't exist yet, so end-to-end use isn't possible. **No user-visible behaviour change** — `/start-epic` still routes to research/discussion as it does today. + +## Reference + +- [Design](design.md) — *Inception Phase — Behaviour* → *Initial session* (lines 184-195) for the entry shape; *Files on disk* (lines 302-318). +- `CONVENTIONS.md` — **MANDATORY** before authoring any skill file. Display rules, Step 0 structure, load directive format, zero-output rule, reference-file structure. +- `skills/workflow-research-entry/SKILL.md` and references — closest precedent. Model the inception-entry skill on this shape. +- `skills/workflow-bridge/SKILL.md` and `references/epic-continuation.md` — pattern for the continuation reference. Inception's continuation is simpler — always re-invokes `/continue-epic {wu}` with no phase-routing computation. +- `skills/continue-epic/scripts/discovery.cjs` — line 5 (`EPIC_PHASES`) needs `inception` added so the iterators don't skip the new phase. + +## What ships + +- New skill `workflow-inception-entry/` (SKILL.md + 3 references). Models on `workflow-research-entry`. +- New `workflow-bridge/references/inception-continuation.md` — plan-mode handoff that re-invokes `/continue-epic {work_unit}`. +- `workflow-bridge/SKILL.md` — register the new continuation reference (`completed_phase = inception` route). +- `continue-epic/scripts/discovery.cjs` — add `'inception'` to `EPIC_PHASES`. **No display change** — Phase 5 owns the discovery-map render. + +## Files + +**New — `skills/workflow-inception-entry/`:** + +- `SKILL.md` — backbone with Step 0 (initialisation), Step 1 (parse args — `$0`=work_type, `$1`=work_unit, `$2` unused since inception is per-work-unit), Step 2 (check phase entry), Step 3 (validate — first-session vs re-entry), Step 4 (gather context), Step 5 (invoke skill). +- `references/validate-phase.md` — **first-session vs re-entry detection.** Phase 2 only wires the first-session branch. Re-entry emits a "refinement coming in Phase 6" stub and returns. Phase 6 replaces the body. +- `references/gather-context.md` — minimal. Reads work-unit description from manifest. If `imports[]` is non-empty, lists filenames as additional context (Phase 8 broadens this — KB indexing on import). +- `references/invoke-skill.md` — handoff to `workflow-inception-process`. **Note:** the processing skill doesn't exist until Phase 3. For Phase 2, the handoff text is authored against the future skill name; invoking it will error until Phase 3 lands. This is fine — Phase 2's PR is reviewable in isolation, and the entry skill becomes useful when stacked atop Phase 3. + +**New — `skills/workflow-bridge/references/inception-continuation.md`:** + +- Plan-mode handoff that always re-invokes `/continue-epic {work_unit}`. No phase-routing computation needed (single deterministic outcome). + +**Modified:** + +- `skills/workflow-bridge/SKILL.md` — Step 2 routing table gains an `inception` branch. Place above the existing epic branch. +- `skills/continue-epic/scripts/discovery.cjs` — line 5: add `'inception'` to `EPIC_PHASES`. Verify `buildEpicDetail` doesn't error on `phases.inception.items.{topic}` shape (status only, no `sources`/`format`). + +## Out of scope + +- Inception process skill itself (Phase 3). +- Wiring `start-epic` to invoke inception (Phase 4). +- Discovery-map render in `continue-epic` (Phase 5). +- Refinement / re-entry implementation (Phase 6). +- Imports machinery beyond awareness in `gather-context.md` (Phase 8). + +## Verification + +1. Compliance self-check passes on `workflow-inception-entry/SKILL.md` and each reference file. +2. Direct invocation smoke test: + ```bash + cd "$(mktemp -d)" && mkdir -p .workflows + # Manually init an epic for testing + node /path/to/skills/workflow-manifest/scripts/manifest.cjs init test-epic --work-type epic --description "Test" + # Invoke the entry skill (will error at Step 5 because process skill doesn't exist yet — expected for Phase 2) + /workflow-inception-entry epic test-epic + ``` + Expected: skill loads, runs Step 0 → Step 4 cleanly, then errors at Step 5 invoking the missing process skill. The error confirms wiring is in place. +3. `continue-epic` does not error on existing epics (which have no `inception` phase): + ```bash + node skills/continue-epic/scripts/discovery.cjs + ``` +4. Run existing manifest tests to confirm Phase 1's foundations still pass. + +## Notes for the implementer + +- **CONVENTIONS.md is mandatory.** Re-read it before authoring `SKILL.md` and references — the conventions are dense and have produced silently non-compliant skills when relied on by memory. +- **Phase 2 is intentionally unreachable end-to-end.** The entry skill exists but invoking it will fail at Step 5 because Phase 3 hasn't shipped yet. This is by design — small, reviewable PRs build on each other. +- **Re-entry is stubbed, not skipped.** `validate-phase.md` has both branches structurally; the re-entry branch points to a Phase-6 placeholder. Phase 6 replaces the body with the real refinement flow. No throwaway code. +- **No background agents.** Inception is curatorial; Phase 3's process skill won't dispatch review/perspective agents either. diff --git a/discovery-map/phase-02-inception-mvp.md b/discovery-map/phase-02-inception-mvp.md deleted file mode 100644 index 982edd9c..00000000 --- a/discovery-map/phase-02-inception-mvp.md +++ /dev/null @@ -1,82 +0,0 @@ -# Phase 2 — Inception MVP - -**Status:** Not started · **Depends on:** Phase 1 - -## Purpose - -The first user-visible piece. Creates the inception entry and process skills, the bridge continuation back to continue-epic, and rewires `start-epic` to invoke inception. After this phase, new epics go through inception when started — but the discovery map isn't yet visualised in `continue-epic` (that's Phase 3). Inception items are written to the manifest; users navigate through but the UI is transitional. - -## Reference - -- [Design](design.md) — Inception Phase — Behaviour (curatorial moves, hard rules, routing inference); Initial session subsection; Convention — same conversational pattern as discussion-process; Files on disk; Session log shape. -- `skills/workflow-research-process/SKILL.md` and references — closest precedent to model on. -- `skills/workflow-discussion-process/SKILL.md` and references — second precedent; the conversational convention is the same shape. -- `skills/workflow-research-entry/SKILL.md` — model for inception-entry. -- `skills/workflow-bridge/SKILL.md` and references — pattern for the inception continuation reference. -- `CLAUDE.md` — Skill File Structure (MANDATORY) section for backbone + reference patterns. - -## What ships - -- New skill `workflow-inception-entry` (model on workflow-research-entry). -- New skill `workflow-inception-process` with initial-session flow only (refinement comes in Phase 4). -- New `inception-guidelines.md` with curatorial moves and routing-inference cues. -- Bridge continuation: inception conclusion → re-invoke `/continue-epic {wu}`. -- `start-epic` Step 3 (Route to First Phase) collapses to "always invoke inception-entry" for new epics. -- `start-epic`'s `i`/`import` route is preserved but routes through inception (full imports machinery comes in Phase 6). - -## Files - -**New — `skills/workflow-inception-entry/`:** -- `SKILL.md` — backbone (parse args, validate phase, gather context, invoke skill). Pattern: workflow-research-entry. -- `references/validate-phase.md` — first-session vs re-entry detection (manifest-based). For Phase 2, only the first-session branch is wired; re-entry returns a stub until Phase 4. -- `references/gather-context.md` — minimal; reads work-unit description from manifest. -- `references/invoke-skill.md` — handoff to processing skill. - -**New — `skills/workflow-inception-process/`:** -- `SKILL.md` — backbone with steps: Resume Detection, Initialize, Load Guidelines, Knowledge Usage / Contextual Query, Session Loop, Document Review, Compliance, Conclude. -- `references/inception-guidelines.md` — curatorial mode, hard rules, routing inference. Treat the design doc's "Inception Phase — Behaviour" section as the source of truth. Worked examples per move (decomposition, tentative grouping, coarseness check, routing dialogue, anchor-and-return). -- `references/initialize-inception.md` — create the inception phase entry; create `inception/` directory; seed context from work-unit description. -- `references/session-loop.md` — conversational rhythm following discussion-process precedent. Topics surface; routing inferred from cues; tentative proposals confirmed. -- `references/routing-inference.md` — cue lists and worked examples (reuse from design doc verbatim). -- `references/confirm-and-persist.md` — render the map at session end; STOP gate; manifest writes; session-log write. -- `references/conclude-inception.md` — final commit; bridge invocation. -- `references/template.md` — initial session-log template (per design doc). - -**New — `skills/workflow-bridge/references/inception-continuation.md`:** -- After inception conclusion, plan-mode handoff that re-invokes `/continue-epic {wu}`. Standard epic pattern. - -**Modified:** -- `skills/start-epic/SKILL.md` — Step 3 invokes `/workflow-inception-entry epic {wu}`. The user no longer chooses research/discussion/import as a top-level menu (import flows through inception, fully integrated in Phase 6). -- `skills/start-epic/references/route-first-phase.md` — keep file (Phase 10 removes); update to reflect that import goes through inception. -- `skills/continue-epic/scripts/discovery.cjs` — recognise `inception` phase exists in the `phases` structure; no display changes yet, but the script must not error when iterating. -- `skills/workflow-bridge/SKILL.md` — register the new continuation reference. - -## Out of scope - -- Discovery map render in `continue-epic` (Phase 3). -- Refinement (Phase 4). -- Self-healing analyses (Phase 5). -- Imports machinery beyond preserving the `i`/`import` entry path (Phase 6). -- Topic-splitting/elevation map writes (Phase 7). -- Migration (Phase 9). - -## Verification - -1. Create a new test epic in a temp directory: `cd $TMPDIR/test-epic && /start-epic`. -2. Provide a description; confirm name; observe that the next phase invoked is inception (not research/discussion). -3. Walk through the inception conversation. Topics should surface conversationally; routing should be inferred from user cues. -4. At session end, confirm: - - `phases.inception.items.{topic}` written for each topic, with `name`, `summary`, `routing`, `source: inception`. - - `inception/session-001.md` written with the initial-session log shape. -5. Bridge fires; user lands back at `/continue-epic`. -6. `/continue-epic` does not error (display is transitional — full map render comes in Phase 3). -7. Compliance self-check passes on all new skill files. - -## Notes for the implementer - -- Inception is **one shape, no flavours** — same skill regardless of greenfield or existing-project epic. Scope emerges from user responses, not a flag. -- **Hard rules** (per design doc): initial spike not exhaustive; no active missing-piece probes; no decisions or investigations. Encode these in `inception-guidelines.md`. -- The session log is a markdown record of the journey, not a transcript. Brief, rationale-focused, event-keyed. -- `inception/` directory is created at first session; session logs accumulate there as `session-NNN.md`. -- The conversational convention follows discussion-process — STOP gates around manifest writes, not around every conversational turn. -- The "import" path through start-epic's existing `i`/`import` should still work in Phase 2 — it can drop into the existing exploration.md path until Phase 6 finalises imports. Don't build full imports machinery here. diff --git a/discovery-map/phase-03-inception-process.md b/discovery-map/phase-03-inception-process.md new file mode 100644 index 00000000..be7e663c --- /dev/null +++ b/discovery-map/phase-03-inception-process.md @@ -0,0 +1,84 @@ +# Phase 3 — Inception Process Skill + +**Status:** Not started · **Depends on:** Phase 2 + +## Purpose + +Second slice of the original "Inception MVP" — the room behind the door. Implements the conversational inception session itself. Models on `workflow-discussion-process` (conversational + STOP-gated). + +After this phase: invoking `/workflow-inception-entry epic {wu}` works end-to-end *if invoked manually* — produces an inception conversation, surfaces topics, infers routing, persists items to the manifest, writes a session log, and bridges back to `/continue-epic`. Real epics still don't go through inception until Phase 4 wires `start-epic`. + +## Reference + +- [Design](design.md): + - **Inception Phase — Behaviour** (lines 111-300) — curatorial moves, hard rules, routing inference, initial-session shape, batched-vs-per-item gate model, examples. + - **Files on disk** (lines 302-318) — directory layout. + - **Session log shape** (lines 320-355) — initial session-log template. +- `CONVENTIONS.md` — **MANDATORY** before authoring any skill file. Especially the *Skill File Structure*, *Reference File Structure*, *Step Numbering*, and *Stop Gates* sections. +- `skills/workflow-discussion-process/SKILL.md` and references — closest precedent. Same conversational pattern, same gate convention, same step rhythm. +- `skills/workflow-knowledge/references/knowledge-usage.md` and `contextual-query.md` — loaded mid-skill (same pattern as discussion-process). + +## What ships + +- New skill `workflow-inception-process/` — backbone + 7 references. +- Initial-session flow only. Resume detection routes to a Phase-6 stub (refinement). +- Knowledge-base contextual query at session start (work-unit description as the query). +- Single STOP gate at confirm-and-persist, then batched manifest writes (one `init-phase` + 3 `set`s per surfaced topic) plus session-log finalisation, single commit. +- Bridge invocation at conclusion. + +## Files + +**New — `skills/workflow-inception-process/`:** + +- `SKILL.md` — backbone with steps: + - Resuming-After-Context-Refresh block (mirrors discussion-process). + - Step 0: Resume Detection — `inception/session-001.md` exists? Yes → Phase-6 stub, return. No → Step 1. + - Step 1: Initialize Inception (load `initialize-inception.md`). + - Step 2: Load Inception Guidelines (load `inception-guidelines.md`). + - Step 3: Knowledge Usage (load `../workflow-knowledge/references/knowledge-usage.md`). + - Step 4: Contextual Query (load `../workflow-knowledge/references/contextual-query.md`). + - Step 5: Session Loop (load `session-loop.md`). + - Step 6: Confirm and Persist (load `confirm-and-persist.md`). + - Step 7: Document Review (lighter than discussion's — inception logs are brief by design). + - Step 8: Compliance Self-Check (load `../workflow-shared/references/compliance-check.md`). + - Step 9: Conclude Inception (load `conclude-inception.md`). +- `references/inception-guidelines.md` — curatorial mode, hard rules, worked examples per move (decomposition, tentative grouping, coarseness check, anchor-and-return). Direct translation of design.md "Inception Phase — Behaviour" lines 115-130. +- `references/initialize-inception.md` — create `inception/` directory; load template; **no** manifest writes yet (topics get written in confirm-and-persist). +- `references/routing-inference.md` — verbatim from design.md lines 132-182. Cue lists + three worked examples. +- `references/session-loop.md` — conversational rhythm: open → surface → group → infer routing → anchor-and-return → convergence-signal. Topics tracked in working list (in conversation memory + draft session-log section). **Binding manifest writes deferred to confirm-and-persist.** +- `references/confirm-and-persist.md` — render the proposed map; STOP gate; on `yes`: per-topic `init-phase` + `set` (`name`, `summary`, `routing`, `source: inception`); finalise session-001.md; single commit. +- `references/conclude-inception.md` — bridge invocation. **No KB indexing** — inception is not an indexed phase. +- `references/template.md` — initial session-log template per design.md "Session log shape" lines 324-355. + +## Out of scope + +- Wiring `start-epic` to invoke inception (Phase 4). +- Refinement / re-entry conversation (Phase 6) — stub only. +- Self-healing analyses (Phase 7). +- Imports KB indexing (Phase 8). +- Background agents (review/perspective). Inception is curatorial — no agents. + +## Verification + +1. Compliance self-check on `workflow-inception-process/SKILL.md` and each reference file. +2. End-to-end manual smoke (direct invocation, since Phase 4 hasn't wired `start-epic` yet): + ```bash + cd "$(mktemp -d)" && mkdir -p .workflows + node /path/to/manifest.cjs init test-epic --work-type epic --description "Building a small SaaS for kitchen ops" + /workflow-inception-entry epic test-epic + ``` + Walk a conversation surfacing 2-3 topics with mixed routing. Verify: + - `phases.inception.items.{topic}` written for each topic with `name`, `summary`, `routing`, `source: inception`. + - `inception/session-001.md` matches the template shape. + - One commit captures the persistence step. + - Bridge fires; user lands at `/continue-epic test-epic`. +3. Run Phase 1's manifest test suite — should still pass. +4. Run the discovery.cjs script against the seeded epic — should not error and should include `inception` in the `phases` output. + +## Notes for the implementer + +- **Manifest writes batch at confirm-and-persist.** Topics surface into a working list during the conversation; the user confirms the *whole map* once; persistence is one STOP gate → N writes → one commit. This matches the design's "safety scales with destructiveness" rule (adds batch). +- **No background agents.** Inception is curatorial, not investigative. Discussion-process's `review-agent` and `perspective-agents` are not modelled. +- **`inception` is NOT a knowledge-indexed phase.** Indexed phases are research/discussion/investigation/specification. Inception session logs are journey records. `conclude-inception.md` does **not** call `knowledge index`. +- **Don't accidentally re-introduce `cancelled` status handling.** Phase 1's manifest CLI rejects `cancelled` for inception items. Don't copy-paste from discussion-process and forget to strip the cancellation paths. +- **Inception items have a `source` field.** For the initial session, `source: inception`. (Phase 7 will introduce `source: research-analysis`/`gap-analysis`; Phase 9 will introduce `source: split`/`source: elevation`; Phase 10 will introduce `source: direct-start`; Phase 11 migration will introduce `source: migration-seeded`.) diff --git a/discovery-map/phase-04-wire-start-epic.md b/discovery-map/phase-04-wire-start-epic.md new file mode 100644 index 00000000..a662f81c --- /dev/null +++ b/discovery-map/phase-04-wire-start-epic.md @@ -0,0 +1,82 @@ +# Phase 4 — Wire `start-epic` to Inception + +**Status:** Not started · **Depends on:** Phase 3 + +## Purpose + +Third and final slice of the original "Inception MVP" — the user-visible flip. Replaces `start-epic`'s research/discussion menu with a single route into the inception phase. After this phase, **new epics go through inception when started**. + +The discovery map isn't yet visualised in `continue-epic` (Phase 5 — display lands after the data is being written). Inception items are written to the manifest by Phase 3's process skill; Phase 4 just turns the new flow on for real users. + +## Reference + +- [Design](design.md): + - **Inception Phase — Behaviour → Initial session** (lines 184-195) — confirms the user-visible entry shape. + - **Imports — Import flow — epics** (lines 614-624) — `i`/`import` route preservation. +- `skills/start-epic/SKILL.md` — the file being modified. +- `skills/start-epic/references/route-first-phase.md` — the menu being collapsed. +- `skills/start-epic/references/collect-import.md` — destination change for imported files. + +## What ships + +- `start-epic` Step 3 (Route to First Phase) collapses to "always invoke inception-entry" for new epics. +- `start-epic`'s `i`/`import` route is preserved but routes through inception (full imports machinery — KB indexing, feature-import behaviour change — comes in Phase 8). +- End-to-end smoke test: `/start-epic` → describe → name → inception session → bridge → `/continue-epic` works for real. + +## Files + +**Modified:** + +- `skills/start-epic/SKILL.md`: + - Step 3 (Route to First Phase) is no longer a multi-option menu. Either route to inception directly, or via the `i`/`import` side-path. + - Step 4 invocation table reduces to one row: `inception → /workflow-inception-entry epic {work_unit}`. +- `skills/start-epic/references/route-first-phase.md`: + - Keep the file (Phase 12 removes it). Update to reflect the new shape — menu offers either continue-to-inception (default) or `i`/`import`. + - On `i`/`import`: load `collect-import.md`, copy files to `imports/`, record in `imports[]`, then continue into inception. +- `skills/start-epic/references/collect-import.md`: + - Switch destination from `research/exploration.md` to `imports/`. + - Use `manifest push {wu} imports '{"path":"imports/...","imported_at":""}'` per file. + +## Out of scope + +- Discovery-map render in `continue-epic` (Phase 5). +- KB indexing of imports (Phase 8). +- Behaviour change for features (still uses old import path until Phase 8). +- Removing the `route-first-phase.md` menu entirely (Phase 12). + +## Verification + +End-to-end smoke (the real one — first time the user-visible flip is reachable): + +1. Fresh epic in temp dir: + ```bash + cd "$(mktemp -d)" + /start-epic + ``` + - Provide a description. + - Confirm name. + - Observe: routing collapses; lands directly in inception (or import sub-flow). +2. Walk a short conversation surfacing 2-3 topics with mixed routing. +3. Confirm-and-persist: + - `phases.inception.items.{topic}` written. + - `inception/session-001.md` matches template. + - Single commit. +4. Bridge fires; user lands at `/continue-epic {wu}`. +5. `/continue-epic` does not error (display still transitional — full map render is Phase 5). +6. **Import path:** + ```bash + echo "Some seed thoughts" > /tmp/seed.md + cd "$(mktemp -d)" + /start-epic + # Pick i/import; provide /tmp/seed.md + ``` + - `imports/seed.md` copied. + - `manifest.imports[]` has one entry. + - Inception session opens with import content reflected. + +## Notes for the implementer + +- **The `i`/`import` flow is the only branch left in `route-first-phase.md`.** If the user doesn't pick import, just continue into inception — no menu rendered. Only show the menu when an inbox file is being processed or when there's a reason for the user to choose import explicitly. Final wording finalised during implementation. +- **Inbox-file path** (when `/start-epic` is invoked with a positional argument pointing at a `.workflows/.inbox/ideas/*.md` file) bypasses the gather-context prompt — see existing `start-epic/SKILL.md` Step 1. That logic stays as-is; only the *next-step* phase routing changes. +- **Don't break the existing import-from-feature flow.** Features still use the old import path until Phase 8 ships the behaviour change. Phase 4 only changes the **epic** import flow. +- **Testing:** because Phase 4 is the first end-to-end-reachable stage, this is the right phase to verify the manifest item shape matches the design (`name`, `summary`, `routing`, `source`). Phases 2 and 3 should have produced the right shape, but Phase 4 is when a *real user* exercises it. diff --git a/discovery-map/phase-03-discovery-map-render.md b/discovery-map/phase-05-discovery-map-render.md similarity index 88% rename from discovery-map/phase-03-discovery-map-render.md rename to discovery-map/phase-05-discovery-map-render.md index 276b175a..b355b725 100644 --- a/discovery-map/phase-03-discovery-map-render.md +++ b/discovery-map/phase-05-discovery-map-render.md @@ -1,6 +1,6 @@ -# Phase 3 — Discovery Map Render in continue-epic +# Phase 5 — Discovery Map Render in continue-epic -**Status:** Not started · **Depends on:** Phase 2 +**Status:** Not started · **Depends on:** Phase 4 ## Purpose @@ -21,7 +21,7 @@ Make the discovery map visible. Updates `continue-epic`'s state display to show - Source provenance shown on a sub-line under each topic when present. - Per-phase entries collapse to per-topic menu entries with auto-routing (Start research/Start discussion/Continue X — phase). - Recommendation logic: top discovery item (`→` first, then `◐`) during discovery; build-phase items once settled. -- New menu entries: `f`/`refine` (no behaviour yet — Phase 4 wires it). +- New menu entries: `f`/`refine` (no behaviour yet — Phase 6 wires it). - `p`/`pending` removed (map covers it). - `s`/`spec` continues to operate when applicable but isn't recommended during discovery. @@ -34,14 +34,14 @@ Make the discovery map visible. Updates `continue-epic`'s state display to show ## Out of scope -- Refinement session itself (Phase 4 — `f`/`refine` menu entry leads here, but Phase 3 only wires the route). -- Self-healing callouts ("3 new topics added") — Phase 5. -- Imports count display ("N imported seeds") — Phase 6. -- Migration callouts — Phase 9. +- Refinement session itself (Phase 6 — `f`/`refine` menu entry leads here, but Phase 5 only wires the route). +- Self-healing callouts ("3 new topics added") — Phase 7. +- Imports count display ("N imported seeds") — Phase 8. +- Migration callouts — Phase 11. ## Verification -1. Continue from a Phase 2 test epic that has been through inception. +1. Continue from a Phase 4 test epic that has been through inception. 2. `/continue-epic` shows the discovery map at the top with all items in `○ fresh` state. 3. Counts in the summary line are correct. 4. Convergence signal reads `⚑ Discovery in progress`. diff --git a/discovery-map/phase-04-refinement-session.md b/discovery-map/phase-06-refinement-session.md similarity index 90% rename from discovery-map/phase-04-refinement-session.md rename to discovery-map/phase-06-refinement-session.md index 75510ac4..ec6d974c 100644 --- a/discovery-map/phase-04-refinement-session.md +++ b/discovery-map/phase-06-refinement-session.md @@ -1,6 +1,6 @@ -# Phase 4 — Refinement Session +# Phase 6 — Refinement Session -**Status:** Not started · **Depends on:** Phase 3 +**Status:** Not started · **Depends on:** Phase 5 ## Purpose @@ -10,7 +10,7 @@ Add the re-entry path to inception so users can refine the map after it's been s - [Design](design.md) — Refinement session subsection; Map editing operations subsection; Safety scales with destructiveness; Cancellation and Removal section (hard-delete + dismissed list). - `skills/workflow-discussion-process/references/discussion-session.md` — conversational pattern precedent. -- `skills/workflow-shared/references/background-agent-surfacing.md` — surfacing protocol (Phase 5 will use it; not needed here yet). +- `skills/workflow-shared/references/background-agent-surfacing.md` — surfacing protocol (Phase 7 will use it; not needed here yet). ## What ships @@ -29,7 +29,7 @@ Add the re-entry path to inception so users can refine the map after it's been s ## Files **New — `skills/workflow-inception-process/references/`:** -- `refinement-session.md` — re-entry flow: read state, self-healing check (placeholder/no-op until Phase 5), open refinement, persist, conclude. +- `refinement-session.md` — re-entry flow: read state, self-healing check (placeholder/no-op until Phase 7), open refinement, persist, conclude. - `map-operations.md` — per-operation handling with the editing-rules matrix from the design doc. Validation logic (never-started gate, name collision check). Hard-delete on remove + add to dismissed list. - `show-dismissed.md` — surface dismissed items with their original source; allow user to re-add. @@ -40,13 +40,13 @@ Add the re-entry path to inception so users can refine the map after it's been s ## Out of scope -- Self-healing analyses (Phase 5 — refinement session loads them but the analyses themselves are not yet rewired). -- Imports interaction (Phase 6 — refinement may eventually offer "remove import" but not in this phase). -- Migration-driven empty-summary back-fill prompt (Phase 9). +- Self-healing analyses (Phase 7 — refinement session loads them but the analyses themselves are not yet rewired). +- Imports interaction (Phase 8 — refinement may eventually offer "remove import" but not in this phase). +- Migration-driven empty-summary back-fill prompt (Phase 11). ## Verification -1. Continue from a Phase 3 test epic. +1. Continue from a Phase 5 test epic. 2. `/continue-epic` → `f`/`refine` → refinement session opens. 3. Add a new topic via natural language ("add offline mode as research") — single STOP gate, manifest written, session log entry added. 4. Add multiple topics in one message ("add A as research, B as discussion, C as research") — single STOP gate showing all three, single commit. diff --git a/discovery-map/phase-05-self-healing.md b/discovery-map/phase-07-self-healing.md similarity index 95% rename from discovery-map/phase-05-self-healing.md rename to discovery-map/phase-07-self-healing.md index 3193a4ef..3b157f9f 100644 --- a/discovery-map/phase-05-self-healing.md +++ b/discovery-map/phase-07-self-healing.md @@ -1,6 +1,6 @@ -# Phase 5 — Self-Healing Analyses Re-point to Map +# Phase 7 — Self-Healing Analyses Re-point to Map -**Status:** Not started · **Depends on:** Phase 4 +**Status:** Not started · **Depends on:** Phase 6 ## Purpose @@ -41,12 +41,12 @@ Move `research-analysis` and `gap-analysis` from `workflow-discussion-entry` to ## Out of scope -- Imports as analysis input (Phase 6 — analyses still operate on research/discussion files only). -- Topic-splitting / elevation behaviour change (Phase 7). +- Imports as analysis input (Phase 8 — analyses still operate on research/discussion files only). +- Topic-splitting / elevation behaviour change (Phase 9). ## Verification -1. Continue from a Phase 4 test epic. +1. Continue from a Phase 6 test epic. 2. Complete a research session for a topic. Return to `/continue-epic`. 3. Boot-up runs research-analysis (cache stale because new research file). If new themes surface, callout reads `⚑ N new topics added to the map from research-analysis`. New items appear on the map with `source: research-analysis` provenance. 4. Complete a discussion session. Boot-up runs gap-analysis. If new gaps surface, callout shows; new items on the map. diff --git a/discovery-map/phase-06-imports.md b/discovery-map/phase-08-imports.md similarity index 84% rename from discovery-map/phase-06-imports.md rename to discovery-map/phase-08-imports.md index 27d2a8cc..7621d960 100644 --- a/discovery-map/phase-06-imports.md +++ b/discovery-map/phase-08-imports.md @@ -1,6 +1,6 @@ -# Phase 6 — Imports +# Phase 8 — Imports -**Status:** Not started · **Depends on:** Phase 5 (and Phase 2 for inception) +**Status:** Not started · **Depends on:** Phase 7 (and Phase 4 for inception fully wired) ## Purpose @@ -9,15 +9,15 @@ Add the imports machinery: a top-level `imports/` directory, manifest tracking, ## Reference - [Design](design.md) — Imports section in full (what imports are, layout, manifest tracking, flows for epic and feature, KB retrieval, behaviour change for features, why not auto-split). -- `skills/start-epic/references/route-first-phase.md` and `skills/start-epic/references/collect-import.md` — existing import flow (epic). -- `skills/start-feature/references/research-gating.md` and `skills/start-feature/references/collect-import.md` — existing import flow (feature). +- `skills/start-epic/references/route-first-phase.md` and `skills/start-epic/references/collect-import.md` — existing import flow (epic) — Phase 4 already routes epic imports to `imports/`; this phase adds KB indexing and the broader convention. +- `skills/start-feature/references/research-gating.md` and `skills/start-feature/references/collect-import.md` — existing import flow (feature). Feature flow is *unchanged* until this phase. - `skills/workflow-knowledge/SKILL.md` and `scripts/knowledge.cjs` — KB indexing API. - `skills/workflow-knowledge/references/knowledge-usage.md` and `contextual-query.md` — existing query patterns. ## What ships -- New `.workflows/{wu}/imports/` directory convention. -- Manifest top-level `imports[]` array tracks imported files with `path` and `imported_at`. +- New `.workflows/{wu}/imports/` directory convention (already partially in place from Phase 4 for epics; this phase formalises it as the project-wide convention). +- Manifest top-level `imports[]` array tracks imported files with `path` and `imported_at` (Phase 1 added storage; Phase 4 wired epic-side writes; this phase adds KB indexing on those writes). - `start-epic` and `start-feature` `i`/`import` flows: - User provides one or more file paths. - Files copied to `.workflows/{wu}/imports/` (filename normalised if needed). @@ -34,8 +34,8 @@ Add the imports machinery: a top-level `imports/` directory, manifest tracking, - `skills/workflow-shared/references/import-files.md` — shared reference: copy files to `imports/`, push manifest entry, run KB index. Used by both `start-epic` and `start-feature`. **Modified:** -- `skills/start-epic/references/collect-import.md` — drop content into research file; route through inception. Use shared import-files reference. -- `skills/start-epic/references/route-first-phase.md` — `i`/`import` collects files, copies to imports/, then routes to inception (Phase 10 fully removes this file; here we modify it). +- `skills/start-epic/references/collect-import.md` — fold KB indexing into the existing flow (the file copy + manifest push were wired in Phase 4). Use shared import-files reference. +- `skills/start-epic/references/route-first-phase.md` — `i`/`import` flow continues to route through inception (Phase 12 fully removes this file). - `skills/start-feature/references/collect-import.md` — drop content into research file; copy to imports/, route to research with blank research file. - `skills/start-feature/references/research-gating.md` — adjust import flow. - `skills/workflow-inception-process/references/initialize-inception.md` — read imports from manifest at session start; load file content as context. @@ -48,7 +48,7 @@ Add the imports machinery: a top-level `imports/` directory, manifest tracking, - Auto-split imports into per-topic files (deliberately rejected — see design doc). - Removing imports via refinement (could be added later; not in this phase). -- Migration to relocate legacy merged-import content out of research files (legacy stays — see Phase 9 / design doc Migration section on legacy). +- Migration to relocate legacy merged-import content out of research files (legacy stays — see Phase 11 / design doc Migration section on legacy). ## Verification @@ -72,5 +72,5 @@ Add the imports machinery: a top-level `imports/` directory, manifest tracking, - **Filename normalisation** — be deterministic and avoid collisions (e.g. lowercase, replace spaces with hyphens). If a name conflict occurs in `imports/`, suffix with a counter or timestamp. - **KB metadata** — `source: import:{filename}` tag enables the user to ask "where did this context come from?" in any session. Useful for debugging. - **Inception reads directly, others use KB.** Inception doesn't have topics yet to query against, so reading imports as raw context makes sense. Once topics exist, KB retrieval is more efficient and per-topic-relevant. -- **Behaviour change for features is real and visible.** Document in changelog when Phase 11 ships. +- **Behaviour change for features is real and visible.** Document in changelog when Phase 13 ships. - **Don't split imports at import time.** Source integrity matters. KB chunking handles per-topic relevance dynamically. diff --git a/discovery-map/phase-07-topic-splitting-elevation.md b/discovery-map/phase-09-topic-splitting-elevation.md similarity index 92% rename from discovery-map/phase-07-topic-splitting-elevation.md rename to discovery-map/phase-09-topic-splitting-elevation.md index 2f667c76..65d9f2b0 100644 --- a/discovery-map/phase-07-topic-splitting-elevation.md +++ b/discovery-map/phase-09-topic-splitting-elevation.md @@ -1,6 +1,6 @@ -# Phase 7 — Topic Splitting and Elevation +# Phase 9 — Topic Splitting and Elevation -**Status:** Not started · **Depends on:** Phase 5 (and Phase 2 for inception items) +**Status:** Not started · **Depends on:** Phase 7 (and Phase 4 for inception items) ## Purpose @@ -29,17 +29,17 @@ Update the existing `topic-splitting` (research) and `topic-elevation` (discussi - `skills/workflow-discussion-process/references/discussion-session.md` — Section F (Topic Elevation): same pattern for the seeded discussion file. Inception item with `routing: discussion`, source `discussion-elevation:{parent}`. Same name validation. **Possibly new — shared validation reference:** -- `skills/workflow-shared/references/topic-name-validation.md` — validates a proposed topic name against active map items and the dismissed list. Returns "ok / collision-active / matches-dismissed". Used by topic-splitting, topic-elevation, refinement adds, direct-entry adds (Phase 8). +- `skills/workflow-shared/references/topic-name-validation.md` — validates a proposed topic name against active map items and the dismissed list. Returns "ok / collision-active / matches-dismissed". Used by topic-splitting, topic-elevation, refinement adds, direct-entry adds (Phase 10). ## Out of scope -- Direct-entry auto-add for unmapped topics (Phase 8). +- Direct-entry auto-add for unmapped topics (Phase 10). - Renaming existing topics that already have phase items (deliberately not supported per the editing-rules matrix — rename is for never-started only). - Reactivating cancelled phase work via splits (out of scope; user uses existing `e`/`reactivate`). ## Verification -1. Continue from a Phase 5 test epic where research is in progress on a topic with multiple threads. +1. Continue from a Phase 7 test epic where research is in progress on a topic with multiple threads. 2. Trigger topic-splitting (research-process detects substantial side-thread; offers to split). Confirm split. 3. Verify: - New research file created with extracted content. @@ -47,14 +47,14 @@ Update the existing `topic-splitting` (research) and `topic-elevation` (discussi - `phases.inception.items.{new-topic}` exists with `routing: research`, `source: research-split:{parent-topic}`. - Map render shows the new item as `◐ researching` with provenance line "from {parent-topic}". 4. Try splitting with a name that's already on the map — blocked, prompted for alternative. -5. Remove a topic via refinement (Phase 4) — name now in dismissed list. Try splitting with that name — allowed, dismissed-list entry removed. +5. Remove a topic via refinement (Phase 6) — name now in dismissed list. Try splitting with that name — allowed, dismissed-list entry removed. 6. Repeat for `topic-elevation` in a discussion session: same outcomes with `routing: discussion` and source `discussion-elevation:{parent-topic}`. 7. Compliance self-check passes on touched skill files. ## Notes for the implementer - **Asymmetry to enforce** — research and discussion *spawn* new map items but never modify existing ones. Don't accidentally add update-existing logic here. -- **User-explicit spawns bypass the dismissed list** — split/elevation are user-initiated; the dismissed list only blocks automatic re-adds by analyses (Phase 5). +- **User-explicit spawns bypass the dismissed list** — split/elevation are user-initiated; the dismissed list only blocks automatic re-adds by analyses (Phase 7). - **Cascade behaviour** — provenance is historical metadata, not a live reference. If the parent's phase work is later cancelled, the children stay on the map untouched. - **Renaming the parent post-split is blocked anyway** — parents of splits/elevations have phase work, so the editing-rules matrix forbids rename. No special-case handling needed. - **Content extraction is the explicit exception** — these flows do extract content (unlike post-conclusion analysis-derived items). Keep that distinction clear in any code comments and docs touched. diff --git a/discovery-map/phase-08-direct-entry-auto-add.md b/discovery-map/phase-10-direct-entry-auto-add.md similarity index 95% rename from discovery-map/phase-08-direct-entry-auto-add.md rename to discovery-map/phase-10-direct-entry-auto-add.md index 526d2d2f..4c6ea8e0 100644 --- a/discovery-map/phase-08-direct-entry-auto-add.md +++ b/discovery-map/phase-10-direct-entry-auto-add.md @@ -1,6 +1,6 @@ -# Phase 8 — Direct-Entry Auto-Add +# Phase 10 — Direct-Entry Auto-Add -**Status:** Not started · **Depends on:** Phase 5 (and Phase 7 for shared name validation if extracted) +**Status:** Not started · **Depends on:** Phase 7 (and Phase 9 for shared name validation if extracted) ## Purpose @@ -12,7 +12,7 @@ When the user picks `d`/`discuss` or `r`/`research` from `continue-epic` and pro - `skills/continue-epic/references/epic-display-and-menu.md` — current `d`/`discuss` and `r`/`research` flows. - `skills/workflow-research-entry/SKILL.md` — entry skill that gets invoked. - `skills/workflow-discussion-entry/SKILL.md` — same. -- `skills/workflow-shared/references/topic-name-validation.md` (if extracted in Phase 7) — name validation helper. +- `skills/workflow-shared/references/topic-name-validation.md` (if extracted in Phase 9) — name validation helper. ## What ships @@ -39,7 +39,7 @@ When the user picks `d`/`discuss` or `r`/`research` from `continue-epic` and pro ## Verification -1. Continue from a Phase 7 test epic. +1. Continue from a Phase 9 test epic. 2. From `/continue-epic`, pick `d`/`discuss`; provide a topic name not on the map (e.g., "feedback-mechanisms"). Verify: - Inception item created: `phases.inception.items.feedback-mechanisms` with `routing: discussion, source: direct-start`. - Discussion entry invoked with the topic. diff --git a/discovery-map/phase-09-migration.md b/discovery-map/phase-11-migration.md similarity index 97% rename from discovery-map/phase-09-migration.md rename to discovery-map/phase-11-migration.md index 74c81755..34ade7a0 100644 --- a/discovery-map/phase-09-migration.md +++ b/discovery-map/phase-11-migration.md @@ -1,6 +1,6 @@ -# Phase 9 — Migration +# Phase 11 — Migration -**Status:** Not started · **Depends on:** Phase 5 (analyses re-pointed) and Phase 3 (map render) +**Status:** Not started · **Depends on:** Phase 7 (analyses re-pointed) and Phase 5 (map render) ## Purpose diff --git a/discovery-map/phase-10-drop-explore-mode.md b/discovery-map/phase-12-drop-explore-mode.md similarity index 83% rename from discovery-map/phase-10-drop-explore-mode.md rename to discovery-map/phase-12-drop-explore-mode.md index a20000e2..236164fc 100644 --- a/discovery-map/phase-10-drop-explore-mode.md +++ b/discovery-map/phase-12-drop-explore-mode.md @@ -1,6 +1,6 @@ -# Phase 10 — Drop Explore Mode in Research; Finalise start-epic +# Phase 12 — Drop Explore Mode in Research; Finalise start-epic -**Status:** Not started · **Depends on:** Phase 9 (migration must run first so existing epics with `exploration.md` are migrated) +**Status:** Not started · **Depends on:** Phase 11 (migration must run first so existing epics with `exploration.md` are migrated) ## Purpose @@ -21,7 +21,7 @@ Remove the open-mode (`e`/`explore`) research path. Under the new model, researc - `workflow-research-process/epic-session.md` no longer handles explore-mode logic — epic and feature sessions are now identical (per-topic). - `start-epic` Step 3 invokes `workflow-inception-entry` directly. No more menu. - `start-epic/references/route-first-phase.md` is **deleted**. -- The `i`/`import` flow at start-epic time is preserved (Phase 6 wired it through inception). +- The `i`/`import` flow at start-epic time is preserved (Phase 8 wired it through inception with KB indexing). - Cross-references to removed files cleaned up. ## Files @@ -39,13 +39,13 @@ Remove the open-mode (`e`/`explore`) research path. Under the new model, researc ## Out of scope -- Migrating legacy `exploration.md` files (Phase 9 handled it; legacy stays as a regular topic). +- Migrating legacy `exploration.md` files (Phase 11 handled it; legacy stays as a regular topic). - Removing `surfaced_topics` / `gap_topics` arrays from manifests (a separate cleanup migration if/when it lands). -- Documentation updates (Phase 11). +- Documentation updates (Phase 13). ## Verification -1. Continue from a Phase 9 test epic. +1. Continue from a Phase 11 test epic. 2. `/start-epic` for a brand-new epic goes directly to inception with no intermediate menu. 3. From `continue-epic`, picking a research-routed item (`Start research for "{topic}"`) invokes `workflow-research-entry epic {wu} {topic}` with the topic argument. No explore-vs-specific prompt. 4. Research session proceeds on the topic; file is `research/{topic}.md`. No `exploration.md` is created for new topics. @@ -54,7 +54,7 @@ Remove the open-mode (`e`/`explore`) research path. Under the new model, researc ## Notes for the implementer -- **Sequencing matters** — Phase 9 must merge before this so existing epics are already migrated. Otherwise users with legacy state might lose visibility into their `exploration.md` files (the migration registers them; without migration, dropping explore-mode could orphan them). +- **Sequencing matters** — Phase 11 must merge before this so existing epics are already migrated. Otherwise users with legacy state might lose visibility into their `exploration.md` files (the migration registers them; without migration, dropping explore-mode could orphan them). - **Don't try to retroactively rename legacy "exploration" topics** — the editing-rules matrix forbids rename for items with phase work. Legacy stays as-is. New epics use proper topic names. - **epic-session.md and feature-session.md may converge** — once explore-mode is gone, the only difference between them is the topic-splitting offer (which exists only in epic). Implementer may want to consolidate; or keep separate for clarity. Either is fine. - **Cross-references** — search the codebase for any remaining references to `route-first-phase`, `exploration.md`, `e`/`explore` mode and update. diff --git a/discovery-map/phase-11-documentation.md b/discovery-map/phase-13-documentation.md similarity index 97% rename from discovery-map/phase-11-documentation.md rename to discovery-map/phase-13-documentation.md index 1c84e412..5a88cb45 100644 --- a/discovery-map/phase-11-documentation.md +++ b/discovery-map/phase-13-documentation.md @@ -1,6 +1,6 @@ -# Phase 11 — Documentation Cleanup +# Phase 13 — Documentation Cleanup -**Status:** Not started · **Depends on:** Phase 10 (final phase) +**Status:** Not started · **Depends on:** Phase 12 (final phase) ## Purpose @@ -47,7 +47,7 @@ Update project-level documentation to reflect the new phase model. CLAUDE.md, RE ## Out of scope -- New skill behaviour (everything functional shipped in Phases 1-10). +- New skill behaviour (everything functional shipped in Phases 1-12). - Removing legacy file references that have been deprecated but not deleted (e.g., the post-migration legacy `exploration.md` files stay; documentation should describe them as legacy if it mentions them at all). ## Verification