Edge Auditor

Systematic edge case discovery and verification. Finds what the tests missed.

Important

• NEVER write files into the project being audited. Tests, reports, and captured output all live under ~/.claude/edge-audits/<project>-<timestamp>/. This rule is non-negotiable — the audited repo must stay clean (git status unchanged after a run).
• Take your time with each phase. Thoroughness is more important than speed.
• Do not skip the test-writing step. Every P0/P1 finding must have a test that proves it (Python) or an embedded test stub in the report (other languages).
• Use the risk scoring framework from references/risk-scoring.md for every finding.
• Consult references/edge-case-catalog.md as a checklist during analysis — do not rely solely on intuition.
• Never modify production code. Write tests only. Flag fixes in the report for the user to implement.
• Launch research subagents in parallel when exploring independent modules.

Instructions

Step 1: Scope and Research

1. If $ARGUMENTS is provided, use it to narrow the audit scope (e.g., a specific module, file, or feature area). Otherwise, audit the entire project.
2. Read the project's CLAUDE.md, README.md, or equivalent to understand architecture, key files, and domain.
3. Use the Explore agent to map the codebase structure:
   • Identify all source modules and their responsibilities
   • Find existing test files and assess coverage gaps
   • Locate configuration, entry points, and external integrations
4. Read key source files to understand the data flow, state management, and error handling patterns.
5. Produce a brief Scope Summary: what is being audited, what is excluded, and why.

Step 2: Identify High-Risk Areas

Analyze the codebase for structural risk indicators. Prioritize areas with:

• External boundaries: API calls, file I/O, user input parsing, network operations
• State mutations: Anything that modifies shared state, databases, files, or caches
• Arithmetic: Financial calculations, aggregations, averages, percentages
• Type conversions: String-to-number, JSON parsing, serialization/deserialization
• Conditional logic: Complex if/else trees, boolean combinations, early returns
• Loop boundaries: Iteration over collections, pagination, retry loops
• Error handling: Bare excepts, swallowed errors, missing finally blocks
• Configuration: Default values, environment variable parsing, missing keys
• Concurrency: Shared resources, race conditions, timeout handling

Produce a Risk Map: a ranked list of modules/functions from highest to lowest risk, with 1-line justification for each.

Step 3: Enumerate Edge Cases

For each high-risk area identified in Step 2:

1. Open references/edge-case-catalog.md and systematically check every relevant category against the code.
2. For each potential edge case found:
   • Describe the specific scenario (not generic — reference actual variable names, functions, and line numbers)
   • Assess whether existing code handles it (guard clause, try/except, validation, etc.)
   • If unhandled, score it using references/risk-scoring.md (Severity x Likelihood = Risk Score)
3. Group findings by module/file for readability.

Step 4: Set Up Scratch Directory and Write Tests

NEVER write files into the project being audited. All artifacts live under ~/.claude/edge-audits/.

1. Resolve the project root and create a per-run scratch directory. Run this before writing any tests or the report:

   PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
   PROJECT_SLUG="$(basename "$PROJECT_ROOT" | tr '[:upper:] _' '[:lower:]--')"
   AUDIT_DIR="$HOME/.claude/edge-audits/${PROJECT_SLUG}-$(date +%Y%m%d-%H%M%S)"
   mkdir -p "$AUDIT_DIR/tests"
   echo "$AUDIT_DIR"

   Remember $AUDIT_DIR and $PROJECT_ROOT for the rest of the run.
2. Python projects only: For every P0/P1 finding, write a focused test named test_[function]_[edge_case] into $AUDIT_DIR/tests/test_edge_audit.py. The file MUST start with a sys.path injection so it can import the project from outside the repo — substitute the literal absolute value of $PROJECT_ROOT (not the shell variable name, not a placeholder):

   import sys
   sys.path.insert(0, "/absolute/path/to/project")  # <-- literal $PROJECT_ROOT

   Each test should set up the edge case input, call the function under test, and assert the current (possibly broken) behavior — document the correct behavior in a comment.
3. Python projects only: Run the suite from outside the repo, capturing output to the scratch dir:

   PYTHONPATH="$PROJECT_ROOT" python -m pytest \
     "$AUDIT_DIR/tests/test_edge_audit.py" -v \
     2>&1 | tee "$AUDIT_DIR/pytest-output.txt"

   Record which tests pass (already handled) and which fail (confirmed bug). If a test unexpectedly passes, re-examine — either the case was already handled or the test is wrong.
4. Non-Python projects (JS/TS, Go, Rust, Java, etc.): Do NOT write a runnable test file anywhere — running it would require touching the repo or its toolchain config. Instead, embed each P0/P1 test as a fenced code block in the report's ## Suggested Tests section (see Step 5). Mark these findings as "unverified — manual run required" in the report. This is a deliberate tradeoff to honor the no-repo-writes rule.

