dimensional-analysis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dimensional Analysis Skill

量纲分析Skill

This skill orchestrates a dimensional-analysis pipeline for codebases that perform numeric computations with mixed units, precisions, or scaling factors. The main skill context is a workflow controller only: it delegates scanning, vocabulary discovery, annotation, propagation, and validation to specialized subagents, then manages batching, persistence, retries, coverage gates, and final reporting.

该Skill为包含混合单位、精度或缩放因子的数值计算代码库编排量纲分析流水线。主Skill仅作为工作流控制器：它将扫描、词汇发现、注释标注、传播和验证工作委托给专门的子代理，然后管理批量处理、持久化、重试、覆盖检查和最终报告。

When to Use

使用场景

Annotating a codebase with unit/dimension comments (e.g.,
```
D18{tok}
```
,
```
D27{UoA/tok}
```
)
Performing dimensional analysis on DeFi protocols, financial code, or scientific computations
Hunting for arithmetic bugs caused by unit mismatches, missing scaling, or precision loss
Auditing codebases with mixed decimal precisions or fixed-point arithmetic

为代码库添加单位/量纲注释（例如
```
D18{tok}
```
、
```
D27{UoA/tok}
```
）
对DeFi协议、金融代码或科学计算代码执行量纲分析
排查由单位不匹配、缺失缩放或精度损失导致的算术bug
审计包含混合小数精度或定点算术的代码库

When NOT to Use

不适用场景

Codebases with no numeric arithmetic or unit conversions — there is nothing to annotate
Pure integer counting logic (loop indices, array lengths) with no physical or financial dimensions
When you only need a quick spot-check of a single formula — read the code directly instead of running the full pipeline

无数值算术运算或单位转换的代码库——没有可标注的内容
仅包含纯整数计数逻辑（循环索引、数组长度）且无物理或金融量纲的代码
仅需要快速抽查单个公式时——直接阅读代码即可，无需运行完整流水线

Execution Mode

执行模式

This skill runs in one mode only:

full-auto

. This is a workflow-based skill that delegates step-specific work to specialized agents via the

Task

tool. You orchestrate the overall process, manage coverage and state persistence, and ensure that every in-scope file is processed through each step of the pipeline.

Always run the full pipeline in this order: Step 1 -> Step 2 -> Step 3 -> Step 4.
The main skill context must not perform repository-wide dimensional analysis, annotation, propagation, or bug validation itself when a dedicated subagent exists for that step.
The main skill context may inspect artifacts, manifests, and subagent outputs only as needed to route work, build prompts, persist state, and determine completion.
Any mode argument provided by the caller is ignored.
Report all results at the end in a single summary.

When you start a step, report it:

text

Starting Step: Step {n}

该Skill仅支持一种运行模式：

full-auto

。这是一个基于工作流的Skill，通过

Task

工具将特定步骤的工作委托给专门的代理。你需要协调整体流程、管理覆盖范围和状态持久化，并确保每个范围内的文件都经过流水线的每一步处理。

必须始终按以下顺序运行完整流水线：步骤1 -> 步骤2 -> 步骤3 -> 步骤4。
当存在专门的子代理负责某一步骤时，主Skill上下文不得自行执行全仓库范围的量纲分析、注释标注、传播或bug验证工作。
主Skill上下文仅可在必要时检查工件、清单和子代理输出，用于任务路由、构建提示、持久化状态和判断完成状态。
调用者提供的任何模式参数都将被忽略。
最终在一份汇总报告中呈现所有结果。

启动步骤时，需进行如下报告：

text

Starting Step: Step {n}

Scope and Coverage Guarantees

范围与覆盖保障

This skill must audit all in-scope arithmetic files, including large repositories.

In-scope files are defined by Step 1 scanner output (
```
files
```
array), across all priority tiers (CRITICAL, HIGH, MEDIUM, LOW).
If Step 1 narrows inputs for vocabulary discovery (for example, CRITICAL/HIGH only), that narrowing applies to discovery only. It never reduces annotation or validation scope.
```
arithmetic-scanner
```
persists the in-scope file manifest to
```
DIMENSIONAL_SCOPE.json
```
in the project root, and that manifest is the source of truth for Steps 2-4.
A file is considered fully covered only when all three statuses are present:
- ```
step2
```
  : anchor annotation completed (or explicit no-anchor result)
- ```
step3
```
  : propagation completed (or explicit no-propagation result)
- ```
step4
```
  : validation completed
