Estimator

---
name: estimator
description: Conducting project scoping and estimation using logical chunking and metric analysis. Use when the user wants to estimate audit effort, scope a codebase for review, calculate hours for a security engagement, or assess the size of a diff or full repository.
argument-hint: "<scope file or glob>"
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---

# Estimator

<workflow>
SEQUENCE:
1. DISCOVERY (required, always first)
2. CHECKPOINT: user confirms "full-scope" or "diff-scope"
3. IF full-scope: EXPLORE (per-chunk) → METRICS → REFLECT → REPORT
   IF diff-scope: DIFF-TRIAGE (per-chunk) → REFLECT → REPORT

CHECKPOINT RULES:
- Present findings using the phase's specified output format
- Ask the checkpoint question explicitly
- STOP and wait for user response before proceeding
- If you analyze multiple chunks without confirmation, STOP and return to last checkpoint
</workflow>

---

## CLI Binary

This skill requires the `auditor-addon-cli` skill for the `aud` binary. Before running any `aud` command, load that skill to determine the correct binary path.

---

<reference_definitions>
## Reference: Categories & Scope

<file_categories>
### File Categories

| Category | Description |
|----------|-------------|
| `business-logic` | Core functionality, value transfer, state changes |
| `infra/glue` | Configuration, interfaces, utilities |
| `presentation` | UI code |
| `tests` | Test files |
| `generated` | Auto-generated bindings |
| `scripts` | Deployment, migration, build scripts |

**Distinguishing business-logic from infra/glue:**
- Affects state transitions, value flows, or protocol invariants → `business-logic`
- Only routes requests, configures settings, or adapts interfaces → `infra/glue`
- Access control that enforces permissions → `business-logic`
- Access control that merely forwards to another module → `infra/glue`
- When uncertain, default to `business-logic` (err toward inclusion)
</file_categories>

<scope_defaults>
### Scope Defaults

| Category | Default Scope | Notes |
|----------|---------------|-------|
| `business-logic` | **in-scope** | Always include |
| `tests` | **out-of-scope** | Unless explicitly requested |
| `generated` | **out-of-scope** | Nothing to audit |
| `scripts` | **out-of-scope** | EXCEPT deployment/initialization scripts → trigger Concern Question |
| `infra/glue` | **Concern Question** | If unclear |
| `presentation` | **Concern Question** | If unclear |
| Deleted files (diff) | **out-of-scope** | Nothing to audit |
</scope_defaults>

<external_dependencies>
### External Dependencies

- Imported libraries (OpenZeppelin, Solmate, Express, gRPC, etc.) → **out-of-scope** by default
- External calls (contract calls, oracles, third-party APIs, message queues) → flag for **Concern Question**
- If in-scope code wraps, extends, or modifies a dependency → ask whether the dependency interaction needs review
</external_dependencies>
</reference_definitions>

<concern_questions>
## Reference: Concern Questions

**Purpose:** When uncertain whether something belongs in scope, ask the user rather than guessing. You lack domain context; the user knows which areas are critical.

**Format:** Frame questions around user priorities, not technical details:
- "Are you concerned that the fee calculation in `Pool.sol` / `BillingService.ts` is correct?"
- "Should the migration scripts be reviewed for data integrity issues?"
- "The access control logic in `Admin.sol` / `AuthMiddleware.go` was modified—is this a critical path?"

**When to use:**
- Files/changes where scope relevance is ambiguous
- Areas that could be important but might also be out of scope
- Anything you would otherwise have to guess about
</concern_questions>

<estimation_baseline>
## Reference: Estimation Baseline

All hour estimates assume a senior auditor who is:
- Proficient in the target language
- Has domain familiarity (e.g., DeFi patterns, authentication flows, distributed systems)

Adjust expectations accordingly for junior auditors or unfamiliar domains.
</estimation_baseline>

<adjustment_reference>
## Reference: Domain Multipliers

The metrics tool accounts for structural complexity and comment density but cannot detect semantic difficulty. Apply explicit multiplier adjustments when domain factors make the work harder or easier than raw metrics suggest.

| Pattern | Typical Multiplier |
|---------|-------------------|
| Inline assembly / low-level bit ops | 1.5x – 2.5x |
| Cryptographic math (ECC, pairings, polynomial commitments, hash circuits) | 1.5x – 3.0x |
| ZK circuit logic (constraint systems, proving/verification details) | 1.5x – 3.0x |
| Dense state machines (many interconnected states, complex transitions) | 1.3x – 2.0x |
| Novel or undocumented protocol logic with no reference implementation | 1.3x – 2.0x |
| Cross-chain / oracle integration points with complex invariants | 1.2x – 1.5x |
| Boilerplate, thin wrappers, repetitive CRUD | 0.6x – 0.8x |

**Formula:** `Adjusted Hours = Tool Hours × Multiplier`

Use the midpoint for moderate cases; upper end when the pattern dominates the file. Skip adjustments smaller than 10% of a file's hours.
</adjustment_reference>

---

