task-triage

Files (2)

• SKILL.md
• structured-handoff.md · references/

SKILL.md (first lines)

# Task Triage Skill

本 Skill只核对任务事实、作出正交决策并交接专业动作；不复制Worktree、OpenSpec或验证手册，也不建立确定性路由器。

## 1. 核对任务事实

只读任务相关范围，不做全量审计。确认：

- 用户希望外部行为或长期事实如何变化；
- 直接相关实现和约束，以及决定当前动作所需的权威来源；
- 登记使用已确认的 Workspace/Project/Service scope；实际需要 Git 操作时再核对相关 repository set，不按目录层级猜测边界；
- 任务范围涉及的已登记代码库（Repository）有来源声明但缺少真实代码时（`repositories/manifest.yml` 有登记、声明目录不存在或诊断报告 `code_missing`），先提醒用户是否按声明来源与集成分支准备该代码库，再继续依赖它的写入；任务范围未涉及的缺失代码库只如实报告，不代为准备。
- 写入授权、不可逆影响和仍需用户决定的语义冲突。

首次修改前，按改动影响核对直接相关实现和约束。小改动不要求遍历规范、知识、测试与登记信息；涉及行为、职责或权威来源变化时，再按需读取相关规范、当前认知、活跃变更、调用方、测试和登记信息，形成有界来源图（Authority Source Map）。来源图仅用于当前工作上下文，不写入任务记录或其他产品状态；只有范围或相关事实变化时才增量刷新。

authority 冲突、授权不明、实际 Git 操作所需的 repository set 不明、不可逆行为缺少决定，或是否进入实现仍未知时，停止对应写入，只询问会改变长期语义、责任边界或授权的最少问题。

### UI Prototype 选择

新页面、主要布局或交互存在实质设计选择，且用户尚未表达原型偏好时，询问是否需要先生成界面原型（UI Prototype）。已有明确偏好继续适用；已明确设计的局部文案、样式或交互修复直接推进，不机械询问。用户主动要求原型时，按下方明确选择边界处理。

只有用户在当前任务中明确确认需要，才在方案已有足够上下文、正式前端实现开始前加载 selected `ui-prototype` Skill。用户拒绝、未确认或直接要求继续时不调用 Skill，正常推进后续流程；不得创建占位文件、waiver、Result、Receipt 或 blocker。UI Prototype 不替代 OpenSpec Change、Planning Review 或正式实现。一旦当前 Task 已生成原型，除非用户明确要求忽略，后续 Agent 必须在正式前端编辑前读取全部相关原型并按其信息架构、布局和交互开发。

用户要求原型且已有正式任务时，接续 `ui-prototype` 的“成果保存与接续”，生成后立即归入任务供评审，不等待实施决定；没有关联变更也通过该技能约定的任务目录展示，不为展示强造变更。后续新建任务时，同样接续此前临时原型。用户决定实施且此前讨论已有未被明确忽略的原型时，在正式前端编辑前由同一技能核对确认版、复用或归入适用位置并验证任务展示。此动作承接已有成果，不重新询问是否生成，也不复制迁移或清理流程；归入展示不等于批准实施，是否创建变更仍按下方语义判断。

## 2. 两轴决策

### 语义治理

| 选择 | 判定 | 动作 |
|---|---|---|
| `code-only` | canonical spec 已覆盖目标，且修改不改变可观察契约 | 不创建 Change |
| `spec-maintenance` | specs、实现、registries 或已确认决定已证明当前事实，只需文档追上事实 | 不补造 Change；current knowledge 使用 `maintain` |
| `change-flow` | 改变 SHALL/MUST、API、状态流、权限、业务规则、数据语义、兼容性或其他可观察承诺 | 一个独立业务目标一个 Change |
| `blocked` | authority、业务语义或授权无法确认 | 报告冲突和最少决策问题 |

工程细节默认不进入 OpenSpec；但默认值、存储或内部机制一旦改变外部行为、数据含义、兼容性、安全边界或业务承诺，仍走 `change-flow`。不得用 `spec-maintenance` 绕过新需求评审，也不得用 `code-only` 掩盖规范缺失或事实不明。

若任务改变依赖、构建或测试入口，直接核对当前项目与服务的真实入口差异：测试与 `verification.yml` 由 `project-testing` 一并维护，准备声明由 `buildr` 的准备声明指引维护。已有授权内的普通维护连续完成，只有业务取舍、范围扩大或外部副作用超出现有授权时请求用户决定；不另设声明接入中转。

