Audit Workflow Skill

Purpose: Orchestrate a project health audit using senior-reviewer + security-auditor + reviewer, aggregate into a report, then optionally route critical findings into the appropriate fix workflow — all in the same chat.

Serena MCP Protocol (Mandatory)

Before running workflow steps:

1. Call mcp__serena__check_onboarding_performed.
2. If onboarding is not performed, call mcp__serena__onboarding.
3. Use Serena semantic tools first for scope discovery: mcp__serena__get_symbols_overview and mcp__serena__find_symbol.
4. Use mcp__serena__find_referencing_symbols before renames, moves, deletions, or behavior-affecting edits.
5. Before deleting a symbol, run mcp__serena__safe_delete_symbol.
6. Prefer symbol-scoped updates via Serena tools; use broad file-level reads/edits only when symbol-level output is insufficient, and state why.

Workflow Architecture

mermaid
1flowchart TD
2    Scope[Define audit scope] --> Arch[senior-reviewer: architecture]
3    Arch --> Sec[security-auditor: security]
4    Sec --> Quality[reviewer: code quality]
5    Quality --> Aggregate[documenter: consolidated report]
6    Aggregate --> Ask{Critical issues?}
7    Ask -->|No| End[Audit complete]
8    Ask -->|Yes - user confirms| Route[Categorize by fix type]
9    Route --> Structural["Structural/Quality → refactor agent"]
10    Route --> SecFix["Security/Features → planner + worker"]
11    Structural --> Verify[test-runner: verify]
12    SecFix --> Verify
13    Verify --> UpdateDoc[documenter: update report]
14    UpdateDoc --> End

Phases 1–4 are always read-only. Phase 5 runs only with explicit user confirmation.

All analysis phases are sequential — each agent receives context from the previous one to avoid duplicate findings and add depth.

Step 1: Define Scope

Parse the user's input to determine what to audit:

/audit                        → full project (src/ or project root)
/audit src/services/          → specific directory
/audit src/auth.ts            → single file (thorough review)
/audit --since main           → only files changed vs main branch
/audit --since HEAD~10        → last 10 commits

For --since variants, run git diff --name-only [ref] to get the file list, then pass those files as scope to each agent.

If no scope given, default to the project's main source directory (check package.json, src/, app/, or ask the user if ambiguous).

Step 2: Architecture Review (senior-reviewer)

Goal: Identify structural, design, and architectural issues.

Checklist for senior-reviewer:

• SOLID principles adherence
• Layered architecture (separation of concerns, dependency direction)
• Design pattern usage (correct, missing, misapplied)
• Module boundaries and coupling
• Circular dependencies
• God classes / God modules
• Scalability concerns (stateful components, caching, bottlenecks)
• Over-engineering or premature abstraction

Expected output format:

markdown
1## Architecture Findings
2
3### Critical
4- [A1] Circular dependency: services/user.ts ↔ services/auth.ts
5
6### High
7- [A2] God module: utils/helpers.ts (850 lines, mixed concerns)
8
9### Medium
10- [A3] Missing repository pattern in services/ — direct DB calls
11
12### Low
13- [A4] Strategy pattern opportunity in pricing logic

Step 3: Security Audit (security-auditor)

Goal: Identify security vulnerabilities and risks.

Context to pass: architecture findings summary (helps auditor focus on high-risk areas like auth services, API layers).

Checklist for security-auditor:

• Authentication & authorization flows
• Input validation and sanitization (injection, XSS)
• Hardcoded secrets, tokens, credentials
• OWASP Top 10 coverage
• API endpoint security (rate limiting, CORS, method restrictions)
• Sensitive data handling and storage (PII, passwords, tokens)
• Dependency vulnerabilities (if npm audit or similar available)
• Error messages leaking internal details

Expected output format:

markdown
1## Security Findings
2
3### Critical
4- [S1] Hardcoded JWT secret in src/config/auth.ts:12
5
6### High
7- [S2] Missing input sanitization on /api/search endpoint
8
9### Medium
10- [S3] No rate limiting on /api/auth/login
11
12### Low
13- [S4] Missing security headers (CSP, HSTS)

Step 4: Code Quality Review (reviewer)

