From auditor-addon
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.
How this skill is triggered — by the user, by Claude, or both
Slash command
/auditor-addon:estimatorThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
<workflow>
CHECKPOINT RULES:
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>
<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:
business-logicinfra/gluebusiness-logicinfra/gluebusiness-logic (err toward inclusion)
</file_categories><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>
<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:
Pool.sol / BillingService.ts is correct?"Admin.sol / AuthMiddleware.go was modified—is this a critical path?"When to use:
<estimation_baseline>
All hour estimates assume a senior auditor who is:
Adjust expectations accordingly for junior auditors or unfamiliar domains. </estimation_baseline>
<adjustment_reference>
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>
<discovery_instructions>
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:
Glob with patterns like **/*.sol, **/*.ts, etc.Step 2 — Chunk files:
Step 3 — Identify patterns: For each chunk, note which path patterns are likely in-scope vs out-of-scope:
src/core/**, contracts/**, services/**test/**, scripts/**, mocks/**Step 4 — Present to user:
CHECKPOINT: "Does this organization look correct? Are we doing a full scope or diff scope estimation?" </discovery_instructions>
<explore_instructions>
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:
aud peek calls for ambiguous filesaud peek when path makes category obvious (e.g., tests/, *_test.*, generated/)Step 2 — Categorize:
aud peek is insufficient, read up to 200 lines to categorizeStep 3 — Determine Scope:
Step 4 — Report: Present summary table:
| File | Category | Scope |
|---|
Include:
CHECKPOINT: "Do you agree with this scope? Proceed to next chunk?" </explore_instructions>
<metrics_instructions>
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:
aud metrics with all confirmed in-scope pathsStep 2 — Analyze:
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>
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):
base ref with user (e.g., main, v1.0.0, commit SHA)head ref (defaults to HEAD)Per-Chunk Steps:
Step 1 — Calculate Diff Metrics:
aud diff-metrics <base> <head> -- <chunk-paths> (add --no-tests if test code should be excluded)nloc_added, nloc_removed, complexity_added, complexity_per_100, comment_density, estimated_hours, and changed_functionsStep 2 — Analyze Changes:
git diff <base>..<head> -- <file> for the actual diffaud 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 codeaud call-chains --root=<changed-name> to see what a changed function reaches downstreamStep 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:
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 |
|---|
full (added files, audit entire file) or diff (modified files, audit changes only)Include:
CHECKPOINT: "Do you agree with this scope? Proceed to next chunk?" </diff_triage_instructions>
<reflect_instructions>
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:
Step 2 — Revise or flag: For each concern identified, either:
Step 3 — Present and stop: Summarize your reflection and any revisions. Then ask the checkpoint question and wait. </reflect_instructions>
<report_instructions>
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:
2. Summary:
3. Chunks Overview:
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 |
|---|
5. Adjustments Summary: If any adjustments were made, list them:
File: <path>
Multiplier: <Nx>
Adjusted Hours: <X hours>
Reason: <justification>
6. Totals:
7. Required Domain Expertise:
8. Risks & Recommendations:
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>
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub artifex1/auditor-addon --plugin auditor-addon