Skip to content

inception(phase-10): direct-entry auto-add via shared ensure-inception-item ref#275

Open
leeovery wants to merge 8 commits into
idea/inception-pr-9-split-elevationfrom
idea/inception-pr-10-direct-entry
Open

inception(phase-10): direct-entry auto-add via shared ensure-inception-item ref#275
leeovery wants to merge 8 commits into
idea/inception-pr-9-split-elevationfrom
idea/inception-pr-10-direct-entry

Conversation

@leeovery
Copy link
Copy Markdown
Owner

@leeovery leeovery commented May 11, 2026

Summary

Phase 10 of the inception/discovery-map initiative. Closes the last surface where map writes were silently bypassed: direct-entry from /continue-epic via d/discuss and r/research. After this PR, every research/discussion topic that gets created by the entry skills also lands on the discovery map with source: direct-start and the chosen routing.

  • New shared reference skills/workflow-shared/references/ensure-inception-item.md — idempotent: exists check returns immediately if the item is already on the map; otherwise pulls the topic from dismissed[] (user-explicit spawns bypass dismissal per design) and writes init-phase + routing + source: direct-start.
  • workflow-research-entry/SKILL.md loads it at the start of Step 2 (covers Step 1 → Step 2 paths). references/gather-context.md gains a final section F that loads it before returning to caller (covers the no-topic-epic Step 1 → Step 4 → Step 5 path which bypasses Step 2). Idempotency makes the redundant invocation when Step 4 loads gather-context after Step 2 a safe no-op.
  • workflow-discussion-entry/SKILL.md loads it at the start of Step 2 (resume + fresh paths converge there) and inside Step 1's topic-provided-but-not-exists branch (which routes to Step 3 and bypasses Step 2).

No continue-epic, manifest.cjs, discovery-utils.cjs, or knowledge-base changes — every existing surface (resume, refinement adds, splits, elevations, self-healing) keeps working untouched. source: direct-start rendering already exists in computeSourceProvenance with passing fixtures. No migration in this PR — Phase 11 backfills any pre-Phase-10 orphans where direct-entry left a research/discussion item without a corresponding inception entry.