```
dimension-discoverer
```
persists the discovered dimensional vocabulary to
```
DIMENSIONAL_UNITS.md
```
in the project root for reuse by later steps and future runs.
When a file ends in a terminal
```
BLOCKED
```
state, persist the blocking reason and retry count in
```
DIMENSIONAL_SCOPE.json
```
and reflect the same file in
```
coverage.unprocessed_files
```
.
Do not finish while any in-scope file remains unprocessed in any step.

该Skill必须审计所有范围内的算术文件，包括大型代码仓库。

范围内文件由步骤1的扫描器输出（
```
files
```
数组）定义，覆盖所有优先级层级（CRITICAL、HIGH、MEDIUM、LOW）。
如果步骤1为词汇发现缩小了输入范围（例如仅CRITICAL/HIGH优先级），该缩小仅适用于发现阶段，绝不减少注释标注或验证的范围。
```
arithmetic-scanner
```
会将范围内文件清单持久化到项目根目录的
```
DIMENSIONAL_SCOPE.json
```
中，该清单是步骤2-4的唯一可信来源。
只有当文件具备以下三种状态时，才被视为完全覆盖：
- ```
step2
```
  ：锚点注释已完成（或明确无锚点结果）
- ```
step3
```
  ：传播已完成（或明确无传播结果）
- ```
step4
```
  ：验证已完成
```
dimension-discoverer
```
会将发现的量纲词汇持久化到项目根目录的
```
DIMENSIONAL_UNITS.md
```
中，供后续步骤和未来运行复用。
当文件进入终端
```
BLOCKED
```
状态时，需在
```
DIMENSIONAL_SCOPE.json
```
中持久化阻塞原因和重试次数，并在
```
coverage.unprocessed_files
```
中同步该文件信息。
任何范围内文件在任意步骤中未处理完成时，不得结束流程。

Delegation Contract

委托协议

```
arithmetic-scanner
```
owns repository scanning, arithmetic-file prioritization, and writing
```
DIMENSIONAL_SCOPE.json
```
.
```
dimension-discoverer
```
owns dimensional vocabulary discovery, unit inference, and writing
```
DIMENSIONAL_UNITS.md
```
.
```
dimension-annotator
```
owns annotation format decisions, anchor-point edits, and comment-writing behavior.
```
dimension-propagator
```
owns propagation logic, inferred annotations, and mismatch reporting during tracing.
```
dimension-validator
```
owns bug detection, red-flag evaluation, rationalization rejection, and confirmation or refutation of propagated mismatches.
The main skill context must not substitute its own dimensional reasoning for skipped or unlaunched subagents. If a step requires specialized reasoning, launch the corresponding subagent.
Use reference files as subagent support material. Pass them to the relevant step in prompts instead of treating them as instructions for the main skill context.

```
arithmetic-scanner
```
负责代码仓库扫描、算术文件优先级划分以及写入
```
DIMENSIONAL_SCOPE.json
```
。
```
dimension-discoverer
```
负责量纲词汇发现、单位推断以及写入
```
DIMENSIONAL_UNITS.md
```
。
```
dimension-annotator
```
负责注释格式决策、锚点编辑和注释写入行为。
```
dimension-propagator
```
负责传播逻辑、推断注释以及追踪过程中的不匹配报告。
```
dimension-validator
```
负责bug检测、红标评估、合理化驳回以及确认或反驳传播过程中发现的不匹配问题。
主Skill上下文不得用自身的量纲推理替代被跳过或未启动的子代理工作。如果某步骤需要专门的推理能力，需启动对应的子代理。
将参考文件作为子代理的支持材料，在提示中传递给相关步骤，而非作为主Skill上下文的指令。

Workflow

工作流

Follow these sections in order. Do not advance until the current step satisfies its completion gate.

按以下章节顺序执行，当前步骤满足完成条件后方可推进到下一步。

Shared Orchestration Rules

通用编排规则

DIMENSIONAL_SCOPE.json

and

DIMENSIONAL_UNITS.md

live in the project root.

The main skill context verifies Step 1 artifacts but does not write either Step 1 artifact itself.
```
DIMENSIONAL_SCOPE.json.in_scope_files
```
is the source of truth for Steps 2-4. Never derive later scope from discovery-only inputs.
When a later step reaches terminal
```
BLOCKED
```
, persist the matching
```
step*_reason
```
and
```
step*_retry_count
```
fields on the file entry in
```
DIMENSIONAL_SCOPE.json
```
.

coverage.unprocessed_files

must be derived from terminal

BLOCKED

entries in

DIMENSIONAL_SCOPE.json

using

{ "path": "...", "blocked_step": "step2|step3|step4", "reason": "...", "retry_count": 1 }

A step may retry a
```
BLOCKED
```
file once with a focused prompt. If it is still
```
BLOCKED
```
, keep the documented reason and continue. Do not finalize while any file remains
```
PENDING
```
.

