| name | ultraplan-discover |
| description | Gray-area extraction stage — surfaces decisions the user must make before the plan can be authored, without expanding scope |
UltraPlan Discover
Identify the open decisions and ambiguities that block confident scenario authoring. This stage mirrors the GSD discuss phase. It runs after scout and before research. Its sole output is a set of decision records and, optionally, deferred-idea records.
Quick Reference
| Aspect | Detail |
|---|
| Inputs | Intake artifact + scout artifact (provided by pipeline runner) |
| Output | One ultraplan_decision_record call per decision area; deferred ideas via the same tool with deferred: true |
| Scope | Identification only — no library selection, no scenario generation |
| Scope guardrail | You MUST NOT expand scope beyond what the intake goal states |
| Storage tools | ultraplan_decision_record — one call per area |
Decision Areas
A decision area is any ambiguity that, if resolved differently, would materially change the plan's scenarios, slots, or test architecture. Examples:
| Category | Example Questions |
|---|
| Auth strategy | Session vs JWT vs OAuth provider — which applies? |
| API shape | REST vs GraphQL vs RPC — does the intake imply a choice? |
| Error semantics | Should errors surface to the UI or be swallowed silently? |
| Library choice | Is there an existing library in the scout, or is a new one needed? |
| Data ownership | Which service owns the canonical record? |
| Deployment target | Is this cloud-agnostic, or tied to a specific provider? |
| Test boundary | Should integration tests hit a real database or a test double? |
Classify Each Area
For each area you identify, assign a disposition:
- OPEN: The intake and scout provide no signal. The user must decide before authoring proceeds.
- RESOLVED-BY-SCOUT: The scout found an existing pattern that answers the question. Record what was found.
- RESOLVED-BY-INTAKE: The intake stated or clearly implied an answer. Record the answer.
- DEFERRED: The question is out of scope for this session. Record with
deferred: true.
Only OPEN areas require user input. RESOLVED areas are recorded for downstream stages to use as constraints.
Scope Guardrail
You MUST NOT add new requirements, features, or capabilities not present in the intake. If a discovery area reveals an attractive extension, record it with deferred: true and move on. The goal statement in the intake is the boundary.
Process
Step 1 — Read intake goal and success criteria
Anchor every decision area to a field in the intake. If an area cannot be linked to the intake goal, it is out of scope.
Step 2 — Read scout findings per stack
For each applicable stack, check whether the scout already resolved the area. Mark accordingly.
Step 3 — Record each area
Call ultraplan_decision_record once per area:
ultraplan_decision_record({
area: string, // short label, e.g. "auth-strategy"
category: string, // one of: auth, api-shape, error-semantics,
// library-choice, data-ownership, deployment, test-boundary, other
disposition: "OPEN" | "RESOLVED-BY-SCOUT" | "RESOLVED-BY-INTAKE" | "DEFERRED",
question: string, // the specific question to answer
resolution: string | null, // null when OPEN; the answer when RESOLVED or DEFERRED
deferred: boolean, // true when disposition is DEFERRED
affectedStacks: ("frontend" | "backend" | "infrastructure")[]
})
Step 4 — Verify scope
Before finishing, confirm: do all recorded areas trace to the intake goal? If any do not, mark them DEFERRED.
MUST DO / MUST NOT DO
| MUST DO | MUST NOT DO |
|---|
| Link every area to the intake goal | Introduce requirements not in the intake |
| Record RESOLVED areas even when no user input is needed | Skip an area because it seems obvious |
| Mark attractive extensions as DEFERRED | Silently fold deferred ideas into the plan |
Call ultraplan_decision_record once per area | Batch multiple areas into one call |
| Consult scout findings before marking an area OPEN | Ask the user to resolve something the scout already answered |
Final Checklist