<phase_instructions>
## Phase Details

<discovery_instructions>
### DISCOVERY

**TRIGGER:** Start of every estimation.
**CHECKPOINT:** "Does this organization look correct? Are we doing a **full scope** or **diff scope** estimation?"

**Goal:** Discover the scope of the audit and organize files into logical chunks.

**Step 1 — Get file structure:**
- If user provided a scope file → read it
- Otherwise → use `Glob` with patterns like `**/*.sol`, `**/*.ts`, etc.

**Step 2 — Chunk files:**
- **Target size:** 5-15 files per chunk (smaller chunks enable incremental review)
- **Boundaries:** Prefer directory boundaries when cohesion is unclear
- **Cross-cutting files:** Place utilities/helpers in their own "Shared/Utils" chunk
- **Example chunks:** "Core Logic", "Token Implementation", "Auth/Permissions", "API Handlers", "Utils", "Tests", "Scripts"

**Step 3 — Identify patterns:**
For each chunk, note which path patterns are likely in-scope vs out-of-scope:
- In-scope: `src/core/**`, `contracts/**`, `services/**`
- Out-of-scope: `test/**`, `scripts/**`, `mocks/**`

**Step 4 — Present to user:**
- List each chunk with a one-liner description
- Show included files/patterns underneath
- Indicate in-scope vs out-of-scope patterns

**CHECKPOINT:** "Does this organization look correct? Are we doing a **full scope** or **diff scope** estimation?"
</discovery_instructions>

---

<explore_instructions>
### EXPLORE (Full Scope Only)

**TRIGGER:** User confirms full-scope estimation after DISCOVERY.
**CONSTRAINT:** Process ONE chunk at a time. STOP after each chunk and WAIT for confirmation.
**CHECKPOINT:** "Do you agree with this scope? Proceed to next chunk?"
**NEXT:** After final chunk confirmed → METRICS.

**Goal:** For each chunk, categorize files and determine audit relevance.

**Per-Chunk Steps:**

**Step 1 — Prepare:**
- Identify files in the chunk
- **Batch `aud peek` calls** for ambiguous files
- **Skip `aud peek`** when path makes category obvious (e.g., `tests/`, `*_test.*`, `generated/`)

**Step 2 — Categorize:**
- Assign each file a category (see File Categories reference)
- If `aud peek` is insufficient, read up to 200 lines to categorize

**Step 3 — Determine Scope:**
- Apply scope defaults (see Scope Defaults reference)
- Use Concern Questions when unclear

**Step 4 — Report:**
Present summary table:
| File | Category | Scope |
|------|----------|-------|

Include:
- Brief chunk summary
- Any adjustments with justification
- Concern Questions for unclear scope

**CHECKPOINT:** "Do you agree with this scope? Proceed to next chunk?"
</explore_instructions>

---

<metrics_instructions>
### METRICS (Full Scope Only)

**TRIGGER:** All chunks explored and scope confirmed.
**NEXT:** REFLECT.

**Goal:** Calculate metrics and estimate audit effort for all confirmed in-scope files.

**Step 1 — Calculate:**
- Run `aud metrics` with all confirmed in-scope paths

**Step 2 — Analyze:**
- Review NLoC, Comment Density, Cognitive Complexity (CC), and Estimated Hours
- **Identify anomalies:** Flag files that stand out (unusually high complexity, sparse documentation, outlier size)

**Step 3 — Adjust:**
Apply domain multipliers where needed (see Domain Multipliers reference). Present any adjustments:
```
File: <path>
Multiplier: <Nx>
Adjusted Hours: <X hours>
Reason: <justification>
```

**NEXT:** Proceed to REFLECT.
</metrics_instructions>

---

<diff_triage_instructions>
### DIFF-TRIAGE (Diff Scope Only)

**TRIGGER:** User confirms diff-scope estimation after DISCOVERY.
**CONSTRAINT:** Process ONE chunk at a time. STOP after each chunk and WAIT for confirmation. Skip chunks with no changes.
**CHECKPOINT:** "Do you agree with this scope? Proceed to next chunk?"
**NEXT:** After final chunk confirmed → REFLECT.
</diff_triage_instructions>

**Goal:** For each chunk with changes, calculate diff metrics, classify changes, and determine audit relevance.

**Setup (once, before iterating):**
- Confirm `base` ref with user (e.g., `main`, `v1.0.0`, commit SHA)
- Confirm `head` ref (defaults to `HEAD`)

**Per-Chunk Steps:**

**Step 1 — Calculate Diff Metrics:**
- Run `aud diff-metrics <base> <head> -- <chunk-paths>` (add `--no-tests` if test code should be excluded)
- If no rows returned for the chunk → skip to next chunk
- Review `nloc_added`, `nloc_removed`, `complexity_added`, `complexity_per_100`, `comment_density`, `estimated_hours`, and `changed_functions`
- Unsupported extensions are omitted automatically; deleted files have zero effort

