sitrep

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sitrep

A situation report for the current run. Sitrep reads the environment (session history, git, GitHub,

TASKS.md

) and reports what happened, what is moving, what is stuck, and what the user owes or needs to decide. It is read-only: sitrep never mutates the repo or GitHub, and never continues unfinished work as a side effect — reporting is the whole job.

当前运行的 situation report。Sitrep 会读取环境（会话历史、git、GitHub、

TASKS.md

），并报告发生了什么、哪些事项正在推进、哪些事项受阻，以及用户需要负责或决定的事项。它是只读的：sitrep 绝不会修改 repo 或 GitHub，也绝不会顺带继续未完成的工作——报告本身就是全部任务。

Operating contract

操作约定

Shared by every DecisionNerd/dev-skills skill. Canonical copy:

handbook/concepts/14-operating-contract.md

Define done first. Before using tools, write the finish line in one or two lines: acceptance criteria (existing issue AC, BDD scenarios, tests, or contract; otherwise propose them and where they should live) and the evidence that will prove them. Re-check it before reporting done. Never report done on unverified work.
Requested scope sets the finish line. A question ("is it ready?", "why is it broken?", "what next?") ends with the answer and a
```
Next:
```
line naming the exact next invoke. An outcome request ("fix", "finish", "land", "#42") continues through the chain (diagnose → fix → test → check-readiness → merge-it) until the outcome or a real blocker. Do not end a turn with "Do you want me to…?" for in-scope, in-repo work.
Stop only for real blockers. Stop and ask only when you cannot continue without the user, or before: deleting data or unmerged work, force-push or history rewrite, changing anything outside this repository (GitHub objects, deployments, live data, production or paid resources, external services), or leaving the requested scope, unless the user's request already named that exact action. Keep the harness's permission prompts for risky commands. Otherwise keep going and put status notes in the same message as the next action.
Ask well, once. For a genuine question use the harness's structured question tool when it has one (Claude Code:
```
AskUserQuestion
```
; Codex:
```
request_user_input
```
when the current mode supports it; T3 Code: the
```
question
```
tool) with concrete options; otherwise plain text with numbered options. Treat the answer as settled; do not re-open earlier verdicts, plans, or answers unless asked.
Fan out when work is parallel. Use subagents for independent reads (repo survey, evidence gathering, per-option research, per-area audits) and independent verification (a reviewer that did not write the change). Writes stay single-owner per path set and sequential. Brief every child with goal, done-when, constraints, must-not, and return shape; verify each result before consolidating. Use Claude Code's
```
Workflow
```
tool only when orchestrating many subagents truly needs it; it is expensive. T3 Code: its delegated subagents — with optional worktree isolation for independent verification — cover this without the
```
Workflow
```
tool.
Pick the model tier per child; defer to routing config. If the harness or user config already routes subagents, follow it and do not pass a model. Otherwise pick a tier per child: mechanical search or inventory → fast/cheap; implementation and evidence gathering → mid; planning, review, adversarial verification → top. Tier names differ per harness (Claude Code:
```
haiku
```
/
```
sonnet
```
/
```
opus
```
or
```
fable
```
; T3 Code: inherit by default or pick from its live provider/model catalog). Set the choice with the harness's spawn
```
model
```
param or agent frontmatter
```
model:
```
(per-harness details:
```
skills/agents/references/sub.md
```
). Where the harness cannot choose, children inherit or the harness picks; say which in the status note.
Keep a checklist on long runs. For more than about five steps or work that crosses skills, keep
```
TASKS.md
```
at the repo root and tick items as they finish. Do not commit it unless the repo already tracks one.
Close every run with three headings.
```
Blocked on me
```
(the one genuine question or blocker, else "none");
```
Changed
```
(files, commits, GitHub objects, deploys, else "nothing");
```
Found
```
(evidence, verdict, and
```
Next: <exact invoke>
```
).

Sitrep exception to the outcome rule: sitrep only reports state; it never continues an outcome chain. When outcome work ("fix", "land", "#42") is already running, report it as

Continuing