开发开始时判断预计知识影响，最终新增、修改或删除后复核。已有知识成果受影响时，主动说明受影响成果与建议校准范围；知识维护尚未授权时等待该组授权，已有授权不重复询问。在当前授权内采用 `current-knowledge-maintenance` 维护相关图示、地图、术语和解释；按需调用专业制作方法。普通开发没有规范变化不因此建立 OpenSpec 变更，无影响内容保留，范围外缺口单独提出建议。

开发开始时若目标可能新增、替换或停用参与项目（Project）的服务（Service），采用当前可用的 `project-composition-maintenance` 技能（Skill）核对组成，并在修改结束后按最终事实维护本次受影响的关联。已授权开发中的必要组成校准纳入同次工作；只读请求不写登记。无组成影响时不全量梳理，不新增强制检查或结果门禁。

### 执行形态

- `implementation`：修改代码、运行构建/测试，或需要长期开发上下文。
- `metadata-only`：仅维护 OpenSpec artifacts、Rules、Skills、文档或模板，不进入代码、构建或测试。
- `unknown`：信息不足；先澄清，不提前写 Change artifacts 或当前事实。

该轴独立于语义治理，也不改变下方默认隔离策略。Formal Task Record本身不是编辑、构建或有界测试的通用工作许可。需要依赖、代码生成或运行入口时使用Project/Service的真实wrapper、包管理器和构建工具；工作位置不代表Formal Verification或cleanup事实。

### 材料深度与三类检查分别判断

规范变化不决定材料深度，也不决定专业检查。每个新正式 `active` 任务先登记、确认隔离位置，再由 `task-manager` 在任务记录（Task Record）的 `brief` 字段保存唯一任务说明（Task Brief）；简单任务允许真实短正文，复杂任务按需要补充方案、实施与交付材料，不为凑齐节点生成长模板、占位报告或变更（Change）。独立正文只由任务记录保存，不创建新的 `brief` 文件关联；具体变化使用既有 proposal、design、specs 和 tasks，不新增额外说明文件。顶部普通链接不替代记录正文。

分别判断并给出最小依据：

- 方案审查（Planning Review）：任务存在提案（proposal）、设计（design）或等价方案选择材料时即需要核对完整性、合理性、一致性与风险；方案可来自任务文档、清单、设计或专业产物，不要求 OpenSpec。
- 实现审查（Implementation Review）：开发实现完成后核对实际成果是否兑现目标与适用方案；没有方案审查也可需要实现审查。
- 任务验证（Task Verification）：目标、影响范围、风险和完成依据需要哪些真实检查与证明；实际执行过检查即登记验证报告，审查不代替验证。

不机械按 `change-flow` 默认两次审查，不因 `code-only`、`spec-maintenance`、无 Change 或无方案跳过需要的检查。需要但未完成、材料缺失、未执行、确实不适用、失败与通过如实区分；不适用或确有需要的事实理由必须通过工作摘要（Work Context）的 `checks` 结论显式留痕（`buildr task work-context record --check <名称> --check-status <needed|not-applicable> --check-reason <理由>`），不只留在对话或临时文本中，也不新增适用性状态库、审批或统一门禁。专业记录缺失不自动阻止其他动作，但目标所需检查或风险尚未解决不得报整体完成。

### 默认隔离

首次持久文件修改前，核对目标及最近现存父目录的真实路径、适用源声明和实际 Git 归属。没有本目录 `.git`、文件未跟踪或被忽略、目标尚不存在，都不能证明非 Git；父仓库、独立子仓库与明确登记的来源都须按实际对象判断。目标或祖先的悬空链接、新链接及身份变化不能自动取得外部范围；已核验的合法工作空间（Workspace）入口别名可以按同一实际根归一。Git 观察失败、仓库损坏或已登记仓库缺失属于身份未明，不能当作非 Git；缺少 Git 工具本身不形成所有资料任务必须安装 Git 的门禁，但没有其他可核验来源时只停止该写入。

按真实对象选择安全工作位置：

