---
name: cook-it-through
description: "当用户要在一个目标项目里推进实质性工程任务、需要先确定执行深度和验证强度时使用；也用于该项目 .scratch 本地 ticket 队列的规划、领取、交付与集成。触发说法包括「按流程做这个」「这个需求怎么落地」「继续这个 ticket」「集成这个 feature」「.scratch 里还有什么可做」「谁在跑这个队列」。不用于纯 TSL 语法/API 查询、只写 commit message、诊断远端 Gitea CI。"
---

# Cook It Through

## 先确定项目与边界

- `<COOK_IT_THROUGH_ROOT>` 是本 skill 的绝对目录，只用于定位随 skill 安装的执行引擎；
  它不是目标项目、状态目录或工作区。
- `<PROJECT_ROOT>` 只能来自用户或任务明确指定的 checkout，并由
  `git rev-parse --show-toplevel` 验证。无法确定时保留占位符并暂停；不得把 skill source、
  snapshot 或偶然 cwd 当项目根。
- 先读取目标项目的 `AGENT_RULES.md`、`AGENT_RULES.local.md`、`.agents/index.md`；不存在则跳过。
  入口 1 只保留这些最小边界，不加载按需文件。
- 主循环只使用共享 local Markdown tracker、同一文件系统和 Git common directory；
  不得接入远程 tracker、独立 clone 或跨机器状态。
- 只从 `<COOK_IT_THROUGH_ROOT>/scripts/main_loop.py` 调用机器入口。构造任何命令前先运行
  `python <COOK_IT_THROUGH_ROOT>/scripts/main_loop.py <command> --help`；帮助输出独占参数、
  状态字段与 evidence schema 的权威。

## 任务路由

按成本从低到高选择第一个满足条件的入口；升级时把已有改动当作事实输入，不视为已批准方案。
路由前阅读 `AGENT_RULES.local.md` 声明的高爆炸半径路径：清单内文件即使改动看似机械，
也不得走入口 1。未声明时，触及构建、CI 或分发配置的改动最低入口 2。

### 入口 1：直接执行

只读分析、定位、审查和不改变可观察行为的机械修改；不生成 spec/tickets，不建 branch。
入口 1 不加载按需文件。

**升级条件**：出现可观察行为变化，或路径地板要求更高入口时转入口 2。

### 入口 2：单切片改动

单模块/既有接口、既有测试 seam、无新公开接口、配置、数据格式、依赖、迁移、兼容或并发，
且一个 session 可完成；不属于入口 3 时适用。详情读
[`workflows/single-session.md`](workflows/single-session.md)。

**升级条件**：需要新 seam、越过边界或出现未确认取舍时转入口 4。

### 入口 3：已明确预期行为的 bug

预期行为和失败反馈已明确；与入口 2 一起读
[`workflows/single-session.md`](workflows/single-session.md)，由该文件决定诊断循环和升级。

### 入口 4：新 feature 或设计变更

产品/架构决策、新 seam/公开接口/配置/数据格式、跨模块、迁移/兼容、跨 session/并发，
或单 session 无法完成的工作。边界不清时先按入口 2 起步；确认后读
[`workflows/feature-planning.md`](workflows/feature-planning.md)。

enqueue 完成、恢复已入队工作或调用 status/claim 后读
[`workflows/ticket-execution.md`](workflows/ticket-execution.md)；stdout 出现
`INTEGRATION_REQUIRED=<feature>@integrated` 后读
[`workflows/feature-integration.md`](workflows/feature-integration.md)。到阶段边界或上下文有压力时读
[`rules/session-boundary.md`](rules/session-boundary.md)。

## 常驻红线

- 禁止手工修改 ticket `Status`、`main-loop:ticket-state`、queue block 或 feature state。
- 禁止伪造或复用证据 artifact；integration dependency 不可见时禁止继续。
- 禁止 stash、reset 或覆盖其他 session 改动；禁止绕过 integration frontier 或运行
  `git add .scratch`。
- 只允许 local Markdown tracker；禁止把远程 tracker、独立 clone 或跨机器状态接入主循环。

## 恢复与完成

`clear`、`compact`、`handoff`、上下文压缩或新 session 恢复时，必须重新加载本文件与当前路由文件；
不得只依据 `status` 输出继续。保持活动 claim 的 heartbeat；结束前做 fresh verification，
并报告完成、未完成、证据与风险。