with its next observable checkpoint — do not suggest re-invoking the active skill or imply the user must restart it. Reserve

Next: <invoke>

for actions not already underway, and write

Next: none

when the work is complete.

所有 DecisionNerd/dev-skills skill 共用此约定。权威副本：

handbook/concepts/14-operating-contract.md

。

先定义完成标准。 在使用工具前，用一两行写明终点：验收标准（现有 issue AC、BDD 场景、测试或 contract；如果没有，则提出建议及其应存放的位置），以及将用于证明完成情况的证据。报告完成前再次核对。绝不在未经验证的情况下报告已完成。
请求范围决定完成边界。 提问（“is it ready?”、“why is it broken?”、“what next?”）应以答案和一行
```
Next:
```
结束，其中注明下一次调用的准确命令。结果类请求（“fix”、“finish”、“land”、“#42”）应沿链路持续推进（diagnose → fix → test → check-readiness → merge-it），直至达到目标或遇到真正的阻塞。对于范围内且在 repo 内的工作，不要以“Do you want me to…?”结束回合。
只在真正的阻塞处停止。 仅当没有用户就无法继续，或在以下操作之前停止并询问：删除数据或未合并的工作、force-push 或重写历史、修改此 repo 之外的任何内容（GitHub 对象、部署、实时数据、生产或付费资源、外部服务），或偏离请求范围；但用户的请求已明确指定该准确操作时除外。对于高风险命令，保留 harness 的权限提示。否则继续推进，并在同一消息中附上状态说明和下一步操作。
只提问一次，且问得恰当。 如果确有真正的问题且 harness 提供结构化提问工具（Claude Code：
```
AskUserQuestion
```
；Codex：当前模式支持时使用
```
request_user_input
```
；T3 Code：
```
question
```
tool），应使用该工具并提供具体选项；否则使用带编号选项的纯文本。将答复视为已确定；除非用户提出要求，不要重新讨论之前的结论、计划或答复。
并行工作时进行分派。 对独立的读取任务（repo 调查、证据收集、按选项研究、按领域审计）以及独立验证（由未编写变更的 reviewer 执行）使用 subagents。每个路径集的写入操作保持单一负责人并顺序执行。向每个 child 简述目标、完成条件、约束、禁止事项和返回格式；汇总前逐一验证结果。仅在确实需要编排大量 subagents 时才使用 Claude Code 的
```
Workflow
```
tool；它成本较高。T3 Code：其 delegated subagents 可覆盖这些场景，并可选用 worktree isolation 进行独立验证，无需
```
Workflow
```
tool。
按 child 选择 model tier；遵循路由配置。 如果 harness 或用户 config 已路由 subagents，则遵循该配置且不要传入 model。否则为每个 child 选择 tier：机械式搜索或 inventory → fast/cheap；实现和证据收集 → mid；规划、review、对抗性验证 → top。各 harness 的 tier 名称不同（Claude Code：
```
haiku
```
/
```
sonnet
```
/
```
opus
```
或
```
fable
```
；T3 Code：默认继承，或从其实时 provider/model catalog 中选择）。通过 harness 的 spawn
```
model
```
param 或 agent frontmatter
```
model:
```
设置选择（按 harness 的详细信息：
```
skills/agents/references/sub.md
```
）。当 harness 无法选择时，由 child 继承或由 harness 选择；在状态说明中注明。
长时间运行要保留 checklist。 对于超过约五个步骤或跨多个 skill 的工作，在 repo 根目录维护
```
TASKS.md
```
，并在完成各项时勾选。除非 repo 已经跟踪该文件，否则不要提交它。
每次运行都以三个标题收尾。
```
Blocked on me
```
（唯一的真正问题或阻塞；否则为“none”）；
```
Changed
```
（文件、commit、GitHub 对象、部署；否则为“nothing”）；
```
Found
```
（证据、结论和
```
Next: <exact invoke>
```
）。

Sitrep 对结果规则的例外： sitrep 只报告状态；绝不继续执行结果链路。当结果类工作（“fix”、“land”、“#42”）已在运行时，将其报告为

Continuing

