home / skills / arjenschwarz / agentic-coding / code-audit

code-audit skill

safe

This skill performs a parallel code audit by coordinating code-simplifier and design-critic analyses to deliver a prioritized quality report.

npx playbooks add skill arjenschwarz/agentic-coding --skill code-audit

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.0 KB

---
name: code-audit
description: >-
  Parallel code audit combining simplification and design critique analysis.
  Spawns two subagents (code-simplifier and design-critic) to independently
  review the current directory, consolidates findings into a prioritised report,
  and offers to create Transit tasks for actionable items. Use when you want a
  broad quality review of a codebase, e.g. "audit this code", "review codebase
  quality", "find improvements", "code audit".
# model: inherit
# allowed-tools: "Read,Glob,Grep,Task,Bash(ls:*)"
---

# Code Audit

Parallel codebase quality review that orchestrates the `code-simplifier` and `design-critic` skills via subagents, then consolidates and presents findings.

## Workflow

### Phase 1: Parallel Analysis

Launch two `general-purpose` subagents in parallel using the Task tool:

**Subagent A — Code Simplifier**

Prompt the subagent to use the `code-simplifier` skill (via the Skill tool) against the current working directory. Instruct it to:
- Scan source files for complexity hotspots, unnecessary abstractions, and simplification opportunities
- Return a structured list of findings, each with: file path, line range, issue summary, suggested fix, and severity (high/medium/low)

**Subagent B — Design Critic**

Prompt the subagent to use the `design-critic` skill (via the Skill tool) against the current working directory. Instruct it to:
- Review architecture, module boundaries, data flow, and design decisions visible in the code
- Return a structured list of findings, each with: scope (file/module/system), issue summary, questions to resolve, and severity (high/medium/low)

Both subagents should focus on the current working directory and respect any project conventions in CLAUDE.md.

### Phase 2: Consolidation

After both subagents complete:

1. Deduplicate overlapping findings (same file + same concern)
2. Group findings into categories:
   - **Simplification** — complexity reduction, readability
   - **Architecture** — design issues, module boundaries, abstraction problems
   - **Shared concerns** — findings flagged by both analyses
3. Sort by severity (high first), then by category

### Phase 3: Present Report

Present findings to the user in this format:

```
## Code Audit: {directory name}

### Shared Concerns
{Findings flagged by both subagents — these are highest signal}

### Architecture Issues
{Design critic findings, sorted by severity}

### Simplification Opportunities
{Code simplifier findings, sorted by severity}

### Summary
- {total} findings: {high} high, {medium} medium, {low} low
```

Each finding should include: location, description, and suggested action.

### Phase 4: Transit Tasks

After presenting the report, ask the user if they want Transit tasks created for any findings. If yes:

- Create one task per actionable finding (or group related findings into a single task)
- Use type `chore` for simplification items, `bug` for design issues that could cause problems
- Include the finding details in the task description
- Use `mcp__transit__create_task` to create tasks

Overview

This skill performs a parallel code audit by running two focused subagents—one that simplifies code and one that critiques design—and consolidates their findings into a prioritized report. It highlights shared concerns, architecture issues, and simplification opportunities, then offers to create actionable Transit tasks. Use it to get a quick, structured quality assessment of the current working directory.

How this skill works

The skill spawns two parallel subagents: a code-simplifier that scans for complexity hotspots and unnecessary abstractions, and a design-critic that inspects architecture, module boundaries, and data flow. Each subagent returns structured findings with location, summary, and severity. The skill deduplicates and groups findings into Simplification, Architecture, and Shared Concerns, sorts them by severity, and presents a clear report. Finally, it can convert selected findings into Transit tasks (chore or bug) for tracked remediation.

When to use it

Before a major refactor to identify simplification targets and architecture risks
During code review cycles to surface systemic issues beyond single PRs
When onboarding to a new codebase to get a consolidated quality snapshot
To prepare for production release by finding high-severity design or complexity problems
When creating a prioritized backlog of technical debt and maintenance work

Best practices

Run from the project root so both subagents inspect the full codebase
Provide or reference any project conventions (coding standards, CLAUDE.md) to guide analysis
Review Shared Concerns first — they represent the highest signal from both analyses
Group related findings into a single Transit task when work spans multiple files or is a single change
Prioritize high-severity items for immediate action and track medium/low as planned improvements

Example use cases

Audit a legacy Python package to identify complexity hotspots and unsafe abstractions
Assess a microservice repository to find architecture boundary violations and data flow risks
Generate a prioritized todo list of refactors and bug fixes before a release
Create tracked Transit tasks for technical debt items found across modules
Combine simplification suggestions into a single chore to improve readability and reduce LOC

FAQ

How are findings deduplicated?

The skill matches findings by location and concern, merging entries that point to the same file/issue to avoid duplicates.

What types of Transit tasks are created?

Simplification items become type 'chore' and design problems that could cause failures become type 'bug'. Tasks include the finding details and suggested actions.