Discovery

Decide what to build — or whether to build at all — before a line of code. The one gate no other AI tool has.

Discovery is lightweight pre-work: clarify an idea, ticket or piece of feedback before committing engineering to it. It's the capability no other AI coding tool has — the judgment to recommend not building something yet, and to route ambiguous work to validation instead of code.

How it runs

Discovery runs read-only (L0–L1). It asks adaptive questions, scores the idea on deterministic, explainable criteria, and produces a recommendation — then creates or enriches a work item. It is not an implementation run.

In the m-shell, just ask — or run it as a command:

excalibur discovery "should we add contract-renewal reminders?"
excalibur discovery --from-file ./notes/feedback.md

excalibur — discovery

›/discovery add an AI summary to every invoice

→Q Who asked for this, and how often?

$two enterprise accounts last quarter

→Q What breaks if we don't build it?

$nothing urgent — a nice-to-have

clarity ▓▓▓▓▓▓▓░░ evidence ▓▓▓▓░░░░░░ scope ▓▓▓▓▓▓░░░░

⚑recommendation: needs_validation

✓validate demand with 3 design-partner calls first

→work item created · WI-142 (Backlog)

The diagnosis

Every session scores five dimensions and lands on a recommendation:

Dimension	Question it answers
Clarity	Is the problem actually well understood?
Evidence	Is there real signal it matters?
Scope	Is it sized right, or should it be split?
Risk	What could go wrong, and how reversible is it?
Readiness	Is it ready for an agent to build?

build_now → build_soon → needs_validation → needs_prototype → do_not_build

Where it goes

Sessions are stored locally with the full transcript and artifacts:

.excalibur/discovery/<id>/
├── transcript.md
├── discovery.json     # scores, recommendation, rationale
└── artifacts/         # scope notes, acceptance criteria, …

From the result you can promote the outcome — in-shell actions or CLI:

discovery create-work-item     # enrich the backlog (default)
discovery create-run           # build it now (confirms if not "build_now")
discovery save-decision        # record the rationale to project memory

The domain model

Discovery sits at the front of the cycle and produces the unit of work:

Idea → (Discovery) → Work item [Backlog → Ready] → Run(s) [Building → Review] → Done
                                                   └→ or: do_not_build → closed

Work item — the base unit of work (a backlog ticket). It can exist with zero runs.
Run — the agentic execution that fulfils a work item (a work item can have 0..N runs).
Discovery — pre-work that creates or enriches a work item. It is not a run.

In Enterprise, Discovery also runs from issue comments (@excalibur discovery|refine|readiness|…) and Slack threads, writing results straight back to Linear/Jira and the team backlog. See Enterprise.

Plan-shaping — co-create the plan before building

Once you are building, Excalibur shapes the plan with you instead of guessing. Before a multi-step build runs, it proposes a few clarifying questions whose answers would change the plan, plus a multi-select list of recommendations — related or commonly-forgotten work (tests, error handling, a migration, a feature flag, telemetry) with the high-value ones pre-checked. Your choices refine the scope before any code is written. It is gated: it stays silent on small or already-clear tasks and only surfaces when it genuinely helps (a large or under-specified plan). On a large build, an automatic read-only scope map runs first so the questions and recommendations are grounded in your real code, not guesses. The web dashboard has a plan-shaping panel for the same flow.

Workflows — the recipe a ready work item runs through.
Autonomy levels — how the resulting run executes.