validator-help

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/validator-help

Evidence-based diagnosis of validator behavior. This skill is diagnosis-only — it explains what happened and why, but does not auto-fix issues. It operates from runtime artifacts and CLI outputs, not source code.

基于证据的验证器行为诊断。本技能仅用于诊断——它会解释发生了什么及原因，但不会自动修复问题。它基于运行时产物和CLI输出而非源代码运行。

Diagnostic Workflow

诊断工作流

Follow this order for every diagnostic question:

Resolve
log_dir
: Read
```
.validator/config.yml
```
and extract the
```
log_dir
```
field (default:
```
validator_logs
```
). All log paths below are relative to
```
<log_dir>/
```
.
Passive evidence first: Read files before running commands.
- ```
<log_dir>/.debug.log
```
  — timestamped event log (commands, gate results, state changes, errors)
- ```
<log_dir>/.execution_state
```
  — JSON with
```
last_run_completed_at
```
  ,
```
branch
```
  ,
```
commit
```
  ,
```
working_tree_ref
```
  , and
```
unhealthy_adapters
```
  (adapter name →
```
{marked_at, reason}
```
  )
- ```
<log_dir>/console.*.log
```
  — console output per run (highest number = latest)
- ```
<log_dir>/check_*.log
```
  — check gate output
- ```
<log_dir>/review_*.json
```
  — review gate results with violations (
```
file
```
  ,
```
line
```
  ,
```
issue
```
  ,
```
fix
```
  ,
```
priority
```
  ,
```
status
```
  )
- ```
.validator/config.yml
```
  — project configuration
Active evidence when needed: Run CLI commands only when passive evidence is insufficient for a confident diagnosis.
Explain with evidence: Clearly distinguish confirmed findings from inference.

针对每个诊断问题，请遵循以下顺序：

解析
log_dir
：读取
```
.validator/config.yml
```
并提取
```
log_dir
```
字段（默认值：
```
validator_logs
```
）。以下所有日志路径均相对于
```
<log_dir>/
```
。
优先使用被动证据：先读取文件，再运行命令。
- ```
<log_dir>/.debug.log
```
  —— 带时间戳的事件日志（命令、检查门结果、状态变更、错误信息）
- ```
<log_dir>/.execution_state
```
  —— JSON文件，包含
```
last_run_completed_at
```
  、
```
branch
```
  、
```
commit
```
  、
```
working_tree_ref
```
  和
```
unhealthy_adapters
```
  （适配器名称 →
```
{marked_at, reason}
```
  ）
- ```
<log_dir>/console.*.log
```
  —— 每次运行的控制台输出（数字越大表示最新）
- ```
<log_dir>/check_*.log
```
  —— 检查门输出
- ```
<log_dir>/review_*.json
```
  —— 包含违规项的检查门结果（
```
file
```
  、
```
line
```
  、
```
issue
```
  、
```
fix
```
  、
```
priority
```
  、
```
status
```
  ）
- ```
.validator/config.yml
```
  —— 项目配置文件
必要时使用主动证据：仅当被动证据不足以做出可靠诊断时，才运行CLI命令。
结合证据进行解释：明确区分已确认的发现与推断内容。

Evidence Sources

证据来源

Source	What It Confirms
`.validator/config.yml`	`log_dir` , `base_branch` , `entry_points` , `cli.default_preference` , `max_retries` , `rerun_new_issue_threshold`
`<log_dir>/.debug.log`	Timestamped event history: commands executed, gate results, state transitions, errors
`<log_dir>/.execution_state`	Last successful run timestamp, branch/commit at that time, working tree stash ref, unhealthy adapter cooldowns
`<log_dir>/console.*.log`	Human-readable output from each run iteration
`<log_dir>/check_*.log`	Raw output from check gate commands (linters, test runners, etc.)
`<log_dir>/review_*.json`	Structured review violations with file, line, issue, priority, and resolution status
`<log_dir>/.validator-run.lock`	Lock file (contains PID) — present only during active execution
`<log_dir>/.ci-wait-attempts`	CI wait attempt counter

来源	可确认内容
`.validator/config.yml`	`log_dir` 、 `base_branch` 、 `entry_points` 、 `cli.default_preference` 、 `max_retries` 、 `rerun_new_issue_threshold`
`<log_dir>/.debug.log`	带时间戳的事件历史：执行的命令、检查门结果、状态转换、错误信息
`<log_dir>/.execution_state`	上次成功运行的时间戳、当时的分支/提交、工作树暂存引用、不健康适配器冷却时间
`<log_dir>/console.*.log`	每次运行迭代的人类可读输出
`<log_dir>/check_*.log`	检查门命令的原始输出（代码检查器、测试运行器等）
`<log_dir>/review_*.json`	结构化的检查违规项，包含文件、行号、问题、优先级和解决状态
`<log_dir>/.validator-run.lock`	锁定文件（包含PID）——仅在执行过程中存在
`<log_dir>/.ci-wait-attempts`	CI等待尝试计数器

CLI Command Quick-Reference

CLI命令速查

Use these only when passive evidence is insufficient:

