project-clarify

Project Clarify

project-clarify is an explicit, user-invoked project stage. One $project-clarify request starts a continuous clarification session: after each frontier round the user replies normally, the next frontier is recomputed and presented again, and only shared-understanding confirmation (or an explicit exit/switch) produces the bounded handoff for project-spec. The user does not need to type $project-clarify again between rounds.

Required order

1. Inspect project facts before asking. If docs/agents/light-project.md exists, read its goal, outputs, domain-context locators, and tracker locator first. Then inspect the named material plus relevant README, instructions, source/tests/specs, and tracker state. Record each usable fact with a stable locator; mark missing or unreadable material as an evidence gap. Facts that inspection can settle are not user questions.
2. Maintain user decisions with socratic. Pass inspected facts, unknowns, existing decisions, and the goal to the socratic engine. Ask the complete current frontier as a round — multiple independent questions with choices, a recommended option, and a useful short reason when appropriate. Do not ask one question at a time by default.
3. Resolve fact and experiment gaps deliberately. For a fact gap, state which decision it blocks and record the authorized capability call (light-research, light-prototype, light-to-questionnaire) in the ledger. Never mark a result as read without a result path actually read; leave unavailable or not-authorized gaps unresolved and keep their downstream decisions out of the frontier.
4. Continue until completion, then return the handoff and stop. After every ordinary user reply, use socratic again to recompute the frontier and present the next round. When no meaningful frontier remains, confirm shared understanding; after confirmation return the handoff and stop. Do not require a repeated $project-clarify invocation for normal replies.

Handoff shape

Project clarification handoff
- Target and inspected project facts:
- Evidence not found or not inspected:
- Current goal and constraints:
- Resolved user decisions:
- Open decisions and dependencies:
- Capability call records and results read:
- Current frontier or explicit blocker:
- Recommended next explicit invocation: project-spec | decision-map | none
- Status: ready-for-next-stage | waiting-for-user | blocked

Return the handoff in memory by default. When the next stage may run in another session, offer to save it at .scratch/<feature>/clarify-handoff.md (or a destination the user names). Write only after the user confirms. Then stop; the user chooses the next invocation.

Composition and upgrade

project-clarify → socratic

If the effort is large, multi-session, or has many dependent decisions, recommend $decision-map and stop. The full contract is in project-clarification-contract.md; workflow and examples are in WORKFLOW.md and EXAMPLES.md.