- **Git 文件：** 除非用户明确要求在主开发分支修改，否则创建或复用当前任务的独立工作树（Worktree）。代码、文档、配置、规则（Rule）、技能（Skill）、模板和 OpenSpec 材料共同遵守；小改动、纯规划、主目录干净或已授权实现均不构成例外。只读检查、合法任务记录和临时输出无需为此创建工作树（Worktree）；专业应用拥有的本机状态继续由其产品动作维护。
- **已确认的非 Git 资料：** 在已授权、已核对的实际位置使用所属专业工具维护，代码库集合（Repository Set）为 `none`，工作树（Worktree）不适用；不为了开始工作初始化仓库、创建分支或补造工作树证据。修改前核对目标身份、当前内容及已观察版本或不存在状态；专业能力支持版本条件时提交其已观察值。普通文件工具写前重读，使用可核对、保留其他内容的最小补丁，覆盖或替换前确认原内容可保全。目标被替换、内容改变或新出现时保留当前内容和修改意图，停止旧观察的覆盖并重新判断；不能自动重放或恢复而覆盖他人修改。写后从真实成果回读正文与来源，不以记录成功替代验收。重读和普通补丁不承诺对任意外部编辑器的原子并发保护。
- **身份未明：** 代码库集合（Repository Set）为 `unresolved`，只停止依赖该身份的写入，保留现场并核对具体差异；不猜测目录、不借非 Git 分支绕过 Git 归属或已选提供者（Provider）。

同一目标从原型（Prototype）进入正式开发时，先接续原型技能（Skill）交接的确认版及源码来源，核对已有稳定隔离标识、工作树（Worktree）路径和分支（Branch）。已有源码位置时复用其实际根，保留未提交成果，不因阶段转换另建位置或实施分支。尚无匹配正式任务时，由 `task-manager` 核验同一目标及标识未被其他任务占用后沿用隔离标识登记；已有匹配任务则继续原任务，不补造原型期间的任务历史。只有临时 HTML 而没有源码位置时才按正常策略创建开发位置。身份冲突保留现场，不通过新建副本、移动或改名绕过核验；页面保存或归档目录变化不改变源码隔离身份。

实际需要 Git 位置时，创建、检查与清理遵循 `buildr.git-worktree-provider/v1` 契约（Contract）及当前有效能力绑定（Capability Binding），由已选提供者（Provider）承接。宿主原生工具可用不代表契约兼容，不据此替换实现或默认目录。

- 已有当前任务的 Git 独立位置：通过 `worktree inspect` 核对任务、真实仓库、分支与登记身份，复用返回的实际根并保留本任务未提交成果；不因新轮次或阶段转换重复创建，也不借用其他任务的位置。其他入口创建的位置缺少历史证据时，由接手智能体（Agent）核对任务归属，并使用已选提供者的显式当前对象输入重新核验；身份冲突或安全无法证明时保留现场，不另建同任务副本、迁移或补造历史。
- 尚无当前任务 Git 位置：向已绑定提供者交接明确的任务标识、工作空间、真实仓库集合、任务分支与起点提交，使用 `worktree create` 返回的实际根继续。主目录的无关未提交改动不阻止创建；不为创建而提交、暂存或清空他人内容。新位置只包含起点提交；依赖未提交成果时先核对其归属和依赖关系。
- 用户明确要求在主开发分支修改：核对实际分支、文件归属与覆盖风险后继续；同一对象、范围与副作用的授权持续有效，不重复确认。
- 实际 Git 动作的提供者不可用、已登记仓库缺失或位置身份冲突：只停止依赖该 Git 位置的持久文件写入，继续其他独立安全的已授权工作；不自动回退主开发分支或初始化仓库。

混合范围逐对象判断，Git 对象受阻不阻断已确认、独立安全的非 Git 资料工作。隔离保护并发任务的文件现场，不承诺合并无冲突；交付时仍核对当前成果与适用目标分支。

## 3. 条件化交接

已有或刚创建的active Formal Task先`task inspect`核对目标、scope与current record identity。按默认隔离策略取得真实执行位置后再写文件；不补造位置、Plan或Receipt。

按用户目标和当前事实渐进装配专业上下文：执行当前动作前只读取相应Skill、binding、contract与直接authority，Review、Verification、OpenSpec、Parent管理和任务收尾只在真实命中时加载。不得为发现未来阶段运行Doctor full或预读完整专业Result；provider不ready时只阻塞或降级对应分支，保留其他已确认结论。

