no-mistakes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

no-mistakes

no-mistakes

is a local gate that validates your code changes through a pipeline (intent, rebase, review, test, document, lint, push, PR, CI) before they reach upstream. You drive it through the

no-mistakes axi

command family, which prints machine-readable TOON to stdout and progress to stderr.

When the user invokes

/no-mistakes

, report the outcome at the end. If the user asks for something specific, translate that request into the matching

axi run

flags yourself - for example, "skip the lint step" becomes

--skip=lint

. Run

no-mistakes axi run --help

to see the available flags.

no-mistakes

是一个本地把关工具，可通过一套流水线（意图确认、变基、审查、测试、文档生成、代码检查、推送、拉取请求、持续集成）在代码提交到上游之前验证您的代码变更。您可通过

no-mistakes axi

命令族来操作它，该命令族会将机器可读的 TOON 格式内容输出到标准输出（stdout），并将进度信息输出到标准错误（stderr）。

当用户调用

/no-mistakes

时，请在最后报告结果。如果用户有特定要求，请将其转换为对应的

axi run

参数——例如，“跳过lint步骤”对应

--skip=lint

。运行

no-mistakes axi run --help

可查看可用参数。

Two ways to invoke

两种调用方式

/no-mistakes

works in two modes, depending on whether the user hands you a task along with the command:

Validate-only - bare
```
/no-mistakes
```
(optionally with flag-style requests like "skip the lint step"). The user's code changes are already committed; validate them and report the outcome.
Task-first -
```
/no-mistakes <task>
```
, e.g.
```
/no-mistakes add a --json flag to the status command
```
. First carry out the task yourself, then validate the result through the pipeline:
1. Check scope. Inspect
```
git status
```
  before you change or commit anything. Preserve unrelated pre-existing uncommitted changes, and when you commit, commit only the changes that belong to the user's task.
2. Do the work. Make the changes the task describes, then commit them on a feature branch. If the user is on the repository's default branch, create a feature branch first - the gate validates committed history on a non-default branch, so the work must land there before you run.
3. Then validate, passing the user's task as your
```
--intent
```
  . The task text is exactly what the user set out to accomplish, in their own words, so it is the intent - pass it through, enriched with the decisions and tradeoffs you made while doing the work (see Intent is required).

Everything below - preconditions, intent, the validate-and-decide loop - applies the same way once the work is committed on a feature branch.

/no-mistakes

有两种运行模式，取决于用户是否在命令后附带任务：

仅验证模式 - 直接使用
```
/no-mistakes
```
（可附带类似“跳过lint步骤”的参数式请求）。此时用户的代码变更已提交，只需验证并报告结果即可。
先执行任务模式 -
```
/no-mistakes <任务内容>
```
，例如
```
/no-mistakes 为status命令添加--json参数
```
。先自行完成任务，再通过流水线验证结果：
1. 检查范围。在进行任何修改或提交前，先查看
```
git status
```
  。保留无关的未提交变更，提交时仅提交与用户任务相关的变更。
2. 执行任务。按照任务描述进行修改，然后在特性分支（feature branch）上提交。如果用户当前在仓库的默认分支上，请先创建一个特性分支——把关工具会验证非默认分支上的提交历史，因此必须先将工作内容提交到特性分支才能运行验证。
3. 进行验证，将用户的任务内容作为
```
--intent
```
  参数传入。任务文本是用户明确要完成的目标，用他们自己的表述即可，这就是意图——直接传入即可，同时可补充您在执行任务过程中做出的决策和权衡（详见必须传入意图部分）。

后续内容——前置条件、意图、验证与决策循环——在工作内容提交到特性分支后均适用。

Before you start

开始前的准备

The work you want validated must be committed on a branch. The gate validates committed history, not your uncommitted working tree.
You must be on a feature branch, not the repository's default branch.
The repository must already be initialized with
```
no-mistakes init
```
.

If any of these is not met,

axi run

returns an

error:

with the exact command to fix it - read it and act on it (commit your work, or create a branch). If the repository is not initialized, run

no-mistakes init

first; if the

no-mistakes