**Step 2 — Analyze Changes:**
- Use `git diff <base>..<head> -- <file>` for the actual diff
- Run `aud call-chains <chunk-paths>` (no `--root`) and grep the output for each name from `changed_functions` to see which entry-point chains reach the modified code
- Optionally: `aud call-chains --root=<changed-name>` to see what a changed function reaches downstream
- Use judgment: scan the diff for added/removed functions, changed logic, new entry points

**Step 3 — Classify & Adjust:**
For each changed file, determine scope and adjust estimates. Assume **no prior auditor context**.

**Scope:** Apply categories and scope defaults (see references).

**Context burden:** From the call-chains output above, assess how each changed function sits in the graph:
- *Isolated* (leaf node, minimal callers, self-contained) → no adjustment
- *Integrated* (multiple paths, shared state, affects invariants) → increase estimate
- *Escalate*: If paths are insufficient, read unchanged files to understand context surface

**Adjust:** Apply domain multipliers where needed (see Domain Multipliers reference).

**Step 4 — Report:**
Present summary table:
| File | Category | Scope | Approach | nloc_added | nloc_removed | complexity_added | comment_density | Adjusted Hours |
|------|----------|-------|----------|------------|--------------|------------------|-----------------|----------------|

- **Approach:** `full` (added files, audit entire file) or `diff` (modified files, audit changes only)

Include:
- Adjustments with justification
- Concern Questions for unclear scope

**CHECKPOINT:** "Do you agree with this scope? Proceed to next chunk?"
</diff_triage_instructions>

---

<reflect_instructions>
### REFLECT

**TRIGGER:** METRICS complete (full scope) OR all DIFF-TRIAGE chunks confirmed (diff scope).
**CHECKPOINT:** "Does this estimate look right to you? Should I adjust anything before I write the report?"
**NEXT:** User confirms → REPORT.

**Goal:** Step back from the per-file detail and assess whether the overall estimate is credible.

**Step 1 — Reflect on the full picture:**
- **Proportionality:** Does the total effort feel proportional to the complexity you observed across the codebase?
- **Hard files:** Were there files you found genuinely difficult to follow? Do their hours reflect that difficulty?
- **Depth:** Would the estimated days give an auditor enough time to probe invariants and edge cases — not just read the code?

**Step 2 — Revise or flag:**
For each concern identified, either:
- Revise the estimate on the spot with a short justification, or
- Flag it as an open question for the user to decide

**Step 3 — Present and stop:**
Summarize your reflection and any revisions. Then ask the checkpoint question and wait.
</reflect_instructions>

---

<report_instructions>
### REPORT

**TRIGGER:** User confirms after REFLECT.

Ask: "Would you like a **detailed report** or a **condensed version** (e.g. for Slack)?"

Then produce the chosen format.

---

**Detailed Report:**

**1. Headline:**
- Full scope: "Audit Estimation - <Repository Name>"
- Diff scope: "Audit Estimation - <Repository Name> (<base>...<head>)"

**2. Summary:**
- High-level overview of the repository
- Diff scope: Focus on nature of changes

**3. Chunks Overview:**
- For each chunk: brief description of purpose
- Diff scope: What changed in each chunk

**4. Detailed Table (in-scope files only):**

Full scope:
| Chunk | File Path | Category | NLoC | Comment Density | Complexity | Estimated Hours |
|-------|-----------|----------|------|-----------------|------------|-----------------|

Diff scope:
| Chunk | File Path | Category | Approach | nloc_added | nloc_removed | complexity_added | Estimated Hours |
|-------|-----------|----------|----------|------------|--------------|------------------|-----------------|

- Use adjusted estimates from METRICS (full) or DIFF-TRIAGE (diff)

**5. Adjustments Summary:**
If any adjustments were made, list them:
```
File: <path>
Multiplier: <Nx>
Adjusted Hours: <X hours>
Reason: <justification>
```

**6. Totals:**
- Full scope: Total NLoC, Total Estimated Hours, Total Estimated Days
- Diff scope: Total nloc_added, Total nloc_removed, Total Estimated Hours, Total Estimated Days

**7. Required Domain Expertise:**
- Languages and ecosystems (e.g. Solidity/EVM, Rust/Substrate)
- Protocol knowledge (e.g. AMM mechanics, lending invariants, ZK proof systems)
- Any specialised skills flagged during analysis (e.g. assembly, cryptographic primitives)

**8. Risks & Recommendations:**
- Proposed timeline and order of execution
- Highlighted concerns:
  - Diff scope: removed functions, new entry points, high-complexity changes
  - Full scope: high-risk areas, complex interactions, areas needing extra attention

---

**Condensed Report (Slack-friendly):**

Plain prose, no markdown headings or tables. Use Slack bold (`*text*`) only.

```
*[Repo] — Audit Estimation*

X days (Y hours)

[2-3 sentences: what the codebase does, what was scoped, overall complexity.]

*Challenges:* [key difficulty factors — crypto, novel protocol, missing docs, etc.]

*Required expertise:* [languages, domain knowledge, any specialist skills needed]
```
</report_instructions>
</phase_instructions>