For P2/P3 findings, skip test writing entirely; document them in the report.

Step 5: Generate Report

Write the report to $AUDIT_DIR/EDGE-AUDIT-REPORT.md. NEVER write it to the project being audited.

# Edge Audit Report

**Project**: [name]
**Audit directory**: [absolute $AUDIT_DIR]
**Date**: [date]
**Scope**: [what was audited]
**Auditor**: Claude Code (edge-auditor skill)

## Executive Summary

- **Total findings**: [N]
- **P0 (Critical)**: [N] — [1-line summary of worst finding]
- **P1 (High)**: [N]
- **P2 (Medium)**: [N]
- **P3 (Low)**: [N]
- **Tests written**: [N] | **Passing**: [N] | **Failing (confirmed bugs)**: [N]

## Risk Map

[Ranked list of modules from Step 2]

## Findings

### P0 — Critical

[Each finding using the format from references/risk-scoring.md]

### P1 — High

[...]

### P2 — Medium

[...]

### P3 — Low/Info

[...]

## Test Results

[pytest output or summary table — or "unverified — manual run required" for non-Python projects]

## Suggested Tests

[For non-Python projects: embedded fenced code blocks for each P0/P1 finding
that the user can paste into their own test suite. Omit this section for
Python projects where tests were actually executed.]

## Recommendations

[Top 3-5 prioritized actions to improve robustness]

Print the executive summary inline to the user. Always print the absolute path of $AUDIT_DIR so the user can open the full report and any captured test output. Do not ask whether to save to file — the file is the deliverable and already lives in the scratch directory.

Error Handling

1. No test framework installed: Check for pytest in the active Python environment before writing tests. If missing, note in report and write tests anyway (user can install later). Do not install dependencies without asking.
2. Tests fail to import: If test imports fail due to project structure, adjust the sys.path.insert line at the top of $AUDIT_DIR/tests/test_edge_audit.py (e.g. add a src/ subdirectory) and document the workaround in the test file header.
3. Scope too large: If the project has 50+ source files, focus on the top 10 highest-risk modules. Note excluded modules in the Scope Summary.
4. No existing tests: Flag this as a P1 finding itself ("no test coverage"). Still write edge case tests.
5. Read-only or generated files: Skip generated code (protobuf, migrations, etc.) — note exclusion in scope.
6. Non-writable ~/.claude/edge-audits/: If the scratch directory cannot be created (permissions, full disk), fall back to $TMPDIR/edge-audits/ and warn the user in the inline summary. NEVER fall back to writing inside the project being audited.
7. Pytest config does not apply: Running pytest from outside the repo means project-level conftest.py, pyproject.toml [tool.pytest.ini_options], and fixtures are not picked up. Keep edge case tests self-contained (no fixture dependencies). If a test needs project fixtures, document it in the report's Suggested Tests section instead of running it.

Examples

Example 1: Audit a financial calculation module (Python)

Input: /code-edges risk management module

Output: Researches risk.py, finds daily loss calculation uses float arithmetic (P0), inventory limits don't account for partial fills (P1), circuit breaker has no test for exactly-at-limit (P2). Writes 5 tests to ~/.claude/edge-audits/myproject-20260101-120000/tests/test_edge_audit.py, 2 fail. Report at ~/.claude/edge-audits/myproject-20260101-120000/EDGE-AUDIT-REPORT.md. Prints executive summary inline with the audit directory path. git status in the audited repo is unchanged.

Example 2: Full project audit (Python)

Input: /code-edges

Output: Scans all modules, identifies API client as highest risk (external boundary + error handling). Finds unhandled 429 rate limit response (P0), JSON parse on empty body (P1), missing timeout on REST calls (P1). Writes 8 tests to ~/.claude/edge-audits/<project>-<timestamp>/tests/test_edge_audit.py, 3 fail. Report with 15 total findings at ~/.claude/edge-audits/<project>-<timestamp>/EDGE-AUDIT-REPORT.md.

Example 3: Scope narrowing (Python)

Input: /code-edges config parsing

Output: Focuses on config.py. Finds missing env var raises KeyError instead of helpful message (P1), boolean config parsed as string (P2), default values shadow env vars (P3). Writes 3 tests to the scratch directory. Report saved outside the repo.

Example 4: Non-Python project (TypeScript)

Input: /code-edges auth middleware

Output: Researches src/middleware/auth.ts. Finds JWT verification allows alg:none (P0), token expiry check uses <= instead of < (P1). Does NOT write any runnable test files anywhere. Embeds both test cases as fenced ts code blocks in the report's ## Suggested Tests section at ~/.claude/edge-audits/<project>-<timestamp>/EDGE-AUDIT-REPORT.md. Inline summary flags findings as "unverified — manual run required" and prints the report path. Repo is untouched.