report

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Report

报告

$ARGUMENTS

is the scope — a subsystem, a flow, a question, or a directory. Empty means the whole project.

The run touches no code. The deliverable is one Markdown file:

git status

at the end shows the tree you started with, plus that file.

A report is a snapshot of the code as it stands today, so it cites

file_path:line_number

everywhere. The repo rule that keeps paths out of

spec.md

does not reach here — that rule protects documents meant to outlive the code, and a snapshot is not one.

$ARGUMENTS

表示范围——可以是子系统、流程、问题或目录。为空则表示整个项目。

本次运行不会修改任何代码。交付物为一个 Markdown 文件：结束时执行

git status

，应显示启动时的目录树，外加该文件。

报告是代码当前状态的快照，因此所有内容都应引用

file_path:line_number

。仓库中禁止在

spec.md

中写入路径的规则不适用于此处——该规则用于保护需要比代码存续更久的文档，而快照不属于这类文档。

Run Flow

执行流程

1. Fix the scope

1. 确定范围

Say back in one line what you are about to report on, and name where the file lands:

.scratch/<yymmdd-slug>/report.md

, the slug named for the scope. When the scope belongs to a plan folder that already exists, write it there instead. Then start — the user reads the line and stops you if it is wrong.

用一行说明即将报告的范围，并注明文件保存位置：

.scratch/<yymmdd-slug>/report.md

，其中 slug 根据范围命名。如果范围属于一个已存在的 plan 目录，则改为写入那里。然后开始执行——用户会阅读这行说明，并在范围有误时叫停。

2. Read the domain docs

2. 阅读领域文档

Read the repo's domain documentation before you open any code —

docs/agents/domain.md

says which files those are and how to use them. The words in

CONTEXT.md

are the words the report uses.

在打开任何代码前，先阅读仓库的领域文档——

docs/agents/domain.md

会说明这些文件是哪些以及如何使用。报告应使用

CONTEXT.md

中的术语。

3. Sweep

3. 广泛扫描

Breadth first, before you read anything closely. Walk the whole scope: top-level directories, entry points, routes and console commands, config, dependency manifests, the test tree, and what recent git history has been touching.

Done when: every directory and manifest in scope carries a line — what it holds, or why the report can pass over it. A part you never opened is a part you cannot leave out quietly.

先广后深，在细读任何内容之前。遍历整个范围：顶层目录、入口点、路由和控制台命令、配置、依赖清单、测试目录结构，以及近期 Git 历史一直触及的内容。

完成标准：范围内的每个目录和清单文件都要在报告中占一行——说明其包含什么，或报告为何可以略过。未打开过的部分绝不能悄然略去。

4. Drill

4. 深入分析

Now go deep on what the sweep raised. Read each file that matters in full, follow it out to its callers and its tests, and trace each main flow end to end — entry point, through the layers, to the data and back.

Done when: every claim the report is about to make is grounded — you can name the

file_path:line_number

it came from. What the code does not answer is an unknown, named as one, never filled in from memory.

接下来对广泛扫描发现的内容进行深入分析。完整阅读每个重要文件，一路追踪至其调用方和相关测试，并端到端梳理每条主要流程——从入口点贯穿各层，追踪至数据并沿原路径返回。

完成标准：报告即将做出的每项论断都必须有依据——能够指出其来源

file_path:line_number

。代码无法解答的内容属于未知项，应明确标为未知项，绝不能凭记忆补全。

5. Write the report

5. 撰写报告

Write the file with these sections, in this order. A section the scope does not reach gets one line saying so — the skeleton stays whole either way.

markdown

undefined

按以下顺序和章节撰写文件。如果范围未涉及某一节，用一行说明即可——无论范围如何，都应保留完整结构。

markdown

undefined

Report — <scope>

What it is

What this project does, and who for.

How it is built

The stack, the layout, and what each top-level part holds.

How it runs

Entry points, commands, environments, and what has to be in place to boot it.

Domain

The concepts the code works in, and the words it uses for them, in

CONTEXT.md

terms.

The concepts the code works in, and the words it uses for them, in

CONTEXT.md

terms.

Key flows

Each main flow traced end to end, step by step.

Tests

What is covered, at which seams, and what is not covered.

Findings

What is stale, risky, duplicated, or missing — one line each.

Unknowns

What the code does not answer, and what it would take to settle each one.


**Done when**: every section is present, every claim outside Unknowns carries its `file_path:line_number`, and everything step 4 could not settle is sitting in Unknowns.

What the code does not answer, and what it would take to settle each one.


**完成标准**：每个章节都存在，Unknowns 之外的每项论断都附有 `file_path:line_number`，且步骤 4 中无法确定的所有内容都列入 Unknowns。

6. Hand back

6. 交付结果

Give the user the path and the Findings and Unknowns lists in the chat, so they can act without opening the file.

在聊天中向用户提供文件路径以及 Findings 和 Unknowns 列表，使用户无需打开文件即可采取行动。

Where it hands off

后续处理与转交

This skill ends at the report. When it points at work, name the skill and leave the call to the user.

A finding worth building or fixing —
```
plan-create
```
for a feature,
```
run
```
for a task,
```
fix
```
for a bug
The design of what the report walked through —
```
solid-check
```
The question turned out to be about a package or an external API, not this codebase —
```
research
```
A term the report had to invent, or a decision it uncovered that would be hard to undo — offer
```
domain-modeling
```
to record it in
```
CONTEXT.md
```
or as an ADR under
```
docs/adr/
```

此 skill 在报告完成后结束。当报告指向某项工作时，说明对应的 skill，并将决定权留给用户。

值得开发或修复的发现——功能使用
```
plan-create
```
，任务使用
```
run
```
，缺陷使用
```
fix
```
需要评审报告所梳理内容的设计——使用
```
solid-check
```
如果问题实际针对的是 package 或外部 API，而非本代码库——使用
```
research
```
如果报告中不得不创造某个术语，或发现了难以撤销的决策——提供
```
domain-modeling
```
，将其记录在
```
CONTEXT.md
```
中，或作为
```
docs/adr/
```
下的 ADR