DIMENSIONAL_SCOPE.json

和

DIMENSIONAL_UNITS.md

存储在项目根目录。

主Skill上下文需验证步骤1的工件，但不得自行写入任何步骤1的工件。
```
DIMENSIONAL_SCOPE.json.in_scope_files
```
是步骤2-4的唯一范围来源，绝不能从仅用于发现阶段的输入推导后续范围。
当后续步骤进入终端
```
BLOCKED
```
状态时，需在
```
DIMENSIONAL_SCOPE.json
```
的文件条目上持久化对应的
```
step*_reason
```
和
```
step*_retry_count
```
字段。

coverage.unprocessed_files

必须从

DIMENSIONAL_SCOPE.json

中的终端

BLOCKED

条目派生，格式为

{ "path": "...", "blocked_step": "step2|step3|step4", "reason": "...", "retry_count": 1 }

。

步骤可针对
```
BLOCKED
```
文件使用聚焦提示重试一次。如果仍然
```
BLOCKED
```
，保留记录的原因并继续流程。不得在存在
```
PENDING
```
状态文件时结束流程。

Step 1: Vocabulary and Scope Discovery

步骤1：词汇与范围发现

If cached artifacts cannot be reused, delegate repository scanning to

arithmetic-scanner

and vocabulary discovery to

dimension-discoverer

. Do not do that step-specific analysis directly in the main skill context.

Check whether
```
DIMENSIONAL_UNITS.md
```
and
```
DIMENSIONAL_SCOPE.json
```
already exist in the project root.

If both exist, read them and confirm:

```
DIMENSIONAL_SCOPE.json.project_root
```
matches the current repo root

DIMENSIONAL_SCOPE.json

contains

in_scope_files

discoverer_focus_files

recommended_discovery_order

, and per-file

step2

step3

step4

fields

```
DIMENSIONAL_UNITS.md
```
is a usable dimensional vocabulary for this repo

If either artifact is stale, malformed, missing required structure, or clearly for another repo, discard reuse and rerun the rest of Step 1.
If both artifacts are valid, reuse them directly. If
```
in_scope_files
```
is empty, skip Steps 2-4 and produce final output with zero findings.
Otherwise use the
```
Task
```
tool to spawn the
```
arithmetic-scanner
```
agent. Its prompt must include:
- project root path
- absolute output path for
```
DIMENSIONAL_SCOPE.json
```
- instruction to write the Step 1 scope manifest to disk and return the same scope data in its report
The scanner owns Step 1 scope persistence. It must:
- identify dimensional-arithmetic files and prioritize them as usual
- write
```
DIMENSIONAL_SCOPE.json
```
  with
```
project_root
```
  ,
```
in_scope_files
```
  ,
```
discoverer_focus_files
```
  , and
```
recommended_discovery_order
```
- initialize every in-scope file with
```
step2: "PENDING"
```
  ,
```
step3: "PENDING"
```
  , and
```
step4: "PENDING"
```
- still write an empty manifest when no arithmetic files are found
- still narrow
```
discoverer_focus_files
```
  to CRITICAL/HIGH when more than 50 arithmetic files are found, while keeping all priorities in
```
in_scope_files
```
After the scanner completes, read
```
DIMENSIONAL_SCOPE.json
```
from disk and confirm it exists and contains the required Step 1 fields before continuing.
Use the
```
Task
```
tool to spawn the
```
dimension-discoverer
```
agent. Its prompt must include:
- project root path
- absolute path to
```
DIMENSIONAL_SCOPE.json
```
- absolute output path for
```
DIMENSIONAL_UNITS.md
```
- prioritized
```
discoverer_focus_files
```
  with each file's path, priority, score, and category
- ```
recommended_discovery_order
```
The discoverer owns Step 1 vocabulary persistence. It must read
```
DIMENSIONAL_SCOPE.json
```
as the Step 1 source of truth and write
```
DIMENSIONAL_UNITS.md
```
with
```
Base Units
```
,
```
Derived Units
```
, and
```
Precision Prefixes
```
sections. If
```
in_scope_files
```
is empty, it must still write the same headings with empty sections.
Step 1 is complete only when both artifacts exist on disk, pass the reuse checks above, and correctly represent the zero-file case. If
```
in_scope_files
```
is empty after the discoverer writes
```
DIMENSIONAL_UNITS.md
```
, skip Steps 2-4 and produce final output with zero findings.

如果无法复用缓存工件，将仓库扫描工作委托给

arithmetic-scanner

，词汇发现工作委托给

dimension-discoverer

。主Skill上下文不得直接执行该步骤的特定分析工作。

检查项目根目录是否已存在

