project-clarify

Project Clarify

project-clarify 是一个由用户显式调用的项目阶段。一次 $project-clarify 请求会启动一个持续的澄清会话： 每轮前沿问题结束后，用户正常回复，随后重新计算并呈现下一轮前沿问题；只有在确认双方理解一致（或明确退出／切换）后，才会为 project-spec 生成有界的交接内容。 用户无需在各轮之间再次输入 $project-clarify。

必需顺序

1. 提问前检查项目事实。 如果 docs/agents/light-project.md 存在，先读取其中的目标、输出、领域背景定位信息和跟踪器定位信息。然后检查指定材料，以及相关的 README、说明、源代码／测试／规范和跟踪器状态。 为每条可用事实记录稳定的定位信息；将缺失或无法读取的材料标记为证据缺口。检查即可确定的事实不应作为用户问题提出。
2. 使用 socratic 维护用户决策。 将检查到的事实、未知事项、现有决策和目标传递给 socratic 引擎。将当前完整的前沿问题作为一轮提出——包含多个相互独立的问题、可选项、推荐选项，并在适当时附上简短且有用的理由。默认不要一次只问一个问题。
3. 有意解决事实和实验缺口。 对于事实缺口，说明它阻碍了哪项决策，并在台账中记录获准调用的能力（light-research、light-prototype、light-to-questionnaire）。除非确实读取了结果路径，否则绝不将结果标记为已读取；对于不可用或未获授权的缺口，应保持未解决状态，并将其下游决策排除在前沿问题之外。
4. 持续推进直至完成，然后返回交接内容并停止。 每次收到用户的普通回复后，都再次使用 socratic 重新计算前沿问题，并呈现下一轮。当不再存在有意义的前沿问题时，确认双方理解一致；确认后返回交接内容并停止。普通回复无需再次调用 $project-clarify。

交接格式

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

默认将交接内容保留在内存中。如果下一阶段可能在另一个会话中运行，请提出将其保存到 .scratch/<feature>/clarify-handoff.md（或用户指定的目标路径）。只有在用户确认后才写入。随后停止；由用户选择下一次调用。

组合与升级

project-clarify → socratic

如果工作量较大、需要多个会话或包含许多相互依赖的决策，请推荐 $decision-map 并停止。完整约定见 project-clarification-contract.md； 工作流和示例见 WORKFLOW.md 和 EXAMPLES.md。