Principal Engineer Audit - Optix MCP Server
Description: Code quality and maintainability analysis for cyclomatic complexity, DRY violations, and coupling.

Ctrl K
`↑``↓` to navigate `Enter` to select `Esc` to close

# Principal Engineer Audit

Code quality and maintainability analysis from a principal engineer's perspective.

5-Step Workflow

This tool analyzes code quality across 5 dimensions critical for long-term maintainability.

## Overview

The `principal_audit` tool evaluates codebase quality from an experienced engineer's perspective. It identifies complexity hotspots, code duplication, tight coupling, and maintainability risks that impact long-term development velocity.

## Workflow Steps

1
Complexity Analysis
Cyclomatic complexity, cognitive complexity, and deeply nested code paths.
2
DRY Violation Detection
Duplicate code blocks, copy-paste patterns, and opportunities for abstraction.
3
Coupling Analysis
Module dependencies, circular references, and component coupling metrics.
4
Separation of Concerns
Mixed responsibilities, god classes/functions, and architectural boundaries.
5
Maintainability Assessment
Overall maintainability scoring, technical debt indicators, and final report.

## Parameters

Parameter | Type | Required | Description
--- | --- | --- | ---
step_number integer | Required | Current step number (1-5)
next_step_required boolean | Required | Set to `false` on step 5
files_examined array[string] | Required | Source files examined
confidence string | Required | Confidence level
continuation_id string | After step 1 | UUID from step 1 response
principal_findings array[object] | Optional | Code quality findings
principal_assessments object | Optional | Positive quality observations

## Finding Format

json

    {
      "category": "complexity",
      "severity": "high",
      "description": "Function exceeds complexity threshold",
      "affected_files": [
        {
          "file_path": "src/services/payment.py",
          "line_start": 45,
          "line_end": 120,
          "function_name": "process_payment"
        }
      ],
      "remediation": "Extract conditional branches into separate functions",
      "confidence": "high",
      "complexity_score": 25
    }

### Categories

- complexity - High cyclomatic/cognitive complexity
- dry_violation - Duplicate or copy-pasted code
- coupling - Tight coupling between modules
- separation_of_concerns - Mixed responsibilities
- maintainability_risk - General maintainability issues

## Quality Metrics

### Complexity Thresholds

Metric | Good | Warning | Critical
--- | --- | --- | ---
Cyclomatic Complexity | < 10 | 10-20 | > 20
Cognitive Complexity | < 15 | 15-25 | > 25
Function Length (LOC) | < 50 | 50-100 | > 100
Nesting Depth | < 4 | 4-6 | > 6

### DRY Violations

Duplication % | Severity
--- | ---
> 80% similar | Critical
60-80% similar | High
40-60% similar | Medium

## Example Usage

MCP Tool Call

    principal_audit(
      step_number=1,
      next_step_required=true,
      files_examined=["src/services/order.py", "src/services/payment.py"],
      confidence="medium",
      project_root_path="/path/to/project",
      principal_findings=[
        {
          "category": "complexity",
          "severity": "high",
          "description": "Function has cyclomatic complexity of 28",
          "affected_files": [
            {
              "file_path": "src/services/order.py",
              "line_start": 100,
              "line_end": 250,
              "function_name": "calculate_order_total"
            }
          ],
          "remediation": "Break down into smaller functions handling tax, discounts, and shipping separately",
          "confidence": "high",
          "complexity_score": 28
        }
      ],
      principal_assessments={
        "Architecture": "Clean service layer separation"
      }
    )

## Output

Generates `reports/NNN_PRINCIPAL_AUDIT_REPORT.md` with:

- Complexity hotspots with metrics
- DRY violations with similarity percentages
- Coupling analysis and dependency graphs
- Refactoring recommendations prioritized by impact
- Overall maintainability score