--- name: development-task-understanding description: 通用开发生命周期的「任务理解与现状调查」阶段 owner；当需要理解用户输入、明确目标、成功条件、影响面、当前链路或根因时使用，负责形成可决策证据，不负责主动发现新需求、冻结方案或修改实现。 --- # Development Task Understanding ## 目标 回答“用户要解决什么，系统实际怎样”。沿用户指出的入口取证，不凭文件名、局部调用或截图外推，也不从愿景、使用信号或市场发明需求；相邻机会只记为范围外。 ## 进入 标准开发任务轻量进入；明确要求调查、完整链路、复杂调试或根因，或局部证据不足时正式展开。 先冻结： - 用户或系统可观察问题； - 最小完整结果及其必要链路； - 任务类型、flow 分类依据、Design/文档建议；`bugfix` 另含复现层级与修后判定； - 期望行为和成功条件；用户任务给出“角色/起点 → 当前操作 → 可见结果”的现状链路，标出断点与未知，不用技术调用链替代，也不在理解阶段设计新交互； - 范围、非目标和约束； - 当前已知事实、假设和未知项；保存用户预期与共识来源，区分明确要求、已确认选择与 AI 推断，沉默不作确认； - 最近 owner、影响面和 L0-L4 风险。 - 技术决策状态：沿用、用户指定或待选型。新项目、技术栈替换及新增影响运行/部署的关键依赖须识别选型需求，记录目标环境、已有约束和未知项，交由设计解决；普通小改沿用现有栈并简述依据，不重选。 大型交付在依赖输入展开设计/实现前，将原始输入与约束整理到 `docs/logs/` 的本任务日志：短内容用“原始输入与约束”章节，多材料或需独立引用时拆日期前缀文件并从日志链接。其它需留痕或跨轮复用的任务沿用此落点，小改动不强制建日志。记录原话/原型/附件的位置与版本、用户要求及材料用途，区分必须遵循、参考、AI 推断与待定；不能把功能原型自动降为样式参考。读取相关原件后提炼，不能仅凭 AI 摘要；原件缺失标明未知，只暂停依赖它的决策。 涉及框架、协议或通用抽象时，先用真实场景证明零改动闭环；能成立就不改。只有可复现、无法由业务或 adapter 承接且阻断当前结果的共同缺口才升级；未来可能和“更通用”不算证据。 ## 调查顺序 1. 明确判断对象和会改变的下一步决策。 2. 读取对象本体，记录它实际产生、保存、转换或消费的事实。 3. 查调用方、被调用方、同类入口和规范事实源，记录现有能力与复用依据；未检索不算不存在。 4. 沿最近完整链路核对 `producer -> owner/state -> boundary -> consumer`。 5. 扫同 owner 或责任链的同类问题，但不无界扩张到全仓库。 6. 区分已确认事实、合理假设和仍需验证的未知项。 7. 判断路径是否显然，或存在会改变结果、owner、复杂度或验证的真实设计空间。 使用可复用知识时核对来源、版本/环境和有效性；设计决定不等于已经实现，历史成功不证明当前状态。维护事实或出现资料冲突时读取[事实知识合同](../../wiki/skills/process/project-knowledge-governance/references/fact-knowledge.md)。 ## Bug 复现门 `bugfix` 默认复现，必须选择 `reproduce` 或 `skip-reproduction`： - 根因、违约边界或修后判定任一不确定时，选择 `reproduce`，用命中同一违约点的最低成本复现。 - 仅当直接证据锁定根因和边界且有贴近风险的修后验证时，才选择 `skip-reproduction`，并记录依据和替代验证。 - 时间、环境和 Token 只影响复现层级，不降低证明门槛。 `reproduce` 保留失败入口、输入和指标供 Validation 复验；`skip-reproduction` 披露没有修前基线。复现不新增 phase。 按失效机制选最低充分层级：纯逻辑用单元、协作边界用集成、时序/环境/用户状态用真实链路。偶发或无法安全重现时先收集现场日志、追踪和状态；根因未锁定保持调查，不能把环境受限写成复现成功。紧急缓解不等于根因修复。 每次新增调查必须改变一个设计、实现或验证决策；已确认且未变化的长文件、日志和命令输出不得重读。 外部协议按端点和操作取证，不从单个成功端点外推。有状态机制分别核对触发、输入、替换、持久化/恢复、重试和测试；registry/catalog 投影对照 canonical 来源。 ## 条件方法 - 用户只给出方向、目标边界模糊或“做到什么程度”会改变交付时，读取[最小完整结果边界](references/minimum-complete-outcome.md)。 - 跨多 hop、runtime、transport、异步边界，或真实复现昂贵时，读取[链路切片](references/chain-slicing.md)。 - 用户要求系统根因、事故复盘或机制沉淀，且已有足够直接证据时，读取[根因分层](references/root-cause-layers.md)。 - 项目另有代码清理或专项调查合同且当前意图命中时，按项目入口读取；本阶段不复制专项方法。 普通任务理解不读取这些参考；一次只选择当前需要的一种方法。 ## 输出 - 需求、最小完整结果、必要链路、范围、非目标、成功条件和风险； - 任务类型、Design/设计文档建议与分叉依据；`bugfix` 另含复现决定、依据和修后判定； - 已查 producer、owner、boundary、consumer 范围； - 已确认事实、仍待验证假设和证据缺口； - 路径是否显然、是否需要正式设计； - 推荐下一阶段、继续调查或不改，以及原因。 本阶段不冻结实现方案、不编辑产物、不执行最终验证，也不枚举并加载所有可能的专项 skill。