Discovery

discovery - develop the plans through a deep conversation

Context reuse: Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.

First action: Before project inspection, preflight, or any other tool call, publish running to blueprint/.state/run.json using the dashboard activity contract in AGENTS.md.

Where this can sit in the workflow:

/onboard  ->  write the plans directly  ->  /overview
          \
           ->  [discovery]  ->  review and approve plan drafts  ->  /overview

/discovery is an optional planning partner, not a required workflow gate and not a quick questionnaire. It can span as many turns as the project needs. Its job is to help the user think through the product, preserve the depth and nuance of that conversation, and draft the two user-owned planning files only when the user asks for drafts.

Running /onboard never starts this skill. Empty plans never require it. A user who writes detailed plans manually, has another AI conversation, or arrives with finished plans continues directly to /overview exactly as before.

For a focused idea or technical tradeoff without drafting plans, use /explore. Discovery develops the broader product plans.

Step 1 - establish the starting point

Read only the planning and project facts needed for the conversation:

• blueprint/project-plan.md
• blueprint/build-plan.md
• the root project manifest, README, and framework configuration when they already contain relevant facts
• blueprint/context/project-overview.md only when the user is revisiting an established project's direction

Classify each planning file as a template, partial draft, or substantive plan. Never treat existing user content as disposable. When either plan has real content, summarize what it already establishes and ask whether the user wants to deepen it, revise a specific direction, or use it unchanged as conversation context. Do not replace it with a fresh generic plan.

Start with a short working hypothesis about the project and name the most important unknown. Then ask one focused question. Do not draft either plan yet.

Step 2 - run adaptive discovery

Ask one meaningful question at a time and let each answer shape the next one. Prefer a likely interpretation the user can correct over a vague request for more detail. Explain a tradeoff when the answer would materially change scope, architecture, cost, or build order.

Cover the areas that matter to this project, not a fixed questionnaire:

• problem, desired outcome, and why the project should exist
• target users, their context, and their primary workflows
• MVP capabilities, explicit non-goals, and later possibilities
• business rules, data, integrations, permissions, and important edge cases
• stack choices, constraints, dependencies, and technical unknowns
• UI/UX direction, accessibility needs, and useful references
• monetization or business model when relevant
• deployment shape, environments, background work, storage, and operations
• risks, assumptions, unresolved decisions, and how success will be judged
• feature boundaries, dependencies, and a sensible build order

Depth is the goal. Follow a consequential answer until its implications are clear instead of racing to the next category. Do not ask the user to repeat facts already established in the conversation or repository. Do not force irrelevant topics merely to complete a checklist.

Follow the proportional-engineering contract in AGENTS.md: ask about optional usage or trust constraints only when they materially change the solution, record established non-requirements, and leave unknowns blank.

Periodically return a compact discovery snapshot with:

• confirmed decisions
• working assumptions that still need confirmation
• open questions or conflicts
• ideas explicitly deferred or excluded

The snapshot keeps a long conversation coherent. It is not permission to write the plans.

Step 3 - decide whether the plans are ready

Do not end discovery because a preset number of questions has been reached. It is ready to draft when:

• the problem, users, and core workflows are concrete
• MVP scope and non-goals are distinguishable
• data and technical choices are detailed enough to expose major dependencies
• the build order can be expressed as feature-sized outcomes
• important contradictions are resolved
• remaining unknowns are either safe to defer or explicitly accepted as TODOs
• the user says they are ready for the plans to be drafted

If the user asks for drafts while a material gap remains, name the gap and ask whether to continue discovery or preserve it as an explicit TODO. Respect the choice. The user may also stop at any time and write the plans manually.