complexity-audit

Skill: Complexity Audit

Version: 1.0.0

Status: draft

Owner: M. Williams / Security Engineering

Category: code-quality

Created: 2026-06-23

Purpose

This Skill performs a maintainability and complexity audit of a single Python module and emits a structured Markdown report of complexity hotspots. Use it when you want to find the functions most likely to harbour bugs or resist change — those that are too long, too deeply nested, take too many parameters, or carry too many responsibilities. It flags each hotspot with an approximate complexity signal, the standard it violates (e.g. CLAUDE.md's "functions ≤ 40 lines"), and a one-line refactor direction. It is a quality lens only: it does not assess security or correctness, and its metrics are heuristic estimates, not a substitute for a calibrated tool like radon or ruff.

Input

Prompt

You are a senior engineer performing a code maintainability and complexity audit.
Your job is to identify the parts of the module most likely to be hard to test,
hard to change, or bug-prone, and to quantify why.

SCOPE: {{SCOPE}} only.

FOCUS ONLY ON:
- Function length vs the project limit (default {{MAX_FUNCTION_LINES}}=40 lines per
  CLAUDE.md; use {{CONTEXT}} to confirm the standard)
- Cyclomatic-complexity signals (branches, loops, try/except, boolean operators) —
  give an APPROXIMATE count and label it approximate
- Nesting depth, parameter count, and single-responsibility violations
- Missing type hints on public functions where the standard requires them
- Dead or unreachable code, unused imports/constants

DO NOT:
- Review security (no OWASP/CWE/vulnerabilities — a Security Skill owns that)
- Write or design tests
- Rewrite the module or deliver a refactored file (one-line refactor direction only)
- Report subjective style/naming preferences not backed by a CLAUDE.md standard
- Present heuristic metrics as exact tool output — always label them approximate

You will receive: CLAUDE.md ({{CONTEXT}}) + the source at {{SCOPE}}. Treat
CLAUDE.md coding standards as the rule set.

OUTPUT FORMAT:
A single Markdown document with EXACTLY these sections. No preamble.

## Complexity Hotspots
A table, sorted worst-first:
| Function | Lines | ~Cyclomatic | Nesting | Params | Standard Violated | Refactor Direction |

## Standards Violations
Bullet list of concrete CLAUDE.md standard breaches (e.g. "missing type hints on
all public functions", "module constant unused"), each with file:line.

## Dead / Unused Code
Bullet list of unused imports, constants, or unreachable branches with file:line,
or "none found".

## SUMMARY
Two sentences: the single worst hotspot and the module's overall maintainability
posture (low / medium / high risk to change).

All metrics are approximate heuristics. No security commentary. No tests. No full code.

Output Spec

Markdown with four sections. Concrete example (fake data):

## Complexity Hotspots
| Function | Lines | ~Cyclomatic | Nesting | Params | Standard Violated | Refactor Direction |
|---|---|---|---|---|---|---|
| `sync_orders` | 78 | ~12 | 4 | 6 | >40 lines; >5 params | Extract the retry block and the mapping block into helpers. |

## Standards Violations
- `billing/sync.py:1` — no type hints on any public function (CLAUDE.md requires them).

## Dead / Unused Code
- `billing/sync.py:9` — `import json` never used.

## SUMMARY
`sync_orders` is the worst hotspot at ~78 lines and 6 parameters. The module is
medium-to-high risk to change until that function is decomposed.

Limitations

• Heuristic, not measured. Cyclomatic complexity and line counts are model estimates; for authoritative numbers run radon cc / ruff — this Skill points you at where to look, not exact scores.
• Does NOT cover security (use Security OWASP Review) or correctness/tests (use the Unit Test Generator). A complex function is not necessarily insecure or wrong.
• Single-file scope only; cannot see cross-module coupling or call-graph fan-out.
• Dead-code detection is conservative and intra-file only — code reachable only via dynamic dispatch, reflection, or other modules may be wrongly flagged or missed.
• Reliability degrades on files longer than ~500 lines — chunk and re-run.
• On empty/minimal input it reports "no hotspots / no violations" rather than inventing complexity.

Tests

Issues found / wording updates during testing: None. Scope discipline held even when the auditor encountered security-relevant lines (it reframed them as maintainability/dead-code, never as vulnerabilities). No prompt wording changes required for v1.0.0.

Changelog

v1.0.0 — 2026-06-23

• Initial release.
• Tested on: OrderFlow sample repo (payments/processor.py, payments/webhook.py, empty fixture).
• Tested by: M. Williams.