/dimensional-analysis

name: dimensional-analysis
description: "Annotates codebases with dimensional analysis comments documenting units, dimensions, and decimal scaling. Use when someone asks to annotate units in a codebase, perform a dimensional analysis, or find vulnerabilities in a DeFi protocol, offchain code, or other blockchain-related codebase with arithmetic. Prevents dimensional mismatches and catches formula bugs early."
allowed-tools: Read Write Grep List Glob Task TodoRead TodoWrite

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 `dimensio