用户已经授权实现时，在已按默认隔离策略确认的位置和文件ownership、副作用边界内立即推进；OpenSpec、Review、Verification与Finish直接消费实际对象和具体资源owner，不要求统一ready。

需要登记待办、创建任务、选择独立位置、维护当前知识或协调父子任务时，读取[具体交接](references/structured-handoff.md)。

### 任务登记与代码更新

已初始化的工作空间（Workspace）中，用户授权开始或继续持久交付时，默认在首次交付文件写入前读取已绑定 `buildr.task-record/v4` 的契约（Contract）与提供者（Provider），交给 `task-manager` 核对匹配记录并接续或创建 `active` 任务。`code-only`、`spec-maintenance` 和 `metadata-only` 不因没有规范变更（Change）或改动小而跳过登记。纯只读咨询、尚未授权的方案讨论和已有任务自身的记录维护不另建任务；用户明确不登记时遵从其范围，不在收尾时补造历史。

后续阶段沿用同一任务标识，出现可接续的进展、决定、暂停或结果时，交给 `task-manager` 更新工作摘要（Work Context）或真实结果；不重复创建，不将记录动作扩展为全局就绪门禁。登记失败如实说明缺口，继续独立只读检查或有界测试，依赖该记录的写入仍按对应能力边界处理。

创建或激活任务前，确认目标工作空间（Workspace）、用户目标、项目（Project）或服务（Service）范围及写入授权；已有匹配任务先读取，不重复创建。激活使用刚读取的记录版本，冲突后重读并重新判断。

登记不要求 Git 更新、干净工作目录、集成分支、上游引用或全局诊断通过；不为登记执行 fetch、rebase 或工作空间同步。无 Git、离线、未提交内容或 Git 操作进行中均不阻止合法登记；保持文件、分支和引用不变。只因记录目标、范围、授权、版本或记录提供者（Provider）无法确认而停止对应记录写入。登记成功不证明代码、环境、验证或交付已就绪。

仅当用户目标确实要求更新代码时，才读取 optional `buildr.git-operations/v1` 的绑定（Binding）、契约（Contract）和已选提供者（Provider），明确仓库、引用、动作与授权后执行；失败不撤销已成立的登记。后续文件修改遵循上方隔离策略，工作空间同步遵循产品入口边界，不将这些条件反向加到任务登记上。

选择 `change-flow` 时，先确保正式 Task Record，再完成执行位置判断并使用适用的 `openspec-*` Skill。首次采用、状态实质变化、暂停、完成或用户询问时，从 CLI 刷新并报告 change id、resolved path、action、status、progress 和 next action/blocker；未创建时只写 `planned`，不猜测路径或进度。Buildr 自有 artifacts 和用户说明正文使用中文；命令、路径、标识符、协议字段与 OpenSpec 格式关键字可保留英文。方案审查、实现审查与验证按上述目标、真实方案和风险分别判断（见 `task-review` 与 `project-verification`），不继承此路径选择。

实现型任务按共享实现区域、验证入口或失败影响面分组。工作位置沿用已核对的默认隔离结果，实际Git与owned scope变化时重新判断。Agent直接依据目标、OpenSpec、Git、代码、文件和专业结果推进，不创建研发聚合事实或planning snapshot。需要设计测试框架、划分测试边界、编排场景或为实现开发测试时使用`project-testing`。开发中由 `project-verification` 依据用户请求、目标与实际调用面选齐相关四类检查并直接执行；不要求用户先提供比较基线或创建测试计划。推送前按具体项目政策核对完整检查，Buildr 产品使用四服务全部静态检查（Static Check）与单元测试（Unit Test）。开发完成后通过 selected `buildr.task-verification/v4` provider 保存已有正式任务的真实报告；独立检查无任务时直接交付证据。triage不把验证报告变成Task完成门禁。

## 输出

面向用户说明分流结论、实际影响与下一步；需要结构化交接时，读取[交接字段](references/structured-handoff.md)。

本轮已授权交付实际完成、适用检查已通过且没有后续已授权动作时，答复末尾用一句话说明可通过"收尾"完成提交、集成与资源善后；用户继续提出新要求时直接接续，不把引导变成重复追问或完成门禁。

## Guardrails

From BuildrAI/Buildr, MIT.

More from BuildrAI/Buildr