Pre-epic discovery: /nxs.discover and the fog referral gate

[sameera]

Epic: Pre-epic discovery: /nxs.discover and the fog referral gate

Description

Nexus's right-sizing gate measures size only. An XL or XXL intent decomposes immediately into
functional-goal stubs with candidate stories, which assumes the split is already knowable. For a
genuinely underspecified initiative the split itself hangs on unresolved decisions, so pre-slicing
is speculative over-generation, the exact failure mode Nexus guards against. Today Nexus conflates
oversized with underspecified and answers both with work-shaped stubs. No decision artifact can
exist before an epic does, because /nxs.decision-record requires a planned epic.

This epic adds a pre-epic discovery stage. /nxs.discover runs discovery as a multi-session loop
over a committed store. The store is a directory of its own outside the queue,
.nexus/discovery/discover-<slug>-<key>/, holding a discovery doc plus one decision-ticket
file per open decision. Ticket type and blocking edges are carried in ticket frontmatter. The
store sits outside .nexus/queue/, which is the directory every stage scans for drainable entries,
so no stage that scans the queue sees a discovery, and the distiller's range helper excludes the
discovery directory so in-flight reasoning never reaches concept-delta synthesis. Committing the
store is what makes a discovery shareable: a lead can push it to a fork
and hand it to a domain expert, and the loop needs no machinery beyond ordinary git operations.

Each session claims one open, unblocked ticket, resolves it through existing machinery, appends the
resolution to the ticket file, appends one gist line to the discovery doc's index, and commits. A
ticket is a question whose resolution is a decision, never a slice of build work. Coarser suspicions
stay in a "Not yet specified" section until a resolution makes them precisely statable. Work ruled
beyond the destination lands in "Out of scope" and never graduates. The loop ends when every
functional goal is sharp enough to state as a backlog stub of size M or smaller.

/nxs.discover never writes to GitHub. Graduation is a new entry mode on /nxs.epic that reads a
finished discovery folder. That mode skips the sharpness gate, because discovery is what the gate
refers people to, and then runs the existing right-size gate unchanged. A result larger than size M
files the stub batch the decomposition path already files, one stub per functional goal. A result of
size M or smaller is planned directly as one epic with its stories. Discovery therefore adds no
second issue-creating surface.

The ticket files are removed when the discovery folder is removed, so the resolved decisions travel
with the stubs. Each stub carries the decisions it hangs on in full gist form, written from the same
text into the stub body and into a comment carrying a hidden marker. Promotion rewrites the stub
body, so the marked comment is the copy that survives. /nxs.decision-record then reads the marked
comments off the epic issue and treats them as an input to the record it writes. The reasoning
discovery produced reaches the design stage instead of stopping at the backlog.

A discovery whose resolutions conclude that no build follows ends through the /nxs.discover close
action, which writes a dated lessons note and removes the folder in one commit.

/nxs.epic also gains a thin referral gate inside its right-size phase. If the intent's functional
goals cannot be stated sharply, it stops and recommends /nxs.discover, with an explicit override
that falls through to the existing sizing path. The existing oversized path stays for the
big-but-clear case. The pipeline becomes
setup → (discover when foggy) → epic → decision-record → analyze → close → distill.

Success Metrics

• A foggy initiative can be driven from first intent to promotable backlog stub issues without any
  GitHub issue of any kind being filed during discovery. Issues appear only when /nxs.epic
  consumes the finished discovery.
• Every stub filed from a discovery is accepted unchanged by /nxs.epic <issue-number> promotion,
  with the same labels, classification, and body meta as a decomposition stub, because the same
  emission path files both.
• Each resolved decision is reachable from the discovery doc in one hop: a one-line gist naming the
  ticket file that holds the detail.
• The reasoning reaches the design stage. After a discovery-filed stub is promoted,
  /nxs.decision-record run against that epic names the decisions the discovery resolved.