command itself is missing or misbehaving,

no-mistakes doctor

reports what is wrong. Before starting, a quick

no-mistakes axi

(home view) shows whether a run is already active - resume or

axi abort

it rather than starting a second run on top of it.

待验证的工作内容必须已提交到某个分支。把关工具验证的是提交历史，而非未提交的工作区内容。
您必须处于特性分支上，而非仓库的默认分支。
仓库必须已通过
```
no-mistakes init
```
完成初始化。

如果以上任一条件未满足，

axi run

会返回

error:

并给出具体的修复命令——请阅读并执行（提交工作内容，或创建分支）。如果仓库未初始化，请先运行

no-mistakes init

；如果

no-mistakes

命令本身缺失或异常，

no-mistakes doctor

会报告问题所在。开始前，运行

no-mistakes axi

（主视图）可查看是否已有正在运行的任务——请恢复任务或运行

axi abort

终止任务，避免在已有任务的基础上启动新任务。

Intent is required

必须传入意图

When you start a run you must pass

--intent

: what the user set out to accomplish - the goal or request behind this work, in their terms. This is not a description of the diff or the files you changed; it is the objective the change is meant to achieve. You know it from the conversation, so pass it directly - no-mistakes uses it verbatim instead of inferring it from local agent transcripts (slower and flakier).

Err on the side of completeness, not brevity. The review step uses

--intent

to tell a deliberate decision apart from a mistake, so a thin one-line summary makes it flag things the user already chose. Capture the nuance: the user's goal, the specific decisions and tradeoffs they made along the way, any constraints or approaches they ruled in or out, and anything they explicitly asked for that might otherwise look surprising in the diff. A few sentences to a short paragraph is normal - write down what you learned from the conversation that a reviewer reading only the diff would not know.

启动任务时必须传入

--intent

参数：用户想要完成的目标——即本次工作背后的需求或请求，用用户的表述即可。这不是对代码差异或修改文件的描述，而是变更要实现的目标。您可从对话中获取该信息，直接传入即可——no-mistakes会直接使用该文本，而不是从本地代理记录中推断（速度慢且不稳定）。

宁可详细，不要简略。审查步骤会使用

--intent

来区分故意决策和错误，因此过于简短的摘要可能会将用户已选择的内容标记为问题。请捕捉细节：用户的目标、执行过程中做出的具体决策和权衡、排除的约束或方案，以及任何用户明确要求但在代码差异中可能显得异常的内容。通常写几句话到一小段即可——写下您从对话中了解到的、仅查看代码差异的审查者无法知晓的信息。

Validate and decide

验证与决策

Run the pipeline and decide on its findings as they come up:

Start the run. It blocks until the first decision point or the end:
sh
```
no-mistakes axi run --intent "<what the user set out to accomplish>"
```
```
axi run
```
and every
```
axi respond
```
block synchronously - the review, test, and CI steps can each take several minutes, so a single call may not return for a while. That is normal; allow a long timeout and do not cancel or re-issue the command because it seems slow. To check progress without disturbing the run, use
```
no-mistakes axi status
```
from a separate call.
If the output contains a
```
gate:
```
object, the pipeline is waiting on you. Read its
```
findings
```
table. Each finding has an
```
id
```
,
```
severity
```
,
```
file
```
,
```
description
```
, and an
```
action
```
that tells you how the pipeline classified it:
- ```
auto-fix
```
  - mechanical and low-risk; you can authorize the fix on your own judgment by responding with
```
--action fix
```
  .
- ```
no-op
```
  - informational only; nothing to do.
- ```
ask-user
```
  - the finding challenges the user's deliberate intent or touches product behavior. This is a call only the user can make - see
  Escalate
```
ask-user
```
  findings
  below.
