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