• /nxs.epic given an underspecified intent stops and recommends /nxs.discover instead of filing
  work-shaped stubs. Given a big-but-clear intent it still offers the oversized split.

Personas

Per docs/product/context.md. The acting persona throughout is the delivery lead (or PM) driving
the Nexus pipeline. Decision tickets may pull in domain humans through interview-typed tickets.

Assumptions

• Discovery state is committed. It lives in .nexus/discovery/discover-<slug>-<key>/, a directory
  of its own outside the queue, which holds the discovery doc and one file per ticket. Living
  outside .nexus/queue/ is what puts a discovery out of reach of every stage that scans the
  queue, and the distiller's range helper excludes the directory as well. The unique key exists because a discovery
  has no issue number to be named by, and because two contributors may independently start on the
  same intent. /nxs.discover commits each session and never pushes.
• Sharing a discovery is an ordinary git push and pull. This epic adds no discovery review gate, no
  approval command, and no rule about who may start, resume, or graduate a discovery.
• Ticket type (research, interview, council, or task), blocking edges, the claim, and the status are
  frontmatter fields on the ticket file. Each has a one-to-one GitHub equivalent, so migrating the
  store to an issue-backed one later is a translation rather than a redesign. Wayfinder's
  "prototype" ticket type has no Nexus machinery and is dropped; prototype-shaped questions route to
  interview or council tickets.
• /nxs.discover selects its action by explicit flag, matching the command surface's rule. Passing
  intent text starts a discovery. Resuming and closing are named actions taking the discovery folder.
• The stubs' feature is confirmed once at start and recorded in the discovery doc, with a per-stub
  override at graduation.
• Discovery resolves the docs root and the target issues repository exactly as /nxs.epic does. The
  store lives in the checkout the command runs in and never migrates, because nothing ever drains a
  discovery folder. Graduation files into the resolved epic repository. Hub and multi-repository
  workspaces are untested this iteration, not blocked.

Out of Scope

• New agents or skills. Every ticket type routes to existing machinery.
• Prototype tooling.
• Changes to /nxs.analyze and /nxs.close behavior. /nxs.decision-record gains
  exactly one change, a read of the marked gist comments, and nothing else. (Amended 2026-08-09:
  this line originally excluded /nxs.distill as well. Decision record Decision Record: Pre-epic discovery: /nxs.discover and the fog referral gate #235 puts the distiller's
  exclusion of .nexus/discovery inside this decision, so that change is in scope. See the
  amendment below.)
• Changes to promotion. It rewrites the stub's body on the issue the stub was filed under, and it
  neither reads nor moves the gist comment.
• Automation of the human side of interview-typed tickets.
• Removal of the discovery folder by /nxs.epic. The folder is removed by a human commit after
  graduation, or by the no-build close.
• An issue-backed discovery store. That migration is its own epic if the committed store falls short.

Open Questions

Amendments

• 2026-08-09 — The discovery store moved from .nexus/queue/discover-<slug>-<key>/ to
  .nexus/discovery/discover-<slug>-<key>/. Decision record Decision Record: Pre-epic discovery: /nxs.discover and the fog referral gate #235, approved 2026-08-08 and therefore
  later than this body, reverses the in-queue placement and refutes it by name. A discovery is now
  kept out of the queue-scanning stages by where it lives rather than by the absence of an
  epic.md, which is the stronger of the two mechanisms. This body and story Start discovery from a foggy initiative #229 were amended to
  match the approved record and the implementation.
• 2026-08-09 — /nxs.distill behavior moved from "Out of Scope" into this epic. Decision record
  Decision Record: Pre-epic discovery: /nxs.discover and the fog referral gate #235, approved 2026-08-08 and therefore later than this body, says in invariant 2 that keeping a
  discovery out of the distiller's behavioral diff is part of this decision and not a later step.
  The shipped work is that exclusion plus the close-time empty-diff gate, which reads the same
  diff and has to stay in step with it. The line above was amended so a later reader sees planned
  scope rather than drift.