【用途】 该技能用于创建一份分阶段的实现计划(structure outline),依据已有的研究结果与设计决策,把一项任务拆成若干可独立测试的阶段,供后续实现使用。仅在用户显式按名称调用该技能时才应使用。
【主要能力】
- 读取任务工件目录:若只提供目录或未提供目录,会在 .humanlayer/tasks/<task slug> 下查找工件目录(使用 ls -La,不使用 grep/glob/ls -l,因目录可能是符号链接);若仍无法确定,会询问用户希望基于哪些工件创建大纲。
- 完整阅读输入文档:不限 limit/offset 读取研究文档,理解代码库现状,审阅全部设计决策与需遵循的模式;不读取研究问题文档(研究问题只是研究阶段的输入)。
- 检查相关任务内容:若提到 .humanlayer/tasks/TASKNAME 路径,则列出该目录并读取除研究问题文档外的所有文件,以及任务文件中提及的相关文件。
- 按需启动子代理补充调研:codebase-locator(查找额外文件)、codebase-analyzer(深入特定实现)、codebase-pattern-finder(查找更多模式示例)、web-search-researcher(调研外部最佳实践);只在前台运行,不后台运行。
- 生成可视化分阶段计划:先读取 {SKILLBASE}/references/show-me.md,然后为每个阶段选用最少必要视图,而非罗列文件与改动;按最易理解的顺序叙述每个阶段。
- 使用树形结构(├──、└──、│)展示文件变更,diff 块中用 + 表示新增/变更行、- 表示删除行、空格表示未变上下文;对关键数据结构、SQL 表或 API 契约使用聚焦视图。
- 以垂直切片拆分阶段:每阶段尽量贯穿多个层/服务/模块,可独立验证(类型检查、测试、构建等);避免“先做 schema、再做 API、再做 UI、最后加测试”这类水平拆分;不要设计成阶段 N 必须等阶段 N+1 完成才能验证。
- 每个阶段包含:构建内容概述、紧凑的变更大纲(文件树、关键结构、测试等)、验证方式。
- 创建实现概览:顶部以 - [ ] Phase N: [Title] 格式列出全部阶段标题,便于实施时勾选。
- 输出文档:读取 {SKILLBASE}/references/structure_outline_template.md,将大纲写入 .humanlayer/tasks/ENG-XXXX-description/NN-structure-outline-DESCRIPTION.md;NN 为按已有最高前缀递增的补零序号,DESCRIPTION 为 2-4 个 kebab-case 单词。有工单时目录如 .humanlayer/tasks/ENG-1478-parent-child-tracking/04-structure-outline-parent-child-tracking.md,无工单时如 .humanlayer/tasks/improve-error-handling/04-structure-outline-error-handling.md。
- 判断是否已在 worktree 中(git rev-parse --git-dir),并读取对应的最终输出模板(worktree 内用 structure_outline_final_answer_in_worktree.md,否则用 structure_outline_final_answer.md);已在 worktree 中时不得建议再建 worktree。
- 按模板精确回复,不附加摘要;如可用则附云端永久链接(.humanlayer/tasks/ 下写入/编辑后由 hook 自动提供)。
【使用方式】
- 用户显式按名称调用该技能并提供目录或任务信息。
- 技能定位工件目录,完整阅读研究文档及相关任务文件。
- 必要时派前台子代理补充调研。
- 读取视觉指南,按垂直切片设计阶段并撰写大纲。
- 读取模板,按序号命名写入任务目录,输出时附永久链接。
- 迭代:用户给出反馈时,技能不直接采纳,而是重新调研验证(启动研究任务、阅读指定文件),确认事实后再更新文档;所有用户反馈都理解为“更新文档”而非“开始实现”。
【文档格式要求】
- 以一个人写给另一个人的口吻撰写,视图之间加简短说明,解释下一部分为何重要、与阶段如何关联。
- 文件归属重要时用高层文件变更树,关键结构重要时用聚焦视图;对已有结构的局部改动用 diff 块,新结构或整体形状用语言特定块或文本块。
- 树保持足够小便于浏览,相关文件归入共享目录,省略无上下文价值的未变路径。
- 每个阶段的验证分为自动化验证(可运行命令:类型检查、测试、lint)与手动验证(需人工判断的步骤);并非每个阶段都需要手动验证,若某阶段无法手动检查,可能划分过小或不够垂直。优先自动化测试。
- 含代码块的 Markdown 示例在展示 Markdown 时,外层用 4 个反引号包围,避免内层 3 个反引号提前闭合。
- 阶段改动应简洁清晰,优先突出签名变化而非整段代码。
【适用场景】 在完成研究与设计讨论后、正式编码实现前,需要一份分阶段、可验证、贯穿多层的实现计划时使用。
【限制与注意事项】
- 仅在用户显式按名称调用时使用。
- 文档冲突时以最新文档为准:结构大纲 > 设计讨论 > 研究 > 工单。
- 不读取研究问题文档;不在后台运行子代理;已在 worktree 中时不得建议创建 worktree。
- 回复严格遵循模板,不附加总结或其他信息。
- 关于具体模板内容、云端链接域名等细节,资料未提供完整定义。