DIMENSIONAL_UNITS.md

和

DIMENSIONAL_SCOPE.json

。

如果两者都存在，读取并确认：
- ```
DIMENSIONAL_SCOPE.json.project_root
```
  与当前代码仓库根目录匹配
- ```
DIMENSIONAL_SCOPE.json
```
  包含
```
in_scope_files
```
  、
```
discoverer_focus_files
```
  、
```
recommended_discovery_order
```
  以及每个文件的
```
step2
```
  、
```
step3
```
  、
```
step4
```
  字段
- ```
DIMENSIONAL_UNITS.md
```
  是适用于当前仓库的可用量纲词汇表
如果任一工件已过期、格式错误、缺少必要结构，或明显属于其他仓库，放弃复用并重新执行步骤1的剩余部分。
如果两个工件均有效，直接复用。如果
```
in_scope_files
```
为空，跳过步骤2-4并生成零发现的最终输出。
否则使用
```
Task
```
工具启动
```
arithmetic-scanner
```
代理，其提示必须包含：
- 项目根目录路径
- ```
DIMENSIONAL_SCOPE.json
```
  的绝对输出路径
- 将步骤1范围清单写入磁盘并在报告中返回相同范围数据的指令
扫描器负责步骤1的范围持久化，必须：
- 识别量纲算术文件并按常规划分优先级
- 写入包含
```
project_root
```
  、
```
in_scope_files
```
  、
```
discoverer_focus_files
```
  和
```
recommended_discovery_order
```
  的
```
DIMENSIONAL_SCOPE.json
```
- 为每个范围内文件初始化
```
step2: "PENDING"
```
  、
```
step3: "PENDING"
```
  和
```
step4: "PENDING"
```
  状态
- 即使未找到算术文件，仍需写入空清单
- 当算术文件超过50个时，仍需将
```
discoverer_focus_files
```
  缩小到CRITICAL/HIGH优先级，同时保留所有优先级文件在
```
in_scope_files
```
  中
扫描器完成后，从磁盘读取
```
DIMENSIONAL_SCOPE.json
```
，确认其存在且包含步骤1所需字段后再继续。
使用
```
Task
```
工具启动
```
dimension-discoverer
```
代理，其提示必须包含：
- 项目根目录路径
- ```
DIMENSIONAL_SCOPE.json
```
  的绝对路径
- ```
DIMENSIONAL_UNITS.md
```
  的绝对输出路径
- 带优先级的
```
discoverer_focus_files
```
  ，包含每个文件的路径、优先级、分数和类别
- ```
recommended_discovery_order
```
发现器负责步骤1的词汇持久化，必须读取
```
DIMENSIONAL_SCOPE.json
```
作为步骤1的可信来源，并写入包含
```
Base Units
```
、
```
Derived Units
```
和
```
Precision Prefixes
```
章节的
```
DIMENSIONAL_UNITS.md
```
。如果
```
in_scope_files
```
为空，仍需写入相同标题的空章节。
只有当两个工件都存在于磁盘上、通过复用检查，且正确表示零文件情况时，步骤1才算完成。如果发现器写入
```
DIMENSIONAL_UNITS.md
```
后
```
in_scope_files
```
为空，跳过步骤2-4并生成零发现的最终输出。

Step 2: Anchor Annotation

步骤2：锚点注释标注

The main skill context must not add annotations itself. Use the

Task

tool to spawn

dimension-annotator

agents for all anchor-point annotation work. For full examples and annotation format details, see

[{baseDir}/references/annotate.md]({baseDir}/references/annotate.md)

Read
```
DIMENSIONAL_SCOPE.json
```
and build batches from
```
in_scope_files
```
. Every in-scope file, including MEDIUM and LOW priority files, must receive a Step 2 outcome.
Batch files instead of spawning one agent per file:
- ```
<= 10
```
  files: one batch
- ```
11-30
```
  files: one batch per category
- ```
> 30
```
  files: one batch per category, splitting categories larger than 10 files into sub-batches of about 8 files
Launch categories in Step 1 recommended discovery order: math libraries, then oracles, then core logic, then peripheral. Batches inside the same category may run in parallel.
Before launching annotators, set
```
step2 = "PENDING"
```
for every in-scope file and persist the updated
```
DIMENSIONAL_SCOPE.json
```
.
Each annotator prompt must include:
- absolute path to
```
DIMENSIONAL_UNITS.md
```
- absolute path to
```
DIMENSIONAL_SCOPE.json
```
- assigned file paths in order
- each file's category and matched patterns from scanner output
- summary of previously annotated interfaces or types from earlier batches, when applicable
- required per-file status output:
```
ANNOTATED
```
  ,
