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

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

---

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 - "
• Diff scope: "Audit Estimation - (...)"

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>