用途
iterate-structure-outline 用于对一份已存在的结构大纲(structure outline)文档进行迭代修改。它明确限定:仅在用户明确按名称调用该技能时使用。
输入
- 结构大纲文档本身。
- 可选的任务票据文件路径,其中包含带反馈的评论。
- 如果只提供了目录或未提供目录,则检查提示中给出的任务产物目录:ls -La .humanlayer/tasks/<task slug>。资料特别说明不要使用 grep、glob 或 ls/ls -l,因为该目录可能是符号链接。
使用方式
- 若用户未给出任何指令或反馈,技能会先询问希望纳入哪些反馈或修改,例如阶段重组、范围变更(增删条目)、回答开放问题、补充上下文或需求,并等待反馈后再继续。
- 完整读取所有输入文档:结构大纲及全部先前产物(ticket.md 或 task.md、研究、设计讨论、PRD/TDD 如存在),使用 Read 工具且不设 limit/offset。
- 根据研究结论理解代码库当前状态,审阅所有设计决策与需遵循的模式。
- 若提到 .humanlayer/tasks/TASKNAME 路径,使用 ls -La 查看,并读取任务目录中的结构大纲、设计讨论、研究文档、票据及相关文件。
- 对用户输入不盲从:需要时派出研究任务核实信息,读取用户提到的具体文件或目录,确认事实后再继续。
- 如需深入调查,可派出子代理:codebase-locator 查找额外文件、codebase-analyzer 深入分析具体实现、codebase-pattern-finder 查找更多模式示例、web-search-researcher 研究外部最佳实践。若出现 humanlayer library researcher 工具,可用于回答依赖与库相关研究问题;若不存在则不提及。禁止在后台运行代理,只能前台运行。
- 处理反馈:阶段变更则重组阶段;范围变更则更新“What we're not doing”与各阶段内容;已回答的开放问题则从“Open Questions”中移除并纳入计划;保持相同的 YAML frontmatter 与格式。
- 需要时在相同 docPath 更新文档,调整阶段、阶段内文件变更与验证方式,移除已回答问题,并告知用户。
- 检查是否已处于 worktree:Bash(git rev-parse --git-dir);读取对应最终输出模板(structure_outline_final_answer_in_worktree.md 或 structure_outline_final_answer.md),严格按模板回复;已在 worktree 中时绝不建议再设置 worktree。
阶段设计原则
- 每个阶段理想上是纵向薄切片,尽可能触及所有或尽量多的层,以达成目标终态;避免“添加所有类型”“添加 API 端点”“实现 UI”这类横向阶段。
- 每个阶段应能基于类型检查、测试、构建步骤及仓库内其他验证独立验证;应理解代码库的测试与验证模式,不要对可用脚本或已有技能自动化完成的步骤建议手动测试。
- 横向拆分示例:构建 schema、构建 API、构建 UI、添加测试,会造成交接问题与半成品。纵向切片示例:用户能端到端创建最简单的版本;用户能端到端编辑一个字段;用户能看到第一个校验错误端到端。每项可按需包含 schema、API、UI 与测试。
- 不要设计成第 N 阶段必须等第 N+1 阶段完成才能验证。
文档优先级与格式
文档冲突时以最新文档为准:结构大纲 > TDD > PRD > 设计讨论 > 研究 > 票据。修改 .humanlayer/tasks/ 下文档时,hook 响应会自动提供云永久链接(形如 http(s)://{DOMAIN}/artifacts/{artifactId}),用于最终输出。在包含 markdown 代码块的 markdown 文件中,外层使用 4 个反引号,避免内层 3 反引号提前闭合。阶段变更应简洁清晰,优先突出签名变化而非整段代码,结构大纲相当于“c 头文件”,计划才包含函数定义。
验证设计
并非每个阶段都需要手动验证,不要仅为凑步骤而加手动验证。若某阶段无法手动检查,可能说明它太小或不够纵向。手动验证的目的是避免在 1000+ 行改动完成后才发现问题所在。自动化测试始终优于手动测试,应结合对代码库与测试模式的了解,明确区分手动测试与自动化测试。
限制
- 仅在用户明确按名称调用时使用。
- 仅用于迭代已有结构大纲,不负责从零创建。
- 资料未说明该技能的收费、平台或效果信息。
- 输出需严格遵循指定模板,不添加摘要或其他信息。