peiiii / development-task-understanding

Development Task Understanding

目标

回答“用户要解决什么，系统实际怎样”。沿用户指出的入口取证，不凭文件名、局部调用或截图外推，也不从愿景、使用信号或市场发明需求；相邻机会只记为范围外。

进入

标准开发任务轻量进入；明确要求调查、完整链路、复杂调试或根因，或局部证据不足时正式展开。

先冻结：

• 用户或系统可观察问题；
• 最小完整结果及其必要链路；
• 任务类型、flow 分类依据、Design/文档建议；bugfix 另含复现层级与修后判定；
• 期望行为和成功条件；用户任务给出“角色/起点 → 当前操作 → 可见结果”的现状链路，标出断点与未知，不用技术调用链替代，也不在理解阶段设计新交互；
• 范围、非目标和约束；
• 当前已知事实、假设和未知项；保存用户预期与共识来源，区分明确要求、已确认选择与 AI 推断，沉默不作确认；
• 最近 owner、影响面和 L0-L4 风险。
• 技术决策状态：沿用、用户指定或待选型。新项目、技术栈替换及新增影响运行/部署的关键依赖须识别选型需求，记录目标环境、已有约束和未知项，交由设计解决；普通小改沿用现有栈并简述依据，不重选。

大型交付在依赖输入展开设计/实现前，将原始输入与约束整理到 docs/logs/ 的本任务日志：短内容用“原始输入与约束”章节，多材料或需独立引用时拆日期前缀文件并从日志链接。其它需留痕或跨轮复用的任务沿用此落点，小改动不强制建日志。记录原话/原型/附件的位置与版本、用户要求及材料用途，区分必须遵循、参考、AI 推断与待定；不能把功能原型自动降为样式参考。读取相关原件后提炼，不能仅凭 AI 摘要；原件缺失标明未知，只暂停依赖它的决策。

<!-- model-capability-patch: gap=现有能力可闭环时仍升级框架; review-on=model-change; remove-when=方案任务能稳定先证明零改动路径 -->
涉及框架、协议或通用抽象时，先用真实场景证明零改动闭环；能成立就不改。只有可复现、无法由业务或 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。