，并附上下一个可观察检查点——不要建议重新调用当前活跃的 skill，也不要暗示用户必须重新启动它。仅为尚未开始的操作保留

Next: <invoke>

；工作完成时写

Next: none

。

Window

时间范围

Default window: since the previous sitrep in this conversation, or since the session start if there is no previous sitrep — whichever is later. The conversation itself is the watermark; do not write watermark files.

Arguments:

Argument	Behaviour
(none)	Default window (above).
`full`	Whole session, ignoring any previous sitrep.
`since <point>`	Since a named point: a commit sha, a time ("since 2pm"), an event ("since the last test run"), or "since the merge".
`<scope>`	Restrict to one area: an issue/PR ( `#42` ), a path ( `src/api` ), or a named workstream ("the auth migration"). Scope filters the report; it does not change the window unless combined with `since` .

默认时间范围：自本次对话中上一次 sitrep 以来；如果没有上一次 sitrep，则自会话开始以来，以较晚者为准。 对话本身就是 watermark；不要写 watermark 文件。

参数：

参数	行为
(none)	默认时间范围（如上）。
`full`	整个会话，忽略任何上一次 sitrep。
`since <point>`	自某个命名时间点以来：commit sha、时间（“since 2pm”）、事件（“since the last test run”）或“since the merge”。
`<scope>`	限制到一个领域：issue/PR（ `#42` ）、path（ `src/api` ）或命名 workstream（“the auth migration”）。scope 仅过滤报告；除非与 `since` 组合使用，否则不改变时间范围。

Evidence gathering (read-only)

证据收集（只读）

Session history first. Re-read this conversation from the window start: the stated objective, each skill invoked, each
```
Changed
```
list, each
```
Blocked on me
```
, and any answers the user gave. The user's latest instructions override stale state.
Repo state. Confirm what the history claims against disk:
bash
```
git status --short --branch
git log --oneline -20
git diff --stat HEAD
```
Uncommitted files count as in-progress, not done.
GitHub state (when
```
gh
```
is available): open PRs and their checks for touched branches, PRs merged during the window and their post-merge check state, issue state for referenced
```
#N
```
s. CI results decide "done" — a merged PR with red checks is not done.
Checklist. If
```
TASKS.md
```
exists at the repo root, tick state is evidence for done/in-progress.
Deltas only. Events before the window appear only when needed for context (one line, marked "before window").

Do not re-derive history the session already settled. Do not ask the user anything git or the transcript can answer.

优先查看会话历史。 从时间范围起点重新阅读本次对话：既定目标、调用过的每个 skill、每个
```
Changed
```
列表、每个
```
Blocked on me
```
，以及用户给出的所有答复。用户的最新指令优先于过期状态。
Repo 状态。 与磁盘实际状态核对历史记录中的内容：
bash
```
git status --short --branch
git log --oneline -20
git diff --stat HEAD
```
未提交的文件算作进行中，而不是已完成。
GitHub 状态（当
```
gh
```
可用时）：查看已触及分支的开放 PR 及其 checks、时间范围内合并的 PR 及其合并后 check 状态，以及所引用
```
#N
```
的 issue 状态。CI 结果决定是否“done”——已合并但 checks 失败的 PR 不算完成。
Checklist。 如果 repo 根目录存在
```
TASKS.md
```
，其勾选状态是判断完成或进行中的证据。
仅报告增量。 时间范围之前的事件仅在需要上下文时提及（用一行，并标记为“before window”）。

不要重新推导会话中已经确定的结论。不要询问任何 git 或对话记录已经能够回答的问题。

Verdict rules

结论规则

Done only with evidence: test run passed, checks green, PR merged, file committed. "I wrote it" is in-progress until proven.
In progress covers anything started, uncommitted, or waiting on CI.
Continuing marks work already running when the sitrep lands:
```
<item> — Continuing; next checkpoint: <observable state>
```
. Do not pair it with a re-invoke of the active skill — the skill is already running and must not be restarted.
Blocked distinguishes: blocked on the user (decision, credential, approval) vs blocked on an external system (CI, deploy, vendor). Name the exact unblock action.
Next is a ranked list of concrete actions not already underway, each with the skill to invoke (
```
Next: merge-it
```
), not vague intentions. Work in flight belongs under Continuing, not Next. When nothing remains, write
```
Next: none
```
.
Questions lists genuine decisions only the user can make. If there are none, say "none" — do not invent confirmations. Per the contract, one primary question goes under
```
Blocked on me
```
.

