AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

dimensional-analysis

Audits code for unit and decimal-scaling bugs and annotates it with dimensional comments recording the units of each value. Use when someone asks to audit or review code for unit confusion, decimals or scaling mismatches, WAD/RAY scale errors, or the wrong token's decimals; to annotate units in a codebase; or to perform a dimensional analysis of a DeFi protocol, offchain code, or other arithmetic-heavy codebase. Catches formulas that combine values carrying different units or scales.

Original source
trailofbits
License
CC-BY-SA-4.0
Pinned revision
2be6433b39e009cd2b6fd3be1895f6b1faa5af9a

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read trailofbits--dimensional-analysis at revision 2be6433b39e009cd2b6fd3be1895f6b1faa5af9a, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 9

references/step1.md

Phase 1: Vocabulary Discovery

First, check for existing vocabulary by looking for DIMENSIONAL_UNITS.md in the project root.

If DIMENSIONAL_UNITS.md exists:

  1. Read the file and parse the vocabulary.
  2. Use the vocabulary directly, but still run Step 1a and Step 1a.5 to establish the full current scope manifest. Existing vocabulary does not prove scope coverage.
  3. Skip only Step 1b (vocabulary discovery), then continue to Phase 2 after the full scope is persisted. If the scanner finds no arithmetic files, use the zero-file termination path below.

If no existing vocabulary file, run Step 1a, Step 1a.5, then Step 1b.

Step 1a: Scope Discovery

Spawn the dimensional-analysis:arithmetic-scanner agent to pre-scan the repository and identify files containing dimensional arithmetic.

The scanner will:

  1. Inventory all source files (excluding tests, dependencies, scripts, mocks).
  2. Pattern-match for precision constants, scaling operations, oracle calls, and conversion functions.
  3. Score and categorize each file by dimensional arithmetic density.
  4. Return a prioritized file list with recommended discovery order.

Handle edge cases from the scanner output:

  • No files found (empty files array): terminate and output a summary with zero findings.
  • Fewer than 3 files: skip prioritization and pass all files directly to the discoverer.
  • More than 50 files with arithmetic: focus the discoverer (Step 1b) on CRITICAL + HIGH priority files only, but keep all priorities in scope for Phases 2-4.

Step 1a.5: Persist Full Scope Manifest (Required)

Immediately persist scanner results to DIMENSIONAL_SCOPE.json in the project root. This file is the source of truth for downstream phases and prevents large file lists from being dropped from context.

DIMENSIONAL_SCOPE.json must include:

  1. in_scope_files — all files from scanner files output, across CRITICAL/HIGH/MEDIUM/LOW. Each entry includes path, priority, score, category, patterns_found (copied from scanner output), and phase statuses.
  2. discoverer_focus_files — the subset used by Step 1b (all files unless the >50 edge-case applies, in which case CRITICAL/HIGH only).
  3. recommended_discovery_order — copied from scanner output.
  4. Per-file phase status initialized to pending:
    • phase2: "PENDING"
    • phase3: "PENDING"
    • phase4: "PENDING"

Example:

{
  "project_root": "/path/to/repo",
  "in_scope_files": [
    {
      "path": "/path/to/repo/contracts/Vault.sol",
      "priority": "CRITICAL",
      "score": 28,
      "category": "core-logic",
      "patterns_found": {
        "high_signal": ["1e18", "mulDiv"],
        "medium_signal": ["convertToShares"]
      },
      "phase2": "PENDING",
      "phase3": "PENDING",
      "phase4": "PENDING"
    }
  ],
  "discoverer_focus_files": [
    "/path/to/repo/contracts/Vault.sol"
  ],
  "recommended_discovery_order": [
    {
      "phase": 1,
      "rationale": "Math libraries define precision constants",
      "files": ["/path/to/repo/contracts/lib/MathLib.sol"]
    }
  ]
}

Step 1b: Vocabulary Discovery

Spawn the dimensional-analysis:dimension-discoverer agent. Include the following in its prompt:

  1. Path to DIMENSIONAL_SCOPE.json — so the discoverer can read the persisted manifest.
  2. Prioritized file list — each file's path, priority tier (CRITICAL/HIGH/MEDIUM/LOW), score, and category (math-library, oracle-integration, conversion, core-logic, peripheral) from discoverer_focus_files.
  3. Project root path — so the agent can resolve file paths.
  4. Recommended discovery order — the phase ordering from the scanner (math libraries → oracles → core logic → peripheral).

If the scanner returned more than 50 files, include only CRITICAL and HIGH priority files (per the edge case rule in Step 1a).

The agent will:

  1. Extract existing D18{...} / D27{...} annotations.
  2. Infer dimensions from naming conventions (*Balance -> {tok}, *Shares -> {share}).
  3. Match known protocol patterns (ERC4626, AMM, lending, staking, Anchor, CosmWasm, etc.).
  4. Identify protocol-specific units.

The scoped file list helps the discoverer focus on the most dimensionally-rich files first, following the recommended discovery order for maximum vocabulary coverage. This discovery scope optimization does not change Phases 2-4 scope, which always uses all in_scope_files.

Persist Vocabulary

Write the approved/discovered vocabulary to DIMENSIONAL_UNITS.md in the project root:

# Dimensional Units

This file defines the dimensional vocabulary for this codebase.
Generated by dimensional-analysis plugin.

## Base Units
- `{tok}` - Token amounts
- `{share}` - Share amounts
...

## Derived Units
- `{tok/share}` - Asset per share ratio
- `{UoA/tok}` - Token price
...

## Precision Prefixes
- `D6` - 6 decimal precision
- `D8` - 8 decimal precision
...

This allows future runs to skip vocabulary discovery.

Step Completion and Next Workflow File