Choose one response:
sh
```
# accept the step as-is and continue
no-mistakes axi respond --action approve

# have the pipeline fix specific findings, then continue
no-mistakes axi respond --action fix --findings <id1,id2> --instructions "<optional guidance>"

# skip this step
no-mistakes axi respond --action skip
```
While a run is active, never fix findings by editing the code yourself - the pipeline owns both the findings and the fixes. Your job at a gate is to decide and respond;
```
--action fix
```
has the pipeline apply the fix and re-review the result.
Each
```
respond
```
blocks until the next
```
gate:
```
,
```
checks-passed
```
decision point, or final outcome.
Two extra flags are available on
```
respond
```
when you need them:
- ```
--add-finding '<json>'
```
  (with
```
--action fix
```
  ) folds a finding you spotted yourself - one the pipeline did not surface - into the fix round, as a JSON finding object. Use it for a problem you noticed that is not in the gate's own
```
findings
```
  table.
- ```
--step <name>
```
  responds to a specific step instead of the one currently awaiting approval. You rarely need this; omit it to answer the active gate.
Repeat step 2 until the output has an
```
outcome:
```
instead of a
```
gate:
```
. The outcomes are:
- ```
checks-passed
```
  - the change is validated and CI is green, but the PR is not merged yet. You are done driving the pipeline. Do not wait for the merge: tell the user the PR is ready and ask them to review and merge it (the PR link is in the
```
help
```
  line). no-mistakes keeps monitoring the PR in the background, so a human can watch it in the TUI.
- ```
passed
```
  - the changes cleared the gate and the PR was merged or closed.
- ```
failed
```
  or
```
cancelled
```
  - they did not; read the output and address it. Fix whatever the output points at (a failing test, a lint error, a finding you skipped), commit the fix on the same feature branch, then drive the pipeline again -
```
no-mistakes axi run --intent "..."
```
  starts a fresh run, or
```
no-mistakes rerun
```
  re-runs the pipeline for the current branch. Do not leave the user at a
```
failed
```
  outcome without either retrying or explaining what blocks it.

The CI step deliberately watches the PR until it is merged or closed, so

axi run

returns

checks-passed

the moment checks are green rather than blocking on the human merge. Never poll or re-run waiting for the merge yourself.

On a successful outcome (

checks-passed

passed

), close the loop with the user: summarize what happened during the pipeline in a concise, easily readable format - what was validated and what was found. If the output includes a

fixes

table, the pipeline fixed findings your original change missed: acknowledge those misses and explicitly list each fix so the user can easily review them.

运行流水线并根据结果做出决策：

启动任务。任务会阻塞直到第一个决策点或结束：
sh
```
no-mistakes axi run --intent "<用户想要完成的目标>"
```
```
axi run
```
和所有
```
axi respond
```
命令都会同步阻塞——审查、测试和CI步骤可能各需数分钟，因此单次调用可能不会立即返回。这是正常现象，请设置较长的超时时间，不要因看似缓慢而取消或重新发起命令。如需在不干扰任务的情况下查看进度，请在单独的调用中使用
```
no-mistakes axi status
```
。
如果输出包含
```
gate:
```
对象，则流水线正在等待您的决策。请阅读其
```
findings
```
表格。每条结果包含
```
id
```
、
```
severity
```
（严重程度）、
```
file
```
（文件）、
```
description
```
（描述）和
```
action
```
（操作建议），用于说明流水线对该结果的分类：
- ```
auto-fix
```
  - 机械性且低风险的问题；您可自行判断并通过
```
--action fix
```
  授权修复。
- ```
no-op
```
  - 仅为信息提示；无需操作。
- ```
ask-user
```
  - 该结果挑战了用户的故意意图或涉及产品行为变更。这只能由用户做出决策——详见下文上报ask-user类结果。
选择以下响应之一：
sh
```
# 接受当前步骤并继续
no-mistakes axi respond --action approve

# 让流水线修复指定结果，然后继续
no-mistakes axi respond --action fix --findings <id1,id2> --instructions "<可选指导>"

# 跳过此步骤
no-mistakes axi respond --action skip
```
当任务正在运行时，请勿自行编辑代码修复问题——流水线负责结果的发现和修复。您在把关环节的职责是做出决策并响应；
```
--action fix
```
会让流水线应用修复并重新审查结果。
每次
```
respond
```
都会阻塞直到下一个
```
gate:
```
、
```
checks-passed
```
决策点或最终结果。
当需要时，
```
respond
```
命令还有两个额外参数：
- ```
--add-finding '<json>'
```
  （需搭配