Goal: Identify code quality, maintainability, and technical debt.

Context to pass: architecture + security summaries (avoids re-flagging already identified issues).

Checklist for reviewer:

• DRY violations (duplicated logic, copy-paste code)
• Complexity (long functions >30 lines, deep nesting >3 levels)
• Naming clarity (ambiguous vars, misleading names)
• Error handling gaps (swallowed errors, missing null checks)
• Dead code and unused imports
• Test coverage gaps (critical paths without tests)
• TypeScript: any types, missing types, incorrect types
• Comments: missing where needed, misleading, or outdated

Expected output format:

markdown
1## Code Quality Findings
2
3### High
4- [Q1] Duplicate email validation in login.ts:23 and register.ts:31
5
6### Medium
7- [Q2] processPayment() is 95 lines with 5 responsibilities
8- [Q3] Error swallowed silently in src/utils/api.ts:67
9
10### Low
11- [Q4] 12 uses of `any` type in src/types/

Step 5: Severity Aggregation

Before passing to documenter, aggregate all findings:

javascript
1allFindings = [
2  ...architectureFindings,   // A1, A2, ...
3  ...securityFindings,        // S1, S2, ...
4  ...qualityFindings          // Q1, Q2, ...
5]
6
7severity_counts = {
8  critical: allFindings.filter(f => f.severity === "Critical").length,
9  high:     allFindings.filter(f => f.severity === "High").length,
10  medium:   allFindings.filter(f => f.severity === "Medium").length,
11  low:      allFindings.filter(f => f.severity === "Low").length
12}

Health Score Formula (0–10):

Start at 10
- Critical finding: -2 each (max -6)
- High finding: -0.5 each (max -3)
- Medium finding: -0.1 each (max -1)
Score floored at 0, rounded to 1 decimal

Step 6: Consolidated Report (documenter)

Determine report path before calling documenter:

javascript
1config = readJSON(".cursor/config.json")
2
3auditsEnabled = config.documentation.enabled.audits  // true/false
4auditsPath    = config.documentation.paths.audits     // e.g. "ai_docs/develop/audits"
5
6if (auditsEnabled && auditsPath) {
7  // Save to configured docs path
8  reportFile = `${auditsPath}/YYYY-MM-DD-{scope-slug}-audit.md`
9} else {
10  // Fall back to workspace — audit still saved, just not in project docs
11  workspacePath = config.workspace.path  // e.g. ".cursor/workspace"
12  reportFile = `${workspacePath}/audits/YYYY-MM-DD-{scope-slug}-audit.md`
13}

Pass reportFile to the documenter so it saves the report to the correct location.

Report format:

markdown
1# Project Audit Report
2
3**Date**: 2026-02-25
4**Scope**: src/services/
5**Audited by**: senior-reviewer + security-auditor + reviewer
6
7---
8
9## Executive Summary
10
11**Overall Health Score**: 7.2/10
12
13| Severity | Architecture | Security | Code Quality | Total |
14|----------|-------------|----------|--------------|-------|
15| Critical | 1           | 1        | 0            | **2** |
16| High     | 2           | 1        | 2            | **5** |
17| Medium   | 1           | 1        | 3            | **5** |
18| Low      | 1           | 1        | 1            | **3** |
19
20**Recommendation**: Address 2 critical issues before next release.
21
22---
23
24## Critical Issues (fix immediately)
25
26### [A1] Circular Dependency
27**Category**: Architecture
28**Location**: services/user.ts ↔ services/auth.ts
29**Impact**: Build issues, testing difficulties, runtime errors possible
30**Fix**: Extract shared identity logic to services/identity.ts
31
32### [S1] Hardcoded JWT Secret
33**Category**: Security
34**Location**: src/config/auth.ts:12
35**Impact**: Secret exposed in version control — full auth compromise possible
36**Fix**: Move to environment variable, rotate immediately
37
38---
39
40## High Priority Issues (fix soon)
41
42[List all High severity findings with locations and suggested fixes]
43
44---
45
46## Medium Priority Issues (plan for next sprint)
47
48[List all Medium severity findings]
49
50---
51
52## Low Priority / Suggestions
53
54[List all Low severity findings]
55
56---
57
58## Priority Matrix
59
60| ID | Issue | Severity | Effort | Priority |
61|----|-------|----------|--------|----------|
62| S1 | Hardcoded JWT secret | Critical | Low | P0 — now |
63| A1 | Circular dependency | Critical | Medium | P0 — now |
64| A2 | God module helpers.ts | High | High | P1 — sprint |
65| S2 | Missing input sanitization | High | Medium | P1 — sprint |
66
67---
68
69## Next Steps
70
711. **Immediate** (before next commit): [list critical fixes]
722. **This sprint**: [list high fixes]
733. **Next sprint**: [list medium fixes]
744. **Backlog**: [list low/suggestions]
75
76Use `/refactor [file]` for structural issues.
77Use `/implement [fix]` for feature-level security fixes.