Stacked on idea/inception-pr-7-self-healing (PR #272). Sibling of Phase 8 (imports) and Phase 9 (split/elevation) — INDEX.md records all three as branching from Phase 7. Doesn't depend on Phase 9's topic-name-validation.md (its collision-active rejection semantics don't fit the resume-or-create direct-entry contract; direct manifest checks are cleaner here).

Test plan

  • bash tests/scripts/test-workflow-manifest.sh — 214/214
  • node --test tests/scripts/test-discovery-for-*.cjs tests/scripts/test-discovery-utils.cjs tests/scripts/test-refinement-session.cjs — 329/329 (incl. existing direct-start provenance fixture)
  • All 38 migration tests pass
  • Knowledge tests pass (store/chunker/config/embeddings/openai/retry/integration/cli/build)
  • End-to-end smoke (manual): direct-entry research with new topic → inception item created with routing: research, source: direct-start
  • End-to-end smoke (manual): direct-entry discussion with new topic → inception item with routing: discussion, source: direct-start
  • End-to-end smoke (manual): direct-entry with existing-name → resume flow unchanged (idempotent no-op)
  • End-to-end smoke (manual): direct-entry with dismissed name → name pulled from dismissed[], fresh inception item created
  • End-to-end smoke (manual): bypass invocation (/workflow-research-entry epic foo new-topic) → inception item auto-created identically

🤖 Generated with Claude Code

leeovery added a commit that referenced this pull request May 11, 2026
@leeovery @claude
docs(discovery-map): record PR #275 for Phase 10
28bd8a3 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
leeovery and others added 8 commits May 11, 2026 22:19
@leeovery @claude
inception(workflow-shared): add ensure-inception-item.md for direct-e…
2b6a242 
…ntry auto-create

Idempotent shared reference that creates a phases.inception.items.{topic}
entry with source: direct-start and caller-supplied routing. Pulls from
dismissed[] first if needed; no-ops if the item already exists. Loaded by
workflow-research-entry and workflow-discussion-entry to keep the discovery
map honest when the user starts a new topic via d/discuss or r/research.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(workflow-research-entry): auto-create inception item on dir…
6c4954d 
…ect-entry research

Loads ensure-inception-item.md at the start of Step 2 (covers paths where
Step 1 resolves topic and routes to Step 2). Adds a new section F at the
end of gather-context.md (covers the no-topic-epic path where Step 1
routes through Step 4 and bypasses Step 2). The shared ref is idempotent,
so the redundant invocation when Step 4 loads gather-context after Step 2
is a safe no-op.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(workflow-discussion-entry): auto-create inception item on d…
51b82e1 
…irect-entry discussion

Loads ensure-inception-item.md at the start of Step 2 (Validate Phase) for
the resume-and-fresh paths that converge there, and inside Step 1's
topic-provided-but-not-exists branch (which routes to Step 3 and bypasses
Step 2). Idempotency makes the redundant Step-2 invocation a safe no-op.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
docs(discovery-map): record PR #275 for Phase 10
649eca5 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(workflow-shared): gate ensure-inception-item on work_type=epic
6a32434 
Research and discussion entry skills are invoked for features, bugfixes,
and cross-cutting work units too. Without gating, the shared reference
would silently call init-phase on phases.inception for non-epic manifests
and create a phantom inception entry where one should never exist. Add a
work_type parameter and an early-return Gate section so the reference is
a no-op for anything other than epic.

Also restructure the dismissed-list read to probe with `exists` first
instead of calling `get` and letting it surface "Path not found" on the
common case where no topic has ever been dismissed. And add the missing
arrow on the gather-context F Load directive (reference-file → reference-
file routing requires it per CONVENTIONS).

Callers updated to pass work_type alongside the existing parameters.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(workflow-shared): align ensure-inception-item with codebase…
ce42d09 
… H4 idioms

Polish from a second review pass:

- Section A: lead with the positive case + #### Otherwise, matching
  topic-name-validation's binary-choice idiom rather than two #### If
  clauses.
- Sections B and C: switch the bare #### If `true` / #### If `false`
  to #### If exists (`true`) / #### If not exists (`false`), matching
  the existing pattern in workflow-research-entry/SKILL.md Step 2 and
  giving a reader scanning H4s the predicate, not just the value.
- Section C: order the truthy branch first to match the rest of the
  codebase.
- gather-context F: fix the narrative — Step 4 doesn't run the load,
  Step 2 does. Spell out both idempotency cases (existing item + non-
  epic gate) plainly.

No behavioral change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
inception(workflow-research-entry): cover cross-cutting in routing + …
8b080d8 
…make explore topic explicit

Two pre-existing issues caught while reviewing Phase 10:

1. SKILL.md Step 1 had branches for feature and epic but none for
   cross-cutting. start-cross-cutting and continue-cross-cutting both
   route through workflow-research-entry, so cross-cutting invocations
   were silently falling through every #### If with no routing target.
   Combine into "feature or cross-cutting" — both follow the same
   single-topic, topic-equals-work-unit-name pattern.

2. gather-context.md section A's explore branch set resolved_filename
   = exploration.md but never explicitly assigned topic, leaving
   downstream consumers (now including F's ensure-inception-item)
   relying on Claude inferring topic = exploration. Mirror the
   import-epic pattern in SKILL.md and assign topic explicitly. Also
   fold cross-cutting into the same gather-context branch as feature.

   While here, made the specific branch's topic assignment explicit
   too — User provides topic name → set topic to the kebab-cased
   response — so both branches treat topic as a first-class variable.

No behavioral change for in-spec invocations; the cross-cutting fix
unblocks a flow that was previously broken.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery @claude
docs(entry-skills): refresh Workflow Context tables for inception + p…
b695d96 
…er-work-type pipelines

The Workflow Context block in every entry skill is the orientation
table Claude reads to know "where am I, what comes before and after,
what shouldn't I do here." After Inception was introduced the tables
went stale in two ways: they still said "six-phase workflow" with no
mention of Inception, and they pretended every skill saw the same
linear pipeline when in fact the pipeline shape depends on the work
type.

Replace each multi-work-type entry skill's table with a per-work-type
pipeline view, with the current phase bolded in each row:

- workflow-research-entry — epic / feature / cross-cutting
- workflow-discussion-entry — epic / feature / cross-cutting
- workflow-specification-entry — epic / feature / bugfix / cross-cutting
- workflow-planning-entry — epic / feature / bugfix
- workflow-implementation-entry — epic / feature / bugfix / quick-fix
- workflow-review-entry — epic / feature / bugfix / quick-fix

Single-work-type entry skills (inception, investigation, scoping)
collapse to a single pipeline line, dropping the now-redundant
"Phase X" framing.

Also bring CLAUDE.md and README.md into line: add Inception as #1 in
CLAUDE.md's Workflow Phases list and to the epic pipeline shape, and
fix README.md's pipeline diagram to include Inception for epics.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@leeovery leeovery force-pushed the idea/inception-pr-10-direct-entry branch from 1fbc5fd to b695d96 Compare May 11, 2026 21:20
@leeovery leeovery changed the base branch from idea/inception-pr-7-self-healing to idea/inception-pr-9-split-elevation May 11, 2026 21:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@leeovery