```
--action fix
```
  ）可将您自己发现的、流水线未识别的问题以JSON结果对象的形式加入修复环节，用于处理把关环节
```
findings
```
  表格中未列出的问题。
- ```
--step <name>
```
  可响应特定步骤，而非当前等待批准的步骤。您很少需要使用此参数；省略该参数即可响应当前活跃的把关环节。
重复步骤2，直到输出显示
```
outcome:
```
而非
```
gate:
```
。结果包括：
- ```
checks-passed
```
  - 变更已通过验证且CI状态为绿色，但PR尚未合并。您的流水线操作已完成。无需等待合并：告知用户PR已准备就绪，请他们审查并合并（PR链接在
```
help
```
  行中）。no-mistakes会在后台持续监控PR，用户可在TUI中查看。
- ```
passed
```
  - 变更已通过把关环节，PR已合并或关闭。
- ```
failed
```
  或
```
cancelled
```
  - 变更未通过；请阅读输出并处理问题。修复输出指出的问题（如测试失败、lint错误、跳过的结果），在同一特性分支上提交修复，然后重新运行流水线——
```
no-mistakes axi run --intent "..."
```
  会启动新任务，或
```
no-mistakes rerun
```
  会重新运行当前分支的流水线。请勿让用户停留在
```
failed
```
  结果而不重试或解释阻塞原因。

CI步骤会特意监控PR直到其合并或关闭，因此

axi run

会在检查通过后立即返回

checks-passed

，而非等待人工合并。请勿自行轮询或重新运行以等待合并。

当结果成功时（

checks-passed

或

passed

），请向用户反馈：以简洁易读的格式总结流水线运行过程——验证了哪些内容，发现了哪些问题。如果输出包含

fixes

表格，说明流水线修复了您原始变更中遗漏的问题：请确认这些遗漏，并明确列出每个修复，以便用户轻松查看。

Escalate

ask-user

findings

上报ask-user类结果

A gate whose findings are all

auto-fix

no-op

is safe to drive on your own judgment: respond with

--action fix

--action approve

as appropriate. But a finding marked

ask-user

is a decision that belongs to the user, not you - the pipeline flagged it because it challenges their deliberate intent or changes product behavior. Do not approve, fix, or skip it on your own. Instead, stop and bring it to the user before you respond:

Relay each
```
ask-user
```
finding to them as the pipeline wrote it - its
```
id
```
,
```
file
```
, and full
```
description
```
verbatim. Do not paraphrase, summarize away the detail, or pre-judge the answer.
Ask how they want to proceed, then translate their decision into the matching
```
respond
```
call:
```
--action fix
```
(pass their guidance through
```
--instructions
```
),
```
--action approve
```
, or
```
--action skip
```
.

The one exception is

--yes

(below): it is the user's standing consent to drive every gate unattended, so under

--yes

you resolve

ask-user

findings automatically instead of stopping to ask.

If you have clear consent to drive the run automatically, pass

--yes

axi run

axi respond

. It treats every actionable finding -

auto-fix

and

ask-user

alike - as consent to fix it, selects every current finding for one fix round, accepts the resulting fix review, and approves gates with only

no-op

findings. Only use it when the user has asked you to drive the whole run without checking back.

如果把关环节的结果均为

auto-fix

或

no-op

，您可自行判断并响应：根据情况使用

--action fix

或

--action approve

。但标记为

ask-user

的结果只能由用户决策，而非您——流水线标记它是因为它挑战了用户的故意意图或涉及产品行为变更。请勿自行批准、修复或跳过该结果。相反，请在响应前暂停并将其告知用户：

按照流水线的原始表述，将每个
```
ask-user
```
结果的
```
id
```
、
```
file
```
和完整
```
description
```
原封不动地转告用户。请勿 paraphrase、省略细节或预先判断答案。
询问用户如何处理，然后将他们的决策转换为对应的
```
respond
```
调用：
```
--action fix
```
（通过
```
--instructions
```
传入用户的指导）、
```
--action approve
```
或
```
--action skip
```
。