Audit Scope Guide

For full-project audits on large codebases: have each agent focus on the most critical 20-30% of files (core business logic, auth, API layer) rather than config files, generated code, or test files.

Phase 5: Remediation Routing

This phase runs only if:

1. Critical issues were found in phases 1–3
2. User explicitly confirms when asked ("Start remediation? y/n")

How to Ask the User

After showing the report, present a clear summary:

Audit complete. Health Score: X/10

Critical issues requiring immediate attention:
- [A1] Circular dependency: services/user.ts ↔ services/auth.ts  (structural)
- [S1] Hardcoded JWT secret in src/config/auth.ts:12             (security)

Start remediation for these critical issues? (y/n)
If yes, fixes will be applied in this chat automatically.

Wait for the user's response before doing anything.

Categorizing Findings for Routing

After user confirms, split critical findings into two buckets:

Bucket A — Structural / Code Quality (fix via refactor agent):

• Circular dependencies
• God classes / modules
• Deep nesting / long functions
• DRY violations
• SOLID violations
• Complexity / code smells

Bucket B — Security / Behavioral (fix via planner + worker):

• Hardcoded secrets / credentials
• Missing input validation / sanitization
• Authentication / authorization gaps
• Missing rate limiting
• Any fix that requires adding new logic, not just restructuring existing code

Executing Bucket A (Structural → refactor agent)

Task(
  subagent_type="refactor",
  prompt="Fix the following structural issues found during audit:
  [list each finding with file path and description]
  
  Context: these were identified by senior-reviewer during a full audit.
  Rules: no behavior changes, all existing tests must pass after refactoring."
)

Then verify:

Task(
  subagent_type="test-runner",
  prompt="Verify refactoring did not break anything.
  Files changed: [from refactor agent]"
)

• If tests fail → Task(subagent_type="debugger") → retry test-runner (max 3)

Executing Bucket B (Security / Behavioral → planner + worker)

Task(
  subagent_type="planner",
  prompt="Create a remediation plan for these security/behavioral issues:
  [list each finding with file path, description, and suggested fix]
  
  Each issue should be one task. Keep tasks small and independent."
)

Then for each task from the planner, execute the standard cycle:

Task(subagent_type="worker", ...)
Task(subagent_type="test-writer", ...)     ← write tests for the fix
Task(subagent_type="test-runner", ...)
  → If fail: Task(subagent_type="debugger") → retry (max 3)
Task(subagent_type="security-auditor", ...)  ← verify the specific fix
  → If issues: Task(subagent_type="debugger") → retry (max 3)

After All Fixes Applied

Update the audit report to reflect what was done:

Task(
  subagent_type="documenter",
  prompt="Update the audit report to add a Remediation section:
  Report: [original report path or content]
  
  Add:
  ## Remediation Applied
  Date: [today]
  
  ### Fixed
  - [A1] Circular dependency → resolved by extracting services/identity.ts
  - [S1] Hardcoded JWT secret → moved to environment variable
  
  ### Remaining (High/Medium/Low — not auto-fixed)
  [list remaining non-critical findings from original report]"
)

Remediation Decision Matrix

What Audit Does NOT Auto-Fix

• High / Medium / Low issues (reported, not auto-fixed)
• Issues requiring large architectural redesign (discuss with user first)
• Issues in third-party/vendor code

For remaining issues after audit, user can:

• Run /refactor [file] on specific structural issues
• Run /orchestrate to tackle a larger remediation plan