All skills
🏗️

Code Quality Audit

Best Practices

Run a comprehensive audit on your app's code. Checks structural patterns, code organization, consistency, test coverage, and technical debt. Produces actionable findings ranked by severity so you know exactly what to fix first.

Skill prompt

Engineering Audit Skill

Perform a deep engineering audit of a TypeScript/Node.js codebase. This skill is for TypeScript + Bash environments only. Execute each section below, collect findings, and produce a final structured report.

Audit Execution Order

Run the sections in this order. For each finding, record the severity, file path, line number, and a concise description.

Severity Levels
Severity Meaning
critical Actively causing bugs, data loss, or security holes. Fix immediately.
high Will cause problems soon or blocks maintainability. Fix this sprint.
medium Code smell or suboptimal pattern. Plan to address.
low Minor style or convention issue. Address opportunistically.
info Observation or positive finding worth noting. No action required.

1. Architecture Review

Examine module boundaries, layering, and structural patterns.

Circular Dependencies
bash
# Use madge to detect circular dependencies
npx madge --circular --extensions ts src/

# If madge is not available, check for obvious circular imports manually
npx madge --circular --extensions ts --no-spinner src/ 2>/dev/null || echo "madge not available - perform manual inspection"
Barrel Export Analysis
bash
# Find barrel files (index.ts that only re-export)
find src/ -name "index.ts" -exec grep -l "export \* from\|export {" {} \;

# Check for barrel files that re-export everything (can cause large bundle sizes and circular deps)
grep -rn "export \* from" src/index.ts src/**/index.ts 2>/dev/null
Layering Violations

Check that dependencies flow in one direction. In a Hercules app the rule is: React components import from convex/_generated/api, and Convex functions never import from src/ (the frontend). Flag any backend file that reaches into the frontend.

bash
# Find Convex functions that import from the frontend
grep -rn "from ['\"]\.\./src\|from ['\"]@/" convex/ 2>/dev/null

# Find React components that bypass the Convex hooks layer
grep -rn "ConvexHttpClient\|new ConvexClient" src/ --include="*.tsx" 2>/dev/null
Module Size Analysis
bash
# Find god files (files over 500 lines)
find src/ -name "*.ts" -exec wc -l {} \; | sort -rn | head -20

# Find god directories (directories with too many files)
find src/ -type d -exec sh -c 'echo "$(find "$1" -maxdepth 1 -name "*.ts" | wc -l) $1"' _ {} \; | sort -rn | head -15
Separation of Concerns
bash
# Find React components doing database work directly instead of going through Convex hooks
grep -rln "ConvexHttpClient\|fetch(" src/ --include="*.tsx" 2>/dev/null

# Find Convex queries/mutations that mix data access with rendering or business rules
grep -rn "ctx\.db\." convex/ --include="*.ts" -A2 2>/dev/null | grep -B1 "JSX\|React\|return <" | head -20

2. Type Safety

Identify patterns that weaken TypeScript's type system.

any Usage
bash
# Count and locate all uses of 'any'
grep -rn "\bany\b" src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules" | grep -v "\.d\.ts"

# Specifically dangerous: function parameters and return types typed as any
grep -rn ":\s*any\b\|<any>" src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules"
Type Assertions
bash
# Find 'as' type assertions (especially 'as any' and 'as unknown')
grep -rn "\bas any\b\|\bas unknown\b" src/ --include="*.ts" --include="*.tsx"

# Find angle-bracket assertions (older style)
grep -rn "<any>\|<unknown>" src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules"
Non-Null Assertions
bash
# Find non-null assertion operator usage (!)
grep -rn "[a-zA-Z0-9_)\]]!\." src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules" | grep -v "\.d\.ts"
grep -rn "[a-zA-Z0-9_)\]]!;" src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules"
Missing Return Types on Exported Functions
bash
# Exported functions without explicit return types
grep -rn "export\s\+\(async\s\+\)\?function\s\+[a-zA-Z]" src/ --include="*.ts" | grep -v "):" | grep -v "): " | head -30
Generic Abuse
bash
# Find overly complex generic signatures (4+ type parameters)
grep -rn "<[A-Z][a-zA-Z]*,\s*[A-Z][a-zA-Z]*,\s*[A-Z][a-zA-Z]*,\s*[A-Z]" src/ --include="*.ts" | grep -v "node_modules"

3. Code Quality

Dead Code Detection
bash
# Use knip to find unused exports, files, and dependencies
npx knip 2>/dev/null || echo "knip not available - perform manual inspection"

# Find unused exports manually: exported functions not imported elsewhere
grep -rn "export function\|export const\|export class\|export interface\|export type\|export enum" src/ --include="*.ts" | head -50
Duplicated Logic
bash
# Find suspiciously similar function names across files (potential duplication)
grep -rn "export\s\+\(async\s\+\)\?function" src/ --include="*.ts" | sed 's/.*function\s\+//' | sed 's/(.*//' | sort | uniq -d