唯一的例外是

--yes

（如下）：这是用户授权您自动处理所有把关环节的同意指令，因此在使用

--yes

时，您可自动处理

ask-user

结果，无需暂停询问。

如果您获得了明确的自动运行授权，请在

axi run

或

axi respond

中传入

--yes

参数。它会将所有可操作结果——包括

auto-fix

和

ask-user

——视为同意修复，选择当前所有结果进行一轮修复，接受修复后的审查结果，并批准仅包含

no-op

结果的把关环节。仅当用户要求您全程自动运行任务而无需反馈时使用此参数。

Inspecting state

查看状态

no-mistakes axi               # home view: active run, recent runs, next steps
no-mistakes axi status        # full detail of the active (or most recent) run
no-mistakes axi logs --step <name> --full   # full log output of one step
no-mistakes axi abort         # cancel the active run

no-mistakes axi               # 主视图：活跃任务、最近任务、下一步操作
no-mistakes axi status        # 活跃（或最近）任务的详细信息
no-mistakes axi logs --step <name> --full   # 某一步骤的完整日志输出
no-mistakes axi abort         # 取消活跃任务

Reading the output

解读输出

Output is TOON:
```
key: value
```
pairs,
```
name[N]{cols}:
```
tables, and
```
help[N]:
```
hints.
The
```
help
```
list at the bottom of most responses tells you the next commands to run.
Errors are printed as
```
error: ...
```
on stdout with a
```
help
```
list; act on the suggestion.
Exit codes:
```
0
```
success, no-op, or normal decision gates,
```
1
```
failed or cancelled final outcomes,
```
2
```
bad usage.

gate:

waiting on you looks roughly like this - a

gate:

line naming the step, a

findings[N]{...}:

table with one row per finding, and a

help[N]:

list of next commands:

gate: review
findings[2]{id,severity,file,description,action}:
  r1,medium,internal/pipeline/executor.go,Error from os.Remove is ignored,auto-fix
  r2,high,cmd/no-mistakes/main.go,New --force flag bypasses the confirm prompt,ask-user
help[2]:
  no-mistakes axi respond --action fix --findings r1
  no-mistakes axi respond --action approve

Read the

action

column per row: decide

r1

(auto-fix) on your own judgment -

respond --action fix --findings r1

hands it to the pipeline to fix - but stop and escalate

r2

(ask-user) to the user before responding. A final state instead shows

outcome: <checks-passed|passed|failed|cancelled>

with no

findings

table. Field names and exact columns can vary by step and version, so read the actual

findings

header rather than assuming this layout.

输出采用TOON格式：
```
key: value
```
键值对、
```
name[N]{cols}:
```
表格和
```
help[N]:
```
提示。
大多数响应底部的
```
help
```
列表会告知您下一步要运行的命令。
错误信息会以
```
error: ...
```
的形式输出到标准输出，并附带
```
help
```
列表；请按照建议操作。
退出码：
```
0
```
表示成功、无操作或正常决策环节，
```
1
```
表示最终结果为失败或取消，
```
2
```
表示使用错误。

等待您决策的

gate:

大致如下——一行

gate:

标明步骤，一个

findings[N]{...}:

表格包含每条结果，还有一个

help[N]:

列表显示下一步命令：

gate: review
findings[2]{id,severity,file,description,action}:
  r1,medium,internal/pipeline/executor.go,Error from os.Remove is ignored,auto-fix
  r2,high,cmd/no-mistakes/main.go,New --force flag bypasses the confirm prompt,ask-user
help[2]:
  no-mistakes axi respond --action fix --findings r1
  no-mistakes axi respond --action approve

请逐行查看

action

列：自行判断处理

r1

（auto-fix）——运行

respond --action fix --findings r1

让流水线修复——但在响应前需暂停并将

r2

（ask-user）上报给用户。最终状态会显示

outcome: <checks-passed|passed|failed|cancelled>

，且无

findings

表格。字段名称和具体列可能因步骤和版本而异，请以实际的

findings

表头为准。