```
REVIEWED_NO_ANCHOR_CHANGES
```
  , or
```
BLOCKED
```
  plus a one-line justification
After each batch, immediately persist each assigned file to exactly one Step 2 status:
- ```
ANNOTATED
```
- ```
REVIEWED_NO_ANCHOR_CHANGES
```
- ```
BLOCKED
```
If a file is
```
BLOCKED
```
, also persist
```
step2_reason
```
and
```
step2_retry_count
```
. Retry each
```
BLOCKED
```
file once with a focused prompt.
Do not continue to Step 3 while any file remains
```
PENDING
```
in on-disk manifest state.

主Skill上下文不得自行添加注释。使用

Task

工具启动

dimension-annotator

代理完成所有锚点注释标注工作。有关完整示例和注释格式详情，请参阅

[{baseDir}/references/annotate.md]({baseDir}/references/annotate.md)

。

读取
```
DIMENSIONAL_SCOPE.json
```
并从
```
in_scope_files
```
构建批量任务。所有范围内文件（包括MEDIUM和LOW优先级）都必须获得步骤2的结果。
批量处理文件，而非为每个文件启动一个代理：
- ```
<= 10
```
  个文件：一个批次
- ```
11-30
```
  个文件：按类别分批次
- ```
> 30
```
  个文件：按类别分批次，将超过10个文件的类别拆分为约8个文件的子批次
按步骤1推荐的发现顺序启动类别处理：先处理数学库，再处理预言机，然后是核心逻辑，最后是外围代码。同一类别内的批次可并行运行。
启动注释器前，为每个范围内文件设置
```
step2 = "PENDING"
```
并持久化更新后的
```
DIMENSIONAL_SCOPE.json
```
。
每个注释器的提示必须包含：
- ```
DIMENSIONAL_UNITS.md
```
  的绝对路径
- ```
DIMENSIONAL_SCOPE.json
```
  的绝对路径
- 按顺序分配的文件路径
- 每个文件的类别和扫描器输出中的匹配模式
- 若适用，早期批次中已标注的接口或类型的摘要
- 要求的每个文件状态输出：
```
ANNOTATED
```
  、
```
REVIEWED_NO_ANCHOR_CHANGES
```
  或
```
BLOCKED
```
  加一行理由说明
每个批次完成后，立即为每个分配的文件持久化唯一的步骤2状态：
- ```
ANNOTATED
```
- ```
REVIEWED_NO_ANCHOR_CHANGES
```
- ```
BLOCKED
```
如果文件状态为
```
BLOCKED
```
，同时持久化
```
step2_reason
```
和
```
step2_retry_count
```
。对每个
```
BLOCKED
```
文件使用聚焦提示重试一次。
当磁盘清单中存在
```
PENDING
```
状态文件时，不得推进到步骤3。

Step 3: Dimension Propagation

步骤3：量纲传播

The main skill context must not perform propagation reasoning itself. Use the

Task

tool to spawn

dimension-propagator

agents to extend annotations through arithmetic, function calls, and assignments. For algebra details, see

[{baseDir}/references/dimension-algebra.md]({baseDir}/references/dimension-algebra.md)

Read
```
DIMENSIONAL_SCOPE.json
```
and build propagation batches from
```
in_scope_files
```
. Every in-scope file must receive a Step 3 outcome.
Use the same batching rules and category ordering as Step 2.
Before launching propagators, confirm every file already has a non-pending Step 2 status.
Then set
```
step3 = "PENDING"
```
for every in-scope file and persist the updated manifest.
Each propagator prompt must include:
- absolute path to
```
DIMENSIONAL_UNITS.md
```
- absolute path to
```
DIMENSIONAL_SCOPE.json
```
- assigned file paths in order
- each file's category and matched patterns
- summary of Step 2 anchor annotations for the assigned files and any upstream interfaces they depend on
- required per-file status output:
```
PROPAGATED
```
  ,
```
REVIEWED_NO_PROPAGATION_CHANGES
```
  , or
```
BLOCKED
```
  plus a one-line justification
After each batch, immediately persist each assigned file to exactly one Step 3 status:
- ```
PROPAGATED
```
- ```
REVIEWED_NO_PROPAGATION_CHANGES
```
- ```
BLOCKED
```
If a file is
```
BLOCKED
```
, also persist
```
step3_reason
```
and
```
step3_retry_count
```
. Retry each
```
BLOCKED
```
file once with a focused prompt.
After all propagators complete, aggregate:
- annotations added by confidence level (
```
CERTAIN
```
  ,
```
INFERRED
```
  ,
```
UNCERTAIN
```
  )
