epic #228: Pre-epic discovery: /nxs.discover and the fog referral gate - #241
Draft
sameera wants to merge 8 commits into
Draft
epic #228: Pre-epic discovery: /nxs.discover and the fog referral gate#241sameera wants to merge 8 commits into
sameera wants to merge 8 commits into
Conversation
Add /nxs.discover with its start action. Start names the destination first — pinned to Nexus's contract that discovery ends when every functional goal is a backlog stub of size M or smaller — confirms it and the feature with the user, then creates a committed folder holding the discovery doc and one file per decision ticket. The store lives under .nexus/discovery/, a sibling of the queue rather than a folder inside it. The queue holds only closed, drainable entries, and a discovery is never closed and never drained, so location alone keeps a discovery out of reach of the distiller's scan and of the /nxs.analyze and /nxs.decision-record resolutions — no stage has to learn a filename convention. The distiller excludes .nexus/discovery/** from its behavioral diff analysis alongside the queue, so discovery prose can never become a concept delta; that exclusion ships here because it is part of the store decision rather than a later step. Committing the store is what makes a discovery shareable by ordinary git operations. Start commits, never pushes, and writes nothing to GitHub. A suspicion that cannot be stated precisely goes to "Not yet specified" rather than becoming a ticket. Start fires the research agents and stops; it resolves no ticket, because a fact is not a decision. Closes #229
Add the resume action to /nxs.discover. A session claims exactly one open, unblocked ticket before any work begins, resolves it through machinery that already exists, appends the resolution to the ticket file, appends one gist line to the discovery doc's index, graduates whatever fog the resolution made precisely statable, commits, and stops. The claim records who and when rather than a boolean, because a stale claim must be takeable and the takeover recorded. Its scope is one working tree: two clones never see each other's claims, and a merge conflict is what tells them they collided. An agent's output is evidence on the ticket, never a resolution — only the session marks a ticket resolved, because a fact is not a decision. Council tickets are orchestrated inside the session rather than handed to /nxs.council, since a slash command cannot invoke another and the ticket must not sit claimed across a session boundary. Closes #230
…th no build Add the discovery entry mode to /nxs.epic and the close action to /nxs.discover. /nxs.epic --discovery <folder> treats a finished discovery doc as its intent, skips the sharpness precondition — discovery is the thing that precondition refers people to — and runs the existing right-size gate unchanged. A result larger than M files the stub batch the decomposition path already files; a result of M or smaller is planned directly as one epic. Discovery therefore adds no second issue-creating surface, which is what makes a discovery-produced stub accepted unchanged by promotion true by construction. Each stub carries the decisions it hangs on in full gist form, written twice from the same text: once in the body, which promotion consumes, and once as a comment carrying a hidden marker, which is the copy that survives the body rewrite. The comment is the only addition the discovery mode makes to the emission path. Neither copy is ever edited again, so they cannot drift. The close action is the terminal act for the one outcome /nxs.epic never sees. It writes a dated lessons note carrying the destination, the resolved-decisions index in full, and the no-build conclusion, and removes the folder in the same commit, so the record cannot be deleted without its replacement landing. Closes #231
Add the sharpness precondition to the right-size phase, before sizing. The test is the stub shape itself: can each functional goal be stated as a one-line goal, with a small estimate, and with candidate story titles? If decomposition cannot produce that shape the intent is underspecified rather than merely oversized, and /nxs.epic stops and recommends /nxs.discover, filing nothing. The stop offers an explicit override that falls through to the existing sizing path, because the sharpness call is a judgement the lead owns and a hard refusal would make a false positive unrecoverable. The gate lives inside the right-size phase rather than as a phase of its own, so it inherits the skip-in-promotion rule for free and adds no new machinery. It does not fire in promotion or discovery mode: a promoted stub was already discovered, and a consumed discovery is the output of the very thing the gate refers people to. A sharp, right-sized intent sees no new interaction, and the oversized path is unchanged. Closes #232
README.md, how-to-nexus.md, and the project CLAUDE.md now show setup → (discover when foggy) → epic → decision-record → analyze → close → distill, and each carries the stage's durable contract: discovery is a multi-session loop, its unit is the decision ticket, its output is functional goals that /nxs.epic files, and a discovery is shared by ordinary git operations. The collaboration property is part of the contract because a reader needs it to know they can hand a discovery to someone else. All three distinguish oversized (big but clear, /nxs.epic's decomposition path) from underspecified (foggy, /nxs.discover), and all three state that discovery writes nothing to GitHub — the issues appear when /nxs.epic consumes the finished discovery. Where the store physically lives is confined to a single sentence per document, explicitly marked as first-iteration, so a later migration to an issue-backed store is a one-line documentation edit rather than a sweep. Closes #233
Before it analyses, the command now fetches the epic issue's comments and keeps the ones carrying the discovery marker. Those gists become an authoritative input to the architect alongside the epic and its stories, so the record is designed on top of the decisions the discovery already settled instead of re-deriving them. They do not replace the analysis. The command still designs the epic and still checks that every story is covered, which is why the gists are not routed through --from: import mode treats its document as the design, whereas a gist decides what to build and at what scope, settles almost nothing about how, and carries no invariants. A gist that states a decision without its reasoning becomes an open clarification for the human, exactly as an unexplained decision in an imported design doc does today. Only marked comments are read, because an epic issue accumulates ordinary discussion. An epic with no marked comment behaves exactly as before — no new prompt and no empty section. The command never edits or removes the comments. Closes #240
sameera
force-pushed
the
feat/pre-epic-discovery-228
branch
from
August 8, 2026 13:13
2c9440b to
b0f2db4
Compare
The distiller's range helper now excludes `.nexus/discovery` alongside `.nexus/queue`, which is the enforcement point record #235 invariant 2 named and `nxs.distill.md` already claimed. A branch carrying discovery prose and code together can no longer feed ungated reasoning into concept-delta synthesis. The no-build lessons note carries one full gist per resolved decision instead of the index verbatim. The index line ends in a ticket filename, and the same commit removes every ticket file, so the only durable artifact on that path was shipping with pointers that were dead on arrival. Also fixes two wrong internal step references in `nxs.epic.md`, and records the five analyze-pass walkthroughs record #235 requires. Four ran with artifacts; the live GitHub half of the fifth did not, and the notes say so. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Updates to command documentation, decision records, and improvements to pr-acceptance and pr-worktree range verification. Ref: 52172fb4-ec00-4a3a-ab04-da6e934af12b Co-Authored-By: Claude Haiku 4.5 <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.
Implements the story sub-issues of #228, one commit per story in blocked_by order.
Each commit body carries its own
Closes #<story>line, so merging this PRinto
maincloses the stories it implements. The epic itself closes through/nxs.close, not by merge.Draft opened by
utils/implement-epic.sh;/nxs.analyzeruns against it next.