Engineering Audit

Reference knowledge for the engineering-auditor agent and the /engineering-audit and /engineering-fix commands.

When to Activate

• Before a release or major refactor
• When onboarding a new project and assessing technical debt
• When CI quality gates start failing repeatedly
• When a team member asks "how healthy is this codebase?"
• Periodically as part of engineering excellence initiatives

Metric Definitions

Cyclomatic Complexity (CC)

Number of linearly independent paths through a function. Measured by ESLint complexity rule.

Cognitive Complexity

How difficult a function is to understand, accounting for nesting and control flow breaks. Different from CC: a function with three nested ifs scores higher than three separate ifs at the same level.

Nesting Depth

Maximum levels of nested blocks (if/for/try). Measured by ESLint max-depth rule. Threshold: 4.

Function Length

Lines of code per function. Measured by ESLint max-lines-per-function. Threshold: 50 lines.

File Length

Total lines per file. Measured by ESLint max-lines. Threshold: 300 lines.

Maintainability Index

Composite score derived from CC, function length, and Halstead volume. Higher is better (0–100).

Technical Debt Ratio

Estimated remediation time relative to development time. SonarQube-style metric: < 5% = A, 6–10% = B, 11–20% = C, 21–50% = D, > 50% = E.

Scoring Thresholds

Per-Dimension Score (0–10)

Maintainability

• 10: All functions CC ≤ 5, no function > 30 lines
• 7: Avg CC < 10, no function > 50 lines
• 4: Avg CC < 20, some functions 50–100 lines
• 0–3: Any CC > 25, or functions > 200 lines

Security

• 10: 0 npm audit vulnerabilities
• 7: Low severity only
• 4: Moderate vulnerabilities
• 0–3: Any critical or high vulnerability

Testing

• 10: > 90% line coverage, test:source ratio > 1.0
• 7: > 60% coverage
• 4: > 30% coverage
• 0–3: < 30% coverage or no test suite

Architecture

• 10: 0 circular dependencies, no god files
• 7: < 3 circular deps
• 4: < 10 circular deps
• 0–3: ≥ 10 circular deps or multiple god files

Documentation

• 10: > 80% public APIs documented (JSDoc)
• 7: > 50%
• 4: > 20%
• 0–3: < 20%

Lint Health

• 10: 0 errors, 0 warnings
• 7: 0 errors, < 10 warnings
• 4: < 10 errors
• 0–3: ≥ 10 errors

Type Safety (TypeScript only)

• 10: 0 type errors, 0 any usages
• 7: 0 errors, < 5 any
• 4: < 10 errors
• 0–3: ≥ 10 errors or widespread any

Build Health

• 10: Build passes, no warnings
• 7: Build passes with warnings
• 4: Build passes on some targets
• 0–3: Build fails

Weighted Engineering Score

Refactoring Techniques

Extract Method

Split a long or complex function into smaller, named functions.

Before:

function processOrder(order: Order) {
  if (!order.items || order.items.length === 0) return;
  let total = 0;
  for (const item of order.items) {
    total += item.price * item.quantity;
    if (item.discount) total -= item.discount;
  }
  const tax = total * 0.1;
  total += tax;
  if (order.coupon === 'SAVE10') total -= total * 0.1;
  order.total = total;
  sendConfirmationEmail(order);
}

After:

function calculateSubtotal(items: OrderItem[]): number {
  return items.reduce((sum, item) => {
    const lineTotal = item.price * item.quantity;
    return sum + lineTotal - (item.discount ?? 0);
  }, 0);
}

function applyTaxAndCoupons(subtotal: number, coupon?: string): number {
  const withTax = subtotal * 1.1;
  return coupon === 'SAVE10' ? withTax * 0.9 : withTax;
}

function processOrder(order: Order) {
  if (!order.items?.length) return;
  order.total = applyTaxAndCoupons(calculateSubtotal(order.items), order.coupon);
  sendConfirmationEmail(order);
}

Early Return (Guard Clauses)

Replace nested conditions with early returns to reduce nesting depth.

Before:

function getDiscount(user: User) {
  if (user) {
    if (user.isPremium) {
      if (user.yearsActive > 5) {
        return 0.3;
      } else {
        return 0.15;
      }
    } else {
      return 0.05;
    }
  }
  return 0;
}

After:

function getDiscount(user: User | null): number {
  if (!user) return 0;
  if (!user.isPremium) return 0.05;
  return user.yearsActive > 5 ? 0.3 : 0.15;
}

Strategy Pattern

Replace long switch or if/else chains with a strategy object.

Before:

function format(value: string, type: string) {
  if (type === 'date') return new Date(value).toLocaleDateString();
  if (type === 'currency') return `$${parseFloat(value).toFixed(2)}`;
  if (type === 'percent') return `${parseFloat(value) * 100}%`;
  return value;
}

After:

const formatters: Record<string, (v: string) => string> = {
  date: (v) => new Date(v).toLocaleDateString(),
  currency: (v) => `$${parseFloat(v).toFixed(2)}`,
  percent: (v) => `${parseFloat(v) * 100}%`,
};

function format(value: string, type: string): string {
  return (formatters[type] ?? ((v) => v))(value);
}

Split Module

Break a god file into cohesive modules.

• Group by responsibility: separate data access, business logic, and presentation
• Each new file should be < 300 lines and have a single, clear purpose
• Export a barrel (index.ts) if consumers need to import from multiple sub-modules

Type Narrowing

Replace any with precise types using guards.

Before:

function process(data: any) {
  return data.value.toString();
}

After:

interface Processable {
  value: string | number;
}

function isProcessable(data: unknown): data is Processable {
  return typeof data === 'object' && data !== null && 'value' in data;
}

function process(data: unknown): string {
  if (!isProcessable(data)) throw new TypeError('Invalid data shape');
  return data.value.toString();
}

Dependency Inversion

Make high-level modules depend on abstractions, not concretions.

Before:

class OrderService {
  private db = new PostgresDatabase();
  save(order: Order) { this.db.insert(order); }
}

After:

interface Database {
  insert(record: unknown): void;
}

class OrderService {
  constructor(private db: Database) {}
  save(order: Order) { this.db.insert(order); }
}

Audit Report Format

Reports are saved at .egc/audits/engineering-audit-<YYYY-MM-DD>.md.

# Engineering Audit: <project>: <date>

## Engineering Score: X.X / 10

| Dimension | Score | Status |
|---|---|---|
| Maintainability | X.X | ok / warn / critical |
| Security | X.X | ok / warn / critical |
| ... | ... | ... |

## Findings

### CRITICAL (N)
- [file:line] description: technique

### HIGH (N)
...

## Remediation Plan

### 1. [file]: Extract Method
Root cause: ...
Impact: ...
Steps: ...

## Observability Log

| Timestamp | Tool | Files Analyzed | Issues Found |
|---|---|---|---|
| ... | ESLint | N | N |

Observability

Every audit run appends to .egc/audits/audit-log.jsonl:

{"ts":"2026-06-07T22:00:00Z","tool":"eslint","files":42,"errors":3,"warnings":17}
{"ts":"2026-06-07T22:00:01Z","tool":"tsc","errors":0,"any_count":2}
{"ts":"2026-06-07T22:00:02Z","tool":"npm-audit","critical":0,"high":0,"moderate":1}
{"ts":"2026-06-07T22:00:03Z","score":8.6,"dimensions":{"maintainability":8.9,"security":9.7}}

Related Skills

• security-review: deep security analysis
• coding-standards: language-specific quality standards
• tdd-workflow: test coverage improvement
• plankton-code-quality: additional quality patterns