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:
- Read the file and parse the vocabulary.
- 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.
- 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:
- Inventory all source files (excluding tests, dependencies, scripts, mocks).
- Pattern-match for precision constants, scaling operations, oracle calls, and conversion functions.
- Score and categorize each file by dimensional arithmetic density.
- Return a prioritized file list with recommended discovery order.
Handle edge cases from the scanner output:
- No files found (empty
filesarray): 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:
in_scope_files— all files from scannerfilesoutput, across CRITICAL/HIGH/MEDIUM/LOW. Each entry includespath,priority,score,category,patterns_found(copied from scanner output), and phase statuses.discoverer_focus_files— the subset used by Step 1b (all files unless the >50 edge-case applies, in which case CRITICAL/HIGH only).recommended_discovery_order— copied from scanner output.- 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:
- Path to
DIMENSIONAL_SCOPE.json— so the discoverer can read the persisted manifest. - Prioritized file list — each file's path, priority tier (CRITICAL/HIGH/MEDIUM/LOW), score, and category (
math-library,oracle-integration,conversion,core-logic,peripheral) fromdiscoverer_focus_files. - Project root path — so the agent can resolve file paths.
- 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:
- Extract existing
D18{...}/D27{...}annotations. - Infer dimensions from naming conventions (
*Balance->{tok},*Shares->{share}). - Match known protocol patterns (ERC4626, AMM, lending, staking, Anchor, CosmWasm, etc.).
- 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
- If this phase terminated due to zero arithmetic files, produce final output using SKILL.md.
- Otherwise read references/step2.md next.