- mismatches found, with severities for validator deduplication
- coverage gaps that could not be inferred
Do not continue to Step 4 while any file remains
```
PENDING
```
in on-disk manifest state.

主Skill上下文不得自行执行传播推理。使用

Task

工具启动

dimension-propagator

代理，通过算术运算、函数调用和赋值扩展注释。有关代数详情，请参阅

[{baseDir}/references/dimension-algebra.md]({baseDir}/references/dimension-algebra.md)

。

读取
```
DIMENSIONAL_SCOPE.json
```
并从
```
in_scope_files
```
构建传播批量任务。所有范围内文件都必须获得步骤3的结果。
使用与步骤2相同的批量规则和类别顺序。
启动传播器前，确认每个文件已具备非
```
PENDING
```
的步骤2状态。
然后为每个范围内文件设置
```
step3 = "PENDING"
```
并持久化更新后的清单。
每个传播器的提示必须包含：
- ```
DIMENSIONAL_UNITS.md
```
  的绝对路径
- ```
DIMENSIONAL_SCOPE.json
```
  的绝对路径
- 按顺序分配的文件路径
- 每个文件的类别和匹配模式
- 分配文件及其依赖的上游接口的步骤2锚点注释摘要
- 要求的每个文件状态输出：
```
PROPAGATED
```
  、
```
REVIEWED_NO_PROPAGATION_CHANGES
```
  或
```
BLOCKED
```
  加一行理由说明
每个批次完成后，立即为每个分配的文件持久化唯一的步骤3状态：
- ```
PROPAGATED
```
- ```
REVIEWED_NO_PROPAGATION_CHANGES
```
- ```
BLOCKED
```
如果文件状态为
```
BLOCKED
```
，同时持久化
```
step3_reason
```
和
```
step3_retry_count
```
。对每个
```
BLOCKED
```
文件使用聚焦提示重试一次。
所有传播器完成后，汇总：
- 按置信度级别（
```
CERTAIN
```
  、
```
INFERRED
```
  、
```
UNCERTAIN
```
  ）分类的新增注释
- 发现的不匹配问题，附带供验证器去重的严重级别
- 无法推断的覆盖缺口
当磁盘清单中存在
```
PENDING
```
状态文件时，不得推进到步骤4。

Step 4: Bug Detection

步骤4：Bug检测

The main skill context must not perform bug detection itself. Use the

Task

tool to spawn

dimension-validator

agents to detect dimensional bugs in annotated code. For examples, red flags, rationalization checks, and standard vocabulary, see

[{baseDir}/references/bug-patterns.md]({baseDir}/references/bug-patterns.md)

[{baseDir}/references/common-dimensions.md]({baseDir}/references/common-dimensions.md)

, and

[{baseDir}/references/dimension-algebra.md]({baseDir}/references/dimension-algebra.md)

. DO NOT DETECT BUGS IN ANY OTHER STEP.

Validate every file in
```
DIMENSIONAL_SCOPE.json.in_scope_files
```
.
Use this priority order without skipping lower tiers:
1. files with CRITICAL or HIGH Step 3 mismatches
2. remaining CRITICAL and HIGH scanner-priority files
3. remaining MEDIUM and LOW files
Before launching validators, confirm every file already has a non-pending Step 3 status.
Then set
```
step4 = "PENDING"
```
for every in-scope file and persist the updated manifest.
Spawn one
```
dimension-validator
```
agent per file. For large repos, run them in waves of roughly 10-30 files to keep orchestration stable.
Each validator prompt must include:
- absolute path to
```
DIMENSIONAL_UNITS.md
```
- absolute path to
```
DIMENSIONAL_SCOPE.json
```
- the single file path to validate
- a summary of anchor and propagated annotations in the file
- Step 3 mismatch summaries for the file, including mismatch IDs
- cross-file function signatures or return dimensions needed for call-boundary checks
- required per-file status output:
```
VALIDATED
```
  or
```
BLOCKED
```
After each wave, immediately persist each file to exactly one Step 4 status:
- ```
VALIDATED
```
- ```
BLOCKED
```
If a file is
```
BLOCKED
```
, also persist
```
step4_reason
```
and
```
step4_retry_count
```
. Retry each
```
BLOCKED
```
file once with a focused prompt.
Deduplicate findings:
- confirmed Step 3 mismatches keep their original IDs and severities
- refuted Step 3 mismatches are noted as false positives and excluded from final counts
- genuinely new findings receive new
```
DIM-XXX
```
  IDs
Aggregate confirmed findings, new findings, refuted findings, coverage summary, and final
```
coverage.unprocessed_files
```
.

Step 4 is complete only when

DIMENSIONAL_SCOPE.json.in_scope_files

contains no

step4: "PENDING"

