Dimensional Analysis Annotator

Dimensional Analysis 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.

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

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:

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.

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.

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.

Step 1: Vocabulary and Scope Discovery

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.

1. Check whether DIMENSIONAL_UNITS.md and DIMENSIONAL_SCOPE.json already exist in the project root.
2. 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
3. If either artifact is stale, malformed, missing required structure, or clearly for another repo, discard reuse and rerun the rest of Step 1.
4. 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.
5. 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
6. 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
7. After the scanner completes, read DIMENSIONAL_SCOPE.json from disk and confirm it exists and contains the required Step 1 fields before continuing.
8. 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
9. 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.
10. 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.

Step 2: Anchor Annotation

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.