Command	When to Use
`agent-validate list`	See configured gates and entry points
`agent-validate health`	Check adapter availability and health status
`agent-validate detect`	See which files changed and which gates would apply
`agent-validate validate`	Validate config.yml syntax and schema
`agent-validate clean`	Archive current logs and reset state (destructive — confirm with user first)

仅在被动证据不足时使用以下命令：

命令	使用场景
`agent-validate list`	查看已配置的检查门和入口点
`agent-validate health`	检查适配器的可用性和健康状态
`agent-validate detect`	查看哪些文件已变更以及将应用哪些检查门
`agent-validate validate`	验证config.yml的语法和 schema
`agent-validate clean`	归档当前日志并重置状态（具有破坏性——需先征得用户确认）

Routing Logic

路由逻辑

Based on the user's question, load the appropriate reference file for detailed guidance:

Question Domain	Reference File
Missing config, YAML errors, misconfiguration, init problems	`references/config-troubleshooting.md`
Check failures, review failures, no_changes, no_applicable_gates, rerun mode	`references/gate-troubleshooting.md`
Lock conflict, stale locks, parallel runs, cleanup	`references/lock-troubleshooting.md`
Adapter health, missing tools, usage limits, cooldown	`references/adapter-troubleshooting.md`

If the question spans multiple domains, load each relevant reference.

根据用户的问题，加载相应的参考文件以获取详细指导：

问题领域	参考文件
配置缺失、YAML错误、配置错误、初始化问题	`references/config-troubleshooting.md`
检查失败、审核失败、无变更、无适用检查门、重运行模式	`references/gate-troubleshooting.md`
锁定冲突、过期锁定、并行运行、清理	`references/lock-troubleshooting.md`
适配器健康、工具缺失、使用限制、冷却	`references/adapter-troubleshooting.md`

如果问题涉及多个领域，请加载所有相关参考文件。

Output Contract

输出约定

Every diagnostic response MUST include these sections:

每个诊断响应必须包含以下部分：

Diagnosis

诊断结果

What happened and why, stated clearly.

明确说明发生了什么及原因。

Evidence

证据

Specific files read, field values observed, and command outputs that support the diagnosis. Quote relevant log lines or config values.

支持诊断结果的具体读取文件、观察到的字段值和命令输出。引用相关日志行或配置值。

Confidence

置信度

One of:

High — diagnosis is fully supported by direct evidence
Medium — diagnosis is likely but some evidence is missing or ambiguous
Low — diagnosis is inferred; key evidence is unavailable

Downgrade confidence when:

```
.debug.log
```
or
```
.execution_state
```
is missing or empty
Log files referenced in output don't exist
Config values can't be verified
CLI commands fail or return unexpected output

以下选项之一：

高——诊断结果完全由直接证据支持
中——诊断结果大概率成立，但部分证据缺失或模糊
低——诊断结果为推断；关键证据不可用

出现以下情况时降低置信度：

```
.debug.log
```
或
```
.execution_state
```
缺失或为空
输出中引用的日志文件不存在
无法验证配置值
CLI命令执行失败或返回意外输出

Next Steps

下一步操作

Actionable recommendations for the user. If confidence is not high, suggest what additional evidence would confirm the diagnosis.

为用户提供可执行的建议。如果置信度不高，建议用户提供哪些额外证据以确认诊断结果。

Bug Filing

Bug提交

After completing your diagnosis, apply the following routing logic to determine whether to file a GitHub issue:

High confidence + bug indicated (evidence points to a defect in agent-validator, not a configuration issue, user error, or expected behavior): Automatically invoke
```
validator-issue
```
with
```
--auto-file <diagnosis summary>
```
as arguments. This passes the diagnosis summary as the bug description and skips the interactive confirmation — the issue is filed immediately after showing the draft.
High confidence + not a bug (diagnosis concludes configuration issue, user error, or expected behavior): Do nothing. Do not invoke
```
validator-issue
```
.
Medium confidence + possible bug (evidence suggests a possible validator defect but is not conclusive): Ask the user: "This may be a validator bug. Want me to file a GitHub issue?" If the user confirms, invoke
```
validator-issue
```
with the diagnosis summary as the bug description. If the user declines, exit without filing.
Low confidence: Do nothing. Do not prompt the user and do not invoke
```
validator-issue
```
.

完成诊断后，应用以下路由逻辑判断是否提交GitHub Issue：

高置信度 + 确认存在Bug（证据表明问题源于agent-validator的缺陷，而非配置问题、用户错误或预期行为）：自动调用
```
validator-issue
```
并传入
```
--auto-file <诊断摘要>
```
作为参数。这会将诊断摘要作为Bug描述传递，并跳过交互式确认——在显示草稿后立即提交Issue。
高置信度 + 非Bug（诊断结果表明是配置问题、用户错误或预期行为）：不执行任何操作。请勿调用
```
validator-issue
```
。
中置信度 + 可能存在Bug（证据表明可能存在验证器缺陷，但结论不明确）：询问用户：“这可能是一个验证器Bug。需要我提交GitHub Issue吗？”如果用户确认，调用
```
validator-issue
```
并将诊断摘要作为Bug描述。如果用户拒绝，则退出且不提交。
低置信度：不执行任何操作。请勿提示用户，也不要调用
```
validator-issue
```
。