entries.

主Skill上下文不得自行执行bug检测。使用

Task

工具启动

dimension-validator

代理，检测已标注代码中的量纲bug。有关示例、红标、合理化检查和标准词汇，请参阅

[{baseDir}/references/bug-patterns.md]({baseDir}/references/bug-patterns.md)

、

[{baseDir}/references/common-dimensions.md]({baseDir}/references/common-dimensions.md)

和

[{baseDir}/references/dimension-algebra.md]({baseDir}/references/dimension-algebra.md)

。不得在其他步骤中执行bug检测。

验证
```
DIMENSIONAL_SCOPE.json.in_scope_files
```
中的所有文件。
按以下优先级顺序处理，不得跳过低优先级层级：
1. 步骤3中发现CRITICAL或HIGH级别不匹配的文件
2. 剩余的CRITICAL和HIGH优先级扫描文件
3. 剩余的MEDIUM和LOW优先级文件
启动验证器前，确认每个文件已具备非
```
PENDING
```
的步骤3状态。
然后为每个范围内文件设置
```
step4 = "PENDING"
```
并持久化更新后的清单。
为每个文件启动一个
```
dimension-validator
```
代理。对于大型仓库，按约10-30个文件为一波次运行，以保持编排稳定性。
每个验证器的提示必须包含：
- ```
DIMENSIONAL_UNITS.md
```
  的绝对路径
- ```
DIMENSIONAL_SCOPE.json
```
  的绝对路径
- 待验证的单个文件路径
- 文件中的锚点和传播注释摘要
- 文件的步骤3不匹配摘要，包括不匹配ID
- 调用边界检查所需的跨文件函数签名或返回量纲
- 要求的每个文件状态输出：
```
VALIDATED
```
  或
```
BLOCKED
```
每波次完成后，立即为每个文件持久化唯一的步骤4状态：
- ```
VALIDATED
```
- ```
BLOCKED
```
如果文件状态为
```
BLOCKED
```
，同时持久化
```
step4_reason
```
和
```
step4_retry_count
```
。对每个
```
BLOCKED
```
文件使用聚焦提示重试一次。
对发现结果去重：
- 已确认的步骤3不匹配保留原ID和严重级别
- 被反驳的步骤3不匹配标记为误报，排除在最终计数之外
- 全新发现分配新的
```
DIM-XXX
```
  ID
汇总已确认的发现、新发现、被反驳的发现、覆盖范围摘要和最终的
```
coverage.unprocessed_files
```
。
只有当
```
DIMENSIONAL_SCOPE.json.in_scope_files
```
中不存在
```
step4: "PENDING"
```
条目时，步骤4才算完成。

Reference Documentation

参考文档

Pass these references to the relevant subagent when a step needs them:

[{baseDir}/references/dimension-algebra.md]({baseDir}/references/dimension-algebra.md)

- Propagator and validator algebra rules

[{baseDir}/references/common-dimensions.md]({baseDir}/references/common-dimensions.md)

- Validator vocabulary reference

[{baseDir}/references/bug-patterns.md]({baseDir}/references/bug-patterns.md)

- Validator bug-pattern and red-flag reference

[{baseDir}/references/annotate.md]({baseDir}/references/annotate.md)

- Annotator format and example reference

当步骤需要时，将以下参考文档传递给相关子代理：

[{baseDir}/references/dimension-algebra.md]({baseDir}/references/dimension-algebra.md)

- 传播器和验证器的代数规则

[{baseDir}/references/common-dimensions.md]({baseDir}/references/common-dimensions.md)

- 验证器词汇参考

[{baseDir}/references/bug-patterns.md]({baseDir}/references/bug-patterns.md)

- 验证器bug模式和红标参考

[{baseDir}/references/annotate.md]({baseDir}/references/annotate.md)

- 注释器格式和示例参考

Final Output

最终输出

At the end of the analysis, provide a structured summary unless some other output format has been specified:

json

{
  "mode": "full-auto",
  "project_root": "<path>",
  "vocabulary": {
    "base_units": ["..."],
    "derived_units": ["..."],
    "precision_prefixes": ["..."]
  },
  "annotations": {
    "total_added": 0,
    "by_file": {}
  },
  "findings": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "details": []
  },
  "uncertainties_resolved": 0,
  "coverage": {
    "in_scope_files": 0,
    "anchor_reviewed_files": "0/0",
    "propagation_reviewed_files": "0/0",
    "validation_reviewed_files": "0/0",
    "annotated_functions": "0/0",
    "annotated_variables": "0/0",
    "unprocessed_files": [
      {
        "path": "/path/to/repo/contracts/LegacyMath.sol",
        "blocked_step": "step3",
        "reason": "Parser could not process generated source",
        "retry_count": 1
      }
    ]
  }
}

分析结束后，除非指定了其他输出格式，否则提供结构化摘要：

json

{
  "mode": "full-auto",
  "project_root": "<path>",
  "vocabulary": {
    "base_units": ["..."],
    "derived_units": ["..."],
    "precision_prefixes": ["..."]
  },
  "annotations": {
    "total_added": 0,
    "by_file": {}
  },
  "findings": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "details": []
  },
  "uncertainties_resolved": 0,
  "coverage": {
    "in_scope_files": 0,
    "anchor_reviewed_files": "0/0",
    "propagation_reviewed_files": "0/0",
    "validation_reviewed_files": "0/0",
    "annotated_functions": "0/0",
    "annotated_variables": "0/0",
    "unprocessed_files": [
      {
        "path": "/path/to/repo/contracts/LegacyMath.sol",
        "blocked_step": "step3",
        "reason": "Parser could not process generated source",
        "retry_count": 1
      }
    ]
  }
}

Completion Checklist

完成检查清单

You are NOT done until all of these are true:

只有当以下所有条件都满足时，才算完成任务：

File Coverage Gates

文件覆盖检查项

```
DIMENSIONAL_UNITS.md
```
exists in the project root
```
DIMENSIONAL_SCOPE.json
```
exists in the project root and is the source of truth for downstream coverage
Every in-scope arithmetic file discovered in Step 1 appears in
```
DIMENSIONAL_SCOPE.json.in_scope_files
```
Every in-scope file has a non-
```
PENDING
```
Step 2 status (
```
ANNOTATED
```
,
```
REVIEWED_NO_ANCHOR_CHANGES
```
, or
```
BLOCKED
```
)

Every in-scope file has a non-

PENDING

Step 3 status (

PROPAGATED

REVIEWED_NO_PROPAGATION_CHANGES

, or

BLOCKED

)

Every in-scope file has a non-
```
PENDING
```
Step 4 status (
```
VALIDATED
```
or
```
BLOCKED
```
)
No in-scope file remains
```
PENDING
```
in any step
Any
```
BLOCKED
```
file has a documented reason in the final output
```
coverage.unprocessed_files
```
exactly matches the final set of terminal
```
BLOCKED
```
files after retries, using
```
path
```
,
```
blocked_step
```
,
```
reason
```
, and
```
retry_count
```

项目根目录存在
```
DIMENSIONAL_UNITS.md
```
项目根目录存在
```
DIMENSIONAL_SCOPE.json
```
，且是下游覆盖范围的可信来源
步骤1发现的所有范围内算术文件都出现在
```
DIMENSIONAL_SCOPE.json.in_scope_files
```
中
每个范围内文件都具备非
```
PENDING
```
的步骤2状态（
```
ANNOTATED
```
、
```
REVIEWED_NO_ANCHOR_CHANGES
```
或
```
BLOCKED
```
）
每个范围内文件都具备非
```
PENDING
```
的步骤3状态（
```
PROPAGATED
```
、
```
REVIEWED_NO_PROPAGATION_CHANGES
```
或
```
BLOCKED
```
）
每个范围内文件都具备非
```
PENDING
```
的步骤4状态（
```
VALIDATED
```
或
```
BLOCKED
```
）
没有范围内文件在任何步骤中处于
```
PENDING
```
状态
所有
```
BLOCKED
```
文件都在最终输出中记录了原因
```
coverage.unprocessed_files
```
与重试后的最终终端
```
BLOCKED
```
文件集合完全匹配，包含
```
path
```
、
```
blocked_step
```
、
```
reason
```
和
```
retry_count
```

Summary Report

汇总报告检查项

Final summary JSON/report provided
Final coverage counters match
```
DIMENSIONAL_SCOPE.json
```
List of modified files provided when edits occurred
Any dimensional mismatches or bugs found are summarized
Any remaining blocked or unprocessed files are called out with reasons

If
DIMENSIONAL_SCOPE.json
and the final report disagree, reconcile the report or continue processing until they match. Do not claim completion from agent intent alone; completion is determined by manifest coverage and final reported statuses.

提供了最终汇总JSON/报告
最终覆盖计数与
```
DIMENSIONAL_SCOPE.json
```
匹配
提供了修改文件列表（若有编辑操作）
汇总了所有发现的量纲不匹配或bug
明确指出了所有剩余的阻塞或未处理文件及其原因

如果
DIMENSIONAL_SCOPE.json
与最终报告不一致，需协调报告或继续处理直至匹配。 不得仅根据代理意图声称完成；完成状态由清单覆盖范围和最终报告的状态决定。