Done 必须有证据：test run 通过、checks 全绿、PR 已合并或文件已提交。“我写完了”在得到证明前只能算进行中。
In progress 包括任何已经开始、尚未提交或正在等待 CI 的事项。
Continuing 标记 sitrep 生成时已经在运行的工作：
```
<item> — Continuing; next checkpoint: <observable state>
```
。不要将其与重新调用当前 skill 配对——该 skill 已经在运行，不得重新启动。
Blocked 应区分：被用户阻塞（需要决策、凭据或批准）与被外部系统阻塞（CI、部署、vendor）。必须指出确切的解阻操作。
Next 是尚未开始的具体操作所组成的优先级列表，每项都应注明要调用的 skill（
```
Next: merge-it
```
），不能只写笼统意图。正在进行的工作应归入 Continuing，而不是 Next。如果没有剩余事项，写
```
Next: none
```
。
Questions 只列出只有用户才能做出的真实决策。如果没有，则写“none”——不要虚构需要确认的事项。按照约定，一个主要问题应放在
```
Blocked on me
```
下。

Output shape

输出结构

markdown

**Sitrep** — <window: "since 14:20" / "since last sitrep" / "full session">

**Objective**
<One or two lines: what this run is trying to achieve, from the user's own words.>

**Done**
- <item> — <evidence: commit sha, check run, merge>

**In progress**
- <item> — <state: uncommitted, CI running, awaiting review>
- <work already running> — Continuing; next checkpoint: <observable state>

**Blocked on me**
<The one genuine question or blocker, else "none">

**Next**
1. <action not already underway> — `Next: <exact invoke>`
2. ...

`Next: none` when nothing remains.

**Questions for you**
- <decision only the user can make>, or "none"

**Changed**
<Files, commits, GitHub objects, deploys in the window, else "nothing">

**Found**
<One-line verdict: on track / drifting / blocked, plus the single most important fact. `Next: <primary invoke>`, or `Next: none` when complete. Work already running is reported as Continuing, never as a re-invoke.>

Keep it scannable: bullets, no paragraphs in section bodies except Objective and Found. A sitrep after a quiet window is short — "nothing changed, still blocked on X" is a valid report.

markdown

**Sitrep** — <window: "since 14:20" / "since last sitrep" / "full session">

**Objective**
<One or two lines: what this run is trying to achieve, from the user's own words.>

**Done**
- <item> — <evidence: commit sha, check run, merge>

**In progress**
- <item> — <state: uncommitted, CI running, awaiting review>
- <work already running> — Continuing; next checkpoint: <observable state>

**Blocked on me**
<The one genuine question or blocker, else "none">

**Next**
1. <action not already underway> — `Next: <exact invoke>`
2. ...

`Next: none` when nothing remains.

**Questions for you**
- <decision only the user can make>, or "none"

**Changed**
<Files, commits, GitHub objects, deploys in the window, else "nothing">

**Found**
<One-line verdict: on track / drifting / blocked, plus the single most important fact. `Next: <primary invoke>`, or `Next: none` when complete. Work already running is reported as Continuing, never as a re-invoke.>

保持内容便于浏览：使用项目符号，除 Objective 和 Found 外，各部分正文不要使用段落。静默时间范围之后的 sitrep 应保持简短——“没有变化，仍阻塞于 X”也是有效报告。

Grounding

依据

Read-only situation reports before action follow the SRE incident habit (state of the world before decisions) and the contract's closing headings. Handbook card:

handbook/practices/recon.md

行动前的只读 situation report 遵循 SRE 事故处理惯例（先了解世界状态，再做决策），并遵循 contract 的收尾标题。Handbook card：

handbook/practices/recon.md

。