# Find copy-paste patterns: identical multi-line blocks
# Look for identical catch blocks, similar validation logic, etc.
grep -rn "catch\s*(.*)\s*{" src/ --include="*.ts" -A3 | head -40
Overly Complex Functions
bash
# Find functions with deep nesting (proxy for high cyclomatic complexity)
# Files with many levels of indentation
grep -rn "^\s\{16,\}" src/ --include="*.ts" | grep -v "node_modules" | head -20

# Find long functions: blocks with more than 50 lines between braces
awk '/^\s*(export\s+)?(async\s+)?function|=>\s*\{/{start=NR} /^\}/{if(start && NR-start>50) print FILENAME":"start" ("NR-start" lines)"; start=0}' src/**/*.ts 2>/dev/null | head -20
Inconsistent Naming
bash
# Find snake_case in TypeScript (should be camelCase)
grep -rn "const [a-z]\+_[a-z]\|let [a-z]\+_[a-z]\|function [a-z]\+_[a-z]" src/ --include="*.ts" | grep -v "node_modules" | head -20

# Find inconsistent boolean naming (should start with is/has/should/can/will)
grep -rn "const\s\+\(is\|has\|should\|can\|will\)" src/ --include="*.ts" | wc -l
grep -rn ":\s*boolean" src/ --include="*.ts" | grep -v "is\|has\|should\|can\|will\|enable\|disable\|allow\|visible\|active\|valid\|loading\|open\|closed\|done\|ready" | head -20

4. Error Handling

Swallowed Errors
bash
# Empty catch blocks
grep -rn "catch" src/ --include="*.ts" -A2 | grep -B1 "{\s*}" | grep "catch"

# Catch blocks that only log (no rethrow or return)
grep -rn "catch" src/ --include="*.ts" -A5 | grep -A4 "console\.\(log\|warn\)" | grep -v "throw\|return\|reject" | head -20
Missing Error Boundaries
bash
# Find top-level async functions without try/catch
grep -rn "export\s\+async\s\+function" src/ --include="*.ts" -A15 | grep -B1 "await" | grep -v "try" | head -20

# Find Convex actions making external calls without try/catch
grep -rn "await fetch\|await axios" convex/ --include="*.ts" -B3 | grep -v "try" | head -20
Unhandled Promise Rejections
bash
# Promises without .catch() and not in try/catch
grep -rn "\.then(" src/ --include="*.ts" | grep -v "\.catch(" | grep -v "await" | head -20

# Fire-and-forget async calls (no await, no .catch)
grep -rn "[^await]\s\+[a-zA-Z]\+(" src/ --include="*.ts" | grep -v "\.catch\|await\|void\|\/\/" | head -20
Inconsistent Error Patterns
bash
# Check for mixed error creation patterns
grep -rn "new Error(\|throw new\|throw '" src/ --include="*.ts" | sed 's/.*\(new Error\|throw new [A-Z][a-zA-Z]*\|throw '\''.*'\''\).*/\1/' | sort | uniq -c | sort -rn

# Find error classes to check for consistency
grep -rn "class.*extends.*Error" src/ --include="*.ts"

5. Dependency Health

Outdated and Vulnerable Packages
bash
# Check for outdated packages
npm outdated 2>/dev/null || pnpm outdated 2>/dev/null || yarn outdated 2>/dev/null

# Security audit
npm audit 2>/dev/null || pnpm audit 2>/dev/null
Unused Dependencies
bash
# Use depcheck or knip to find unused dependencies
npx depcheck 2>/dev/null || npx knip --dependencies 2>/dev/null || echo "depcheck/knip not available"
Duplicate Dependencies
bash
# Check for duplicate packages in lockfile
npm ls --all 2>/dev/null | grep -i "deduped" | wc -l
npm ls --all 2>/dev/null | grep "invalid" | head -10

# Check for multiple versions of the same package
cat package-lock.json 2>/dev/null | grep -o '"node_modules/[^"]*"' | sed 's/.*\///' | sed 's/"//' | sort | uniq -d | head -20
Heavy Imports
bash
# Find imports that pull in large packages where lighter alternatives exist
grep -rn "from ['\"]lodash['\"]" src/ --include="*.ts" | head -10
grep -rn "from ['\"]moment['\"]" src/ --include="*.ts" | head -10
grep -rn "from ['\"]axios['\"]" src/ --include="*.ts" | head -10

# Check for deep imports vs barrel imports (barrel = heavier)
grep -rn "from ['\"]lodash['\"]" src/ --include="*.ts" | wc -l
grep -rn "from ['\"]lodash/" src/ --include="*.ts" | wc -l

6. Testing Gaps

Missing Test Files
bash
# Find source files without corresponding test files
for file in $(find src/ -name "*.ts" -not -name "*.test.ts" -not -name "*.spec.ts" -not -name "*.d.ts" -not -name "index.ts" -not -path "*/test/*" -not -path "*/__tests__/*"); do
    base="${file%.ts}"
    if [ ! -f "${base}.test.ts" ] && [ ! -f "${base}.spec.ts" ]; then
        dir=$(dirname "$file")
        fname=$(basename "$base")
        if [ ! -f "${dir}/__tests__/${fname}.test.ts" ] && [ ! -f "${dir}/__tests__/${fname}.spec.ts" ]; then
            echo "MISSING TEST: $file"
        fi
    fi
done | head -30
Low Assertion Density
bash
# Find test files with low assertion counts
for testfile in $(find src/ -name "*.test.ts" -o -name "*.spec.ts"); do
    tests=$(grep -c "it(\|test(" "$testfile" 2>/dev/null || echo 0)
    asserts=$(grep -c "expect\|assert" "$testfile" 2>/dev/null || echo 0)
    if [ "$tests" -gt 0 ] && [ "$asserts" -lt "$tests" ]; then
        echo "LOW ASSERTIONS ($asserts asserts / $tests tests): $testfile"
    fi
done
Test Anti-Patterns
bash
# Tests checking implementation details (mocking internals excessively)
grep -rn "jest\.mock\|vi\.mock\|sinon\.stub" src/ --include="*.test.ts" --include="*.spec.ts" | wc -l

# Disabled/skipped tests
grep -rn "\.skip\|xdescribe\|xit\|test\.skip\|it\.skip" src/ --include="*.test.ts" --include="*.spec.ts"

# Tests without cleanup
grep -rn "beforeEach\|afterEach\|beforeAll\|afterAll" src/ --include="*.test.ts" --include="*.spec.ts" | wc -l

# Snapshot overuse
grep -rn "toMatchSnapshot\|toMatchInlineSnapshot" src/ --include="*.test.ts" --include="*.spec.ts" | wc -l

7. Performance Patterns

N+1 Queries
bash
# Database calls inside loops (the classic N+1 — fetch parents, then loop and fetch children one by one)
grep -rn "for\s*(.*of\|forEach\|\.map(" convex/ --include="*.ts" -A8 | grep -B3 "ctx\.db\.\(get\|query\)" | head -30
Missing Memoization
bash
# Expensive computations that could be memoized: repeated function calls with same patterns
grep -rn "\.filter(.*\.filter\|\.map(.*\.map\|\.reduce(.*\.reduce" src/ --include="*.ts" | head -10

# React components: missing useMemo/useCallback for expensive operations
grep -rn "\.filter(\|\.map(\|\.sort(\|\.reduce(" src/ --include="*.tsx" | grep -v "useMemo\|useCallback" | head -20
Sync Operations That Should Be Async
bash
# Synchronous file system operations in non-script files
grep -rn "readFileSync\|writeFileSync\|existsSync\|mkdirSync\|readdirSync\|statSync\|unlinkSync\|appendFileSync" src/ --include="*.ts" | grep -v "node_modules\|\.test\.\|\.spec\.\|scripts/" | head -20

# Synchronous crypto operations
grep -rn "crypto\..*Sync\|pbkdf2Sync\|scryptSync\|randomBytes\b" src/ --include="*.ts" | grep -v "node_modules" | head -10
Large Bundle Contributions
bash
# Check for dynamic imports that should be lazy-loaded
grep -rn "^import.*from" src/ --include="*.ts" --include="*.tsx" | grep -i "chart\|editor\|markdown\|highlight\|pdf\|xlsx\|csv\|moment\|lodash\|aws-sdk" | head -20

8. Security Quick-Check

Hardcoded Secrets
bash
# Potential hardcoded secrets, tokens, and keys
grep -rn "password\s*[:=]\s*['\"][^'\"]\+['\"]" src/ --include="*.ts" | grep -vi "test\|spec\|mock\|example\|placeholder\|changeme\|xxx"
grep -rn "apiKey\s*[:=]\s*['\"][^'\"]\+['\"]" src/ --include="*.ts" | grep -vi "test\|spec\|mock"
grep -rn "secret\s*[:=]\s*['\"][^'\"]\+['\"]" src/ --include="*.ts" | grep -vi "test\|spec\|mock\|process\.env"
grep -rn "Bearer\s\+[A-Za-z0-9._-]\{20,\}" src/ --include="*.ts" | head -10
Unsafe Regex
bash
# Find complex regex patterns that may be vulnerable to ReDoS
grep -rn "new RegExp(\|/.*[*+]\{.*[*+]" src/ --include="*.ts" | grep -v "node_modules" | head -15
Prototype Pollution Vectors
bash
# Object.assign or spread with user input
grep -rn "Object\.assign\|_.merge\|_.defaultsDeep\|_.set(" src/ --include="*.ts" | grep -v "node_modules" | head -10

# Missing __proto__ / constructor checks in merge utilities
grep -rn "function.*merge\|function.*extend\|function.*deepCopy" src/ --include="*.ts" | head -10
Unsanitized User Input
bash
# User input flowing into dangerous sinks
grep -rn "innerHTML\|outerHTML\|document\.write\|eval(\|new Function(" src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules" | head -10

# exec with string interpolation (command injection)
grep -rn "exec(\`\|exec(\".*\$\|execSync(\`" src/ --include="*.ts" | grep -v "node_modules" | head -10

9. Technical Debt Markers

TODO/FIXME/HACK Comments
bash
# Inventory all debt markers with context
echo "=== TODOs ==="
grep -rn "// TODO\|// @todo\|/\* TODO" src/ --include="*.ts" --include="*.tsx"
echo ""
echo "=== FIXMEs ==="
grep -rn "// FIXME\|// @fixme\|/\* FIXME" src/ --include="*.ts" --include="*.tsx"
echo ""
echo "=== HACKs ==="
grep -rn "// HACK\|// @hack\|/\* HACK\|// XXX\|// WORKAROUND" src/ --include="*.ts" --include="*.tsx"
Deprecated API Usage
bash
# Find @deprecated usage or calls to deprecated Node.js APIs
grep -rn "@deprecated" src/ --include="*.ts" | head -15
grep -rn "url\.parse(\|new Buffer(\|fs\.exists(\|path\.extname" src/ --include="*.ts" | grep -v "node_modules" | head -10

# Deprecated TypeScript patterns
grep -rn "/// <reference\|namespace " src/ --include="*.ts" | grep -v "node_modules\|\.d\.ts" | head -10
Temporary Workarounds
bash
# Patterns that suggest temporary code
grep -rn "// temporary\|// temp fix\|// remove after\|// revert this\|// quick fix\|// hotfix\|@ts-ignore\|@ts-expect-error\|eslint-disable" src/ --include="*.ts" --include="*.tsx" | head -30

10. Automated Tool Checks

Run available tooling for deeper analysis. Skip tools that are not installed.

bash
# Use the run_lint and run_build tools to check for type errors and lint
# violations. They run the project's configured linter and build pipeline
# without needing to know which tools the project uses.

# Circular dependency check
npx madge --circular --extensions ts src/ 2>&1

# Unused exports and dependencies
npx knip 2>&1 | head -50

Output: Final Report Format

After completing all sections, compile findings into this structured report. Every finding MUST include a file path and line number where possible.

markdown
# Engineering Audit Report

**Project:** [project name]
**Date:** [audit date]
**Scope:** [directories audited]

## Executive Summary

- **Critical:** X findings
- **High:** X findings
- **Medium:** X findings
- **Low:** X findings
- **Info:** X findings

## Critical Findings

1. **[CRITICAL]** `src/path/file.ts:42` - Description of the issue
   - **Impact:** What goes wrong if this is not fixed
   - **Recommendation:** Specific fix with code example if applicable

## High Findings

1. **[HIGH]** `src/path/file.ts:100` - Description of the issue
   - **Impact:** Why this matters
   - **Recommendation:** How to fix it

## Medium Findings

1. **[MEDIUM]** `src/path/file.ts:200` - Description of the issue
   - **Recommendation:** Suggested improvement

## Low Findings

1. **[LOW]** `src/path/file.ts:300` - Description of the issue

## Info / Positive Observations

1. **[INFO]** Good pattern observed: description

## Technical Debt Summary

| Category                | Count | Top Priority Item       |
| ----------------------- | ----- | ----------------------- |
| TODO/FIXME comments     | X     | file.ts:N - description |
| `any` type usage        | X     | file.ts:N - description |
| Skipped tests           | X     | file.test.ts:N          |
| @ts-ignore/expect-error | X     | file.ts:N               |
| Deprecated API calls    | X     | file.ts:N               |

## Recommended Next Steps

1. [Prioritized action item 1]
2. [Prioritized action item 2]
3. [Prioritized action item 3]

When to Use This Skill

Use /engineering-audit when:

  • Onboarding onto an unfamiliar TypeScript codebase
  • Preparing for a major refactor or migration
  • Conducting a quarterly or periodic health check
  • Evaluating a codebase for acquisition or integration
  • Establishing a baseline before adding new team members
  • Identifying and prioritizing technical debt reduction work
  • Preparing architecture decision records (ADRs) backed by evidence