Quality Audit

Quality Audit Workflow

Purpose

Orchestrates a systematic, parallel quality audit of any codebase with automated remediation through PR generation and PM-prioritized recommendations.

When I Activate

I automatically load when you mention:

• "quality audit" or "code audit"
• "codebase review" or "full code review"
• "refactoring opportunities" or "technical debt audit"
• "module quality check" or "architecture review"
• "parallel analysis" with multiple agents

What I Do

Execute a 7-phase workflow that:

1. Familiarizes with the project (investigation phase) 2. Audits using parallel agents across codebase divisions 3. Creates GitHub issues for each discovered problem 3.5. Validates against recent PRs (prevents false positives) 4. Generates PRs in parallel worktrees per remaining issues 5. Reviews PRs with PM architect for prioritization 6. Reports consolidated recommendations in master issue

Quick Start

User: "Run a quality audit on this codebase"
Skill: *activates automatically*
       "Beginning quality audit workflow..."

The 7 Phases

Phase 1: Project Familiarization

• Run investigation workflow on project structure
• Map modules, dependencies, and entry points
• Understand existing patterns and architecture

Phase 2: Parallel Quality Audit

• Divide codebase into logical sections
• Deploy multiple agent types per section (analyzer, reviewer, security, optimizer)
• Apply PHILOSOPHY.md standards ruthlessly
• Check module size, complexity, single responsibility

Phase 3: Issue Assembly

• Create GitHub issue for each finding
• Include severity, location, recommendation
• Tag with appropriate labels
• Add unique IDs, keywords, and file metadata

Phase 3.5: Post-Audit Validation [NEW]

• Scan merged PRs from last 30 days (configurable)
• Calculate confidence scores for PR-issue matches
• Auto-close high-confidence matches (≥90%)
• Tag medium-confidence matches (70-89%) for verification
• Add bidirectional cross-references between issues and PRs
• Target: <5% false positive rate

Phase 4: Parallel PR Generation

• Create worktree per remaining open issue (worktrees/fix-issue-XXX)
• Run DEFAULT_WORKFLOW.md in each worktree
• Generate fix PR for each confirmed open issue

Phase 5: PM Review

• Invoke pm-architect skill
• Group PRs by category and priority
• Identify dependencies between fixes

Phase 6: Master Report

• Create master GitHub issue
• Link all related issues and PRs
• Prioritized action plan with recommendations

Philosophy Enforcement

This workflow ruthlessly applies:

• Ruthless Simplicity: Flag over-engineered modules
• Module Size Limits: Target <300 LOC per module
• Single Responsibility: One purpose per brick
• Zero-BS: No stubs, no TODOs, no dead code
• Anti-Fallback (#2805, #2810): Detect silent degradation and error swallowing patterns
• Structural Analysis (#2809): Flag oversized files, deeply nested code, and tangled dependencies

Detection Categories

Standard Categories

Extended Categories

| Category | What It Detects | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | -------------------------- | | Silent Fallbacks | except: pass, broad catches that return defaults silently, fallback chains that mask failures, ?? defaultValue hiding missing config, dict.get(key, default) on required values, | | fallback in shell scripts | | Error Swallowing | Catch blocks with no re-raise/re-throw, error-to-None/null transforms, catch-all discarding exceptions, log-only catch blocks, empty catch blocks, catch (Exception) returning false/default/empty collection | | Result Dropping | Fire-and-forget async (_ = Task(), asyncio.create_task() without error handling), unchecked HTTP response status, discarded return values, Task.WhenAll/Promise.all/asyncio.gather without individual failure checks, unchecked subprocess.run() | | Shell Anti-Patterns | \|\| true, >/dev/null 2>&1, 2>/dev/null, set +e, \|\| fallback_command, missing set -euo pipefail | | Silent Truncation | Take(N)/[:N]/.slice(0,N) without logging, .Where()/list comprehensions that silently drop items that should be processed, string substring without bounds logging | | Async Anti-Patterns | async void (C#), .Result/.Wait() sync-over-async, unawaited coroutines/promises, shared mutable state without synchronization, CancellationToken not propagated, Timer/CancellationTokenSource not disposed | | Config Divergence | Env vars defined in deploy configs but read with silent fallbacks in code, IsDevelopment() guards that could leak to staging/prod, services expecting config that infrastructure doesn't provide | | Validation Gaps | API endpoints without input validation, string interpolation in SQL/GraphQL/Cypher, missing pagination limits, missing request size limits, enum parsing from user input without validation, trusting deserialized external data without null checks | | Health & Observability | Degraded reported when Unhealthy is appropriate, background worker failures not surfaced to /health, log-only error handling without metrics, permanent errors treated as transient (retried instead of dead-lettered), partial success marked as full success | | Retry Anti-Patterns | Retry loops that fall through silently after exhaustion, circuit breakers that open without alerting, retry logic that eventually gives up without raising the last error | | Structural Issues | Files >500 LOC, functions >50 lines, nesting >4 levels, >5 parameters, circular imports | | Documentation | Point-in-time content, unprofessional tone (pirate speak, chatbot artifacts), quality/correctness gaps | | Hardcoded Limits | Non-configurable numeric caps ([:N], max_X = N), silent truncation without logging, data loss from processing limits |

Multi-Agent Validation (v3.0)

Every finding is validated by 3 independent agents (analyzer, reviewer, architect). A finding is confirmed only if ≥2 agents agree. This eliminates false positives before any fixes are attempted.

Iterative Loop with Escalating Depth (v3.0)

Cycle 1: SEEK → VALIDATE (3 agents) → FIX → decision
Cycle 2: SEEK (deeper) → VALIDATE → FIX → decision
Cycle 3: SEEK (deepest) → VALIDATE → FIX → decision
...continues if thresholds not met

Loop rules:

• Minimum 3 cycles always run
• Continue past 3 if: any high/critical NEW findings emerged, or >3 medium NEW findings
• Maximum 6 cycles (safety valve)
• Each cycle: fresh eyes, dig deeper, challenge prior findings
• Fixes use the full DEFAULT_WORKFLOW approach (understand → test → implement → verify)
• Fix-all-per-cycle rule (#2842): Every confirmed finding in a cycle MUST be

fixed before the cycle is complete. No partial cycles. No deferring findings to "follow-up issues" or "next cycle". If SEEK finds issues, FIX must address ALL of them.

• Loop decision based on NEW findings (#2842): The decision to continue is

based on whether the current cycle discovered NEW issues, not whether old issues remain unfixed (they shouldn't — the fix-all rule prevents that).

• Fix verification step: After fixes, a verification step compares confirmed

findings against fix results to ensure nothing was skipped.

Run via recipe:

amplihack recipe execute quality-audit-cycle.yaml --context '{"target_path": "src/amplihack", "min_cycles": "3", "max_cycles": "6"}'

Configuration

Override defaults via recipe context or environment:

Structured Inputs (recipe context, per #2843):

Available Categories: security, reliability, dead_code, silent_fallbacks, error_swallowing, result_dropping, shell_anti_patterns, silent_truncation, async_anti_patterns, config_divergence, validation_gaps, health_observability, retry_anti_patterns, structural, hardcoded_limits, test_gaps, doc_gaps, documentation

Example invocation:

amplihack recipe execute quality-audit-cycle.yaml --context '{
  "target_path": "src/amplihack/fleet",
  "min_cycles": "3",
  "max_cycles": "6",
  "severity_threshold": "medium",
  "module_loc_limit": "300",
  "fix_all_per_cycle": "true",
  "categories": "security,reliability,dead_code,silent_fallbacks,error_swallowing"
}'

Core Settings (environment):

• AUDIT_PARALLEL_LIMIT: Max concurrent worktrees (default: 8)

Phase 3.5 Validation Settings:

• AUDIT_PR_SCAN_DAYS: Days to scan for recent PRs (default: 30)
• AUDIT_AUTO_CLOSE_THRESHOLD: Confidence % for auto-close (default: 90)
• AUDIT_TAG_THRESHOLD: Confidence % for tagging (default: 70)
• AUDIT_ENABLE_VALIDATION: Enable Phase 3.5 (default: true)

Quality Audit Workflow - Working Examples

Practical examples demonstrating quality audit workflow execution.

---

Basic Examples

Example 1: Simple Quality Audit

User Request:

User: "Run a quality audit on this codebase"

Skill Activation:

quality-audit-workflow: *activates automatically*
"Beginning comprehensive quality audit of your codebase..."

Execution Flow:

Phase 1: Project Familiarization
├── Exploring project structure...
├── Found 12 modules in src/
├── Mapped 45 dependencies
└── Identified 3 existing TODO markers

Phase 2: Parallel Quality Audit
├── Division: src/core/ (4 agents running)
├── Division: src/api/ (4 agents running)
├── Division: src/utils/ (4 agents running)
└── Consolidated 18 findings

Phase 3: Issue Assembly
├── Created issue #101: [AUDIT] high: Complex auth module
├── Created issue #102: [AUDIT] medium: Dead code in utils
├── Created issue #103: [AUDIT] medium: Missing error handling
└── 3 issues created

Phase 4: Parallel PR Generation
├── worktrees/fix-issue-101 → PR #201
├── worktrees/fix-issue-102 → PR #202
├── worktrees/fix-issue-103 → PR #203
└── 3 PRs created

Phase 5: PM Review
├── Priority 1: PR #202 (no dependencies)
├── Priority 2: PR #203 (no dependencies)
├── Priority 3: PR #201 (complex, review carefully)
└── Recommended merge sequence: #202 → #203 → #201

Phase 6: Master Report
└── Created master issue #104 with full report

Output:

Quality Audit Complete!

Summary:
- 12 modules analyzed
- 18 findings discovered
- 3 issues created
- 3 PRs generated

Master Report: https://github.com/org/repo/issues/104

Recommended Actions:
1. Review and merge PR #202 (trivial dead code removal)
2. Review and merge PR #203 (error handling improvement)
3. Carefully review PR #201 (auth module refactor)

---

Example 2: Targeted Audit (Specific Directory)

User Request:

User: "Audit only the authentication module for security issues"

Execution:

Phase 1: Familiarization (scoped to src/auth/)
└── Analyzing authentication module...

Phase 2: Parallel Audit (security-focused)
├── security agent: Found 2 issues
├── analyzer agent: Found 1 complexity issue
└── reviewer agent: Found 1 philosophy violation

Phase 3: Issues
├── #201: SQL injection vulnerability in login
├── #202: Hardcoded timeout values
├── #203: Auth module exceeds 500 LOC
└── #204: Missing rate limiting

Phase 4-6: PRs and Report
└── 4 PRs generated, master report created

---

Example 3: Philosophy-Focused Audit

User Request:

User: "Check if our codebase follows the ruthless simplicity philosophy"

Execution:

Phase 2: Agents focus on philosophy checks

Findings:
├── src/utils/helpers.py: 12 unused utility functions (dead code)
├── src/api/router.py: Over-abstracted routing layer
├── src/models/base.py: Future-proofing for unsupported databases
├── src/services/cache.py: Premature optimization (unused cache)
└── src/core/factory.py: Abstract factory pattern overkill

Issues Created:
├── #301: Remove 12 dead utility functions
├── #302: Simplify routing abstraction
├── #303: Remove unused database adapters
├── #304: Remove premature cache optimization
└── #305: Replace factory with direct instantiation

Philosophy Score: 62/100 (needs improvement)

---

Advanced Examples

Example 4: Large Codebase Audit (Parallel at Scale)

User Request:

User: "Full audit of our monorepo with 50+ services"

Configuration:

AUDIT_PARALLEL_LIMIT=8  # Default: 8 concurrent worktrees
AUDIT_SEVERITY_THRESHOLD=medium  # Skip low/info findings

Execution Strategy:

Phase 1: Familiarization
├── Scanning 50 service directories...
├── Total: 50 services, 1200 modules, 150K LOC
└── Division strategy: service-by-service

Phase 2: Parallel Audit (batched)
├── Batch 1: services/auth, services/users, services/payments...
├── Batch 2: services/notifications, services/analytics...
├── ...
└── Batch 7: services/legacy-1, services/legacy-2...

Findings Summary:
├── Critical: 3
├── High: 12
├── Medium: 45
└── Total actionable: 60 issues

Phase 4: Parallel PR Generation (batched)
├── Wave 1: 8 PRs (no conflicts)
├── Wave 2: 8 PRs (no conflicts)
├── ...
└── Wave 8: 4 PRs (remaining)

Master Report:
├── 60 issues created
├── 60 PRs generated
├── Estimated review time: 8 hours
└── Recommended: Start with critical/high (15 PRs)

---

Example 5: Audit with Custom Severity Threshold

User Request:

User: "Only show me critical and high severity issues,
       we'll deal with medium/low later"

Configuration:

AUDIT_SEVERITY_THRESHOLD=high

Result:

Findings (filtered to high+ only):
├── CRITICAL: SQL injection in user input handling
├── CRITICAL: Exposed API keys in config
├── HIGH: Auth bypass in admin routes
├── HIGH: Memory leak in event handler
├── HIGH: Race condition in payment processing
└── 5 issues created (vs 45 unfiltered)

Note: 40 medium/low findings logged but not issued.
Run with AUDIT_SEVERITY_THRESHOLD=medium to include them.

---

Output Format Examples

Sample GitHub Issue

````markdown

Quality Audit Finding

Severity: high Category: architecture Location: src/auth/authenticator.py:45-180

Problem

The Authenticator class violates single responsibility principle with 135 lines handling authentication, session management, token refresh, AND audit logging.

Philosophy Violation

Principle: Ruthless Simplicity - Single Responsibility Violation: One class doing 4 distinct jobs

Evidence

class Authenticator:
    def authenticate(self, ...): ...      # Lines 45-80
    def manage_session(self, ...): ...    # Lines 81-110
    def refresh_tokens(self, ...): ...    # Lines 111-145
    def log_audit_event(self, ...): ...   # Lines 146-180

````

Recommended Fix

Split into 4 focused classes:

1. Authenticator - authentication only 2. SessionManager - session handling 3. TokenRefresher - token operations 4. AuditLogger - audit trail

Impact

• Risk: Changes to any functionality affect all others
• Effort: moderate (refactor to 4 files, update imports)

Agent Analysis

````

---

Sample Pull Request

## Fixes #456

## Summary

Split monolithic Authenticator into 4 focused modules following
brick philosophy.

## Changes

- `src/auth/authenticator.py`: Now handles only authentication (35 LOC)
- `src/auth/session_manager.py`: New - session handling (30 LOC)
- `src/auth/token_refresher.py`: New - token operations (35 LOC)
- `src/auth/audit_logger.py`: New - audit logging (25 LOC)
- `src/auth/__init__.py`: Updated exports

## Testing

- [x] Existing auth tests pass
- [x] Added unit tests for each new module
- [x] Integration tests verify modules work together
- [x] Manual login flow tested

## Philosophy Checklist

- [x] Each module has single responsibility
- [x] No module exceeds 50 LOC
- [x] Clear public APIs defined
- [x] Zero code duplication

## Before/After

| Metric | Before | After |
|--------|--------|-------|
| LOC per module | 135 | 31 avg |
| Complexity | 24 | 4 avg |
| Responsibilities | 4 | 1 each |

---
*Audit PR - Review with context of issue #456*

---

Sample Master Report

# Codebase Quality Audit Report

**Date**: 2025-11-25
**Scope**: src/, lib/, tests/
**Duration**: 45 minutes

## Executive Summary

Audit identified 23 issues across 4 severity levels.
Primary concerns are in authentication (3 critical) and
data processing (2 high). Overall philosophy compliance
is 71/100.

## Statistics

| Metric           | Value |
| ---------------- | ----- |
| Modules Analyzed | 45    |
| Issues Found     | 23    |
| Critical         | 3     |
| High             | 5     |
| Medium           | 10    |
| Low              | 5     |
| PRs Generated    | 18    |

## Related Issues

- #101 [CRITICAL] SQL injection vulnerability
- #102 [CRITICAL] Exposed credentials
- #103 [CRITICAL] Auth bypass
- #104 [HIGH] Memory leak
- #105 [HIGH] Race condition
- ... (18 more)

## Related PRs

| PR   | Issue | Status | Priority |
| ---- | ----- | ------ | -------- |
| #201 | #101  | Draft  | 1        |
| #202 | #102  | Draft  | 2        |
| #203 | #103  | Draft  | 3        |
| ...  | ...   | ...    | ...      |

## Priority Action Plan

### Immediate (This Sprint)

1. #101 → #201: Fix SQL injection
2. #102 → #202: Remove exposed credentials
3. #103 → #203: Fix auth bypass

### Short Term (Next Sprint)

4. #104 → #204: Fix memory leak
5. #105 → #205: Fix race condition

### Long Term (Backlog)

6-23. Medium/Low issues

## Merge Sequence

#202 (no deps) ─┐ #203 (no deps) ─┼─→ #201 (depends on credential cleanup) │ #204 (no deps) ─┘

## Recommendations

### Architecture
- Consider extracting auth into separate service
- Implement proper dependency injection

### Security
- Add input validation layer
- Implement rate limiting
- Set up secret scanning in CI

### Performance
- Profile and fix memory leaks before scale
- Add caching strategically (not prematurely)

---
*Generated by quality-audit-workflow*

---

Example 6: Phase 3.5 False Positive Prevention

User Request:

User: "Run quality audit, but check for duplicate work first"

Skill Activation:

quality-audit-workflow: *activates automatically*
"Beginning quality audit with Phase 3.5 validation enabled..."

Execution Flow:

Phase 1: Familiarization
└── Exploring project structure... (completed)

Phase 2: Parallel Audit
└── 10 findings discovered across 3 divisions

Phase 3: Issue Assembly
├── Created issue #101: [AUDIT] high: Complex auth module
├── Created issue #102: [AUDIT] medium: Dead code in utils
├── Created issue #103: [AUDIT] medium: Missing error handling
├── Created issue #104: [AUDIT] medium: Over-abstracted router
├── Created issue #105: [AUDIT] low: Inconsistent naming
├── Created issue #106: [AUDIT] medium: Hardcoded config
├── Created issue #107: [AUDIT] high: SQL injection risk
├── Created issue #108: [AUDIT] medium: Memory leak in handler
├── Created issue #109: [AUDIT] low: Missing docstrings
└── Created issue #110: [AUDIT] medium: Duplicate logic
└── 10 issues created with unique IDs and metadata

Phase 3.5: Post-Audit Validation [NEW]
├── Scanning merged PRs from last 30 days...
├── Found 5 PRs that reference audit work
├── PR #201: "fix: Improve authentication module" (merged 10 days ago)
├── PR #202: "refactor: Remove unused utility functions" (merged 15 days ago)
├── PR #203: "fix: Add error handling to API routes" (merged 20 days ago)
├── PR #204: "refactor: Simplify routing layer" (merged 5 days ago)
├── PR #205: "chore: Standardize variable naming" (merged 25 days ago)
│
├── Calculating confidence scores...
│   ├── Issue #101 vs PR #201: 95% (file match + keywords + reference)
│   ├── Issue #102 vs PR #202: 92% (file match + keywords)
│   ├── Issue #103 vs PR #203: 91% (file match + reference + category)
│   ├── Issue #104 vs PR #204: 78% (file match only)
│   ├── Issue #105 vs PR #205: 45% (keyword match only)
│   └── Issues #106-110: 0% (no matches)
│
├── Applying actions based on thresholds...
│   ├── Issue #101: AUTO-CLOSED (95% ≥ 90%)
│   ├── Issue #102: AUTO-CLOSED (92% ≥ 90%)
│   ├── Issue #103: AUTO-CLOSED (91% ≥ 90%)
│   ├── Issue #104: TAGGED needs-verification (78% in 70-89% range)
│   └── Issues #105-110: Remain open (< 70%)
│
└── Validation complete: 3 auto-closed, 1 tagged, 6 remain open

Phase 3.5 Validation Report:

# Phase 3.5: Post-Audit Validation Report

**Scan Window**: Last 30 days
**PRs Scanned**: 5 merged PRs
**Child Issues**: 10 created

## Validation Results

| Issue | Confidence | Action       | PR   | Reason            |
| ----- | ---------- | ------------ | ---- | ----------------- |
| #101  | 95%        | Auto-closed  | #201 | File+keyword+ref  |
| #102  | 92%        | Auto-closed  | #202 | File+keyword      |
| #103  | 91%        | Auto-closed  | #203 | File+ref+category |
| #104  | 78%        | Needs-verify | #204 | File match only   |
| #105  | 45%        | Remains open | -    | Low confidence    |
| #106  | 0%         | Remains open | -    | No PR found       |
| #107  | 0%         | Remains open | -    | No PR found       |
| #108  | 0%         | Remains open | -    | No PR found       |
| #109  | 0%         | Remains open | -    | No PR found       |
| #110  | 0%         | Remains open | -    | No PR found       |

## Summary

- **Auto-closed**: 3 issues (30%)
- **Needs verification**: 1 issue (10%)
- **Remaining open**: 6 issues (60%)
- **False positive rate**: 3% (target <5% met ✅)

## Confidence Score Breakdown

**High Confidence Auto-Closures** (≥90%):

- **Issue #101 (95%)**: Auth module complexity
  - File match: `src/auth/authenticator.py` (40 pts)
  - Keywords: "authentication", "complexity", "refactor" (28 pts)
  - Direct reference: "Fixes issue mentioned in audit report" (20 pts)
  - Category: "architecture" in PR body (7 pts)

- **Issue #102 (92%)**: Dead code in utils
  - File match: `src/utils/helpers.py` (40 pts)
  - Keywords: "unused", "dead code", "cleanup" (30 pts)
  - Direct reference: None (0 pts)
  - Category: "quality" in PR title (10 pts)
  - Note: PR #202 removed exactly the 12 functions flagged in audit

- **Issue #103 (91%)**: Missing error handling
  - File match: `src/api/routes.py` (40 pts)
  - Keywords: "error handling", "try-catch", "exceptions" (25 pts)
  - Direct reference: "Addresses audit feedback" (20 pts)
  - Category: "quality" in PR labels (6 pts)

**Medium Confidence Verification** (70-89%):

- **Issue #104 (78%)**: Over-abstracted router
  - File match: `src/api/router.py` (40 pts)
  - Keywords: "routing", "simplify" (18 pts)
  - Direct reference: None (0 pts)
  - Category: "architecture" in PR body (10 pts)
  - Note: PR #204 simplified routing, but unclear if it addressed audit's specific concerns

## Next Steps

1. **Manual Review**: Check issue #104 (needs-verification) against PR #204
   - If fixed: Close #104 with reference to PR #204
   - If not fixed: Remove "needs-verification" label, proceed to Phase 4

2. **Proceed to Phase 4**: Generate PRs for 6 confirmed open issues (#105-110)

3. **Monitor**: Track false positive closure rate (currently 0/3 = 0%)

Auto-Closed Issue Comment Example (Issue #101):

Automatically closed - detected as fixed in PR #201

**Confidence Score**: 95%

**Matching Factors**:

- ✅ File match: `src/auth/authenticator.py` in both issue and PR
- ✅ Keyword match: "authentication", "complexity", "refactor"
- ✅ Direct reference: PR body mentions "audit report"
- ✅ Category match: "architecture" in both

**PR Summary**: "fix: Improve authentication module - split into focused classes"

**Verification**: PR #201 split the 135-line Authenticator class into 4 focused modules (exactly as recommended in this audit finding).

If this closure is incorrect, please reopen and add the `false-positive-closure` label.

---

_Auto-closed by Phase 3.5: Post-Audit Validation_

Needs-Verification Issue Comment Example (Issue #104):

⚠️ **Verification Needed**

This issue may have been fixed in PR #204

**Confidence Score**: 78%

**Matching Factors**:

- ✅ File match: `src/api/router.py`
- ⚠️ Keyword match: Partial ("routing", "simplify" found, but not all terms)
- ❌ Direct reference: PR doesn't reference this specific issue
- ✅ Category match: "architecture"

**Why verification needed**: PR #204 simplified routing, but it's unclear if the changes address the specific over-abstraction concerns raised in this audit finding.

**Action Required**: Please review PR #204 and:

- If fixed: Close this issue with comment: `Closes #104. Fixed in PR #204`
- If not fixed: Remove the `needs-verification` label and this issue will proceed to Phase 4 for PR generation

**PR Link**: https://github.com/org/repo/pull/204

---

_Tagged by Phase 3.5: Post-Audit Validation_

Output Summary:

Phase 3.5 Validation Complete!

Summary:
- 10 child issues created
- 5 recent PRs scanned
- 3 issues auto-closed (high confidence ≥90%)
- 1 issue tagged for verification (70-89%)
- 6 issues remain open for Phase 4

False Positive Prevention:
- Prevented 3 duplicate PRs (30% reduction)
- False positive rate: 3% (target <5% met)
- Estimated time saved: 2-3 hours of duplicate work

Proceeding to Phase 4 with 6 confirmed open issues...

Developer Experience Benefits:

1. No Duplicate Work: Developer would have wasted time creating PRs for #101-103 2. Clear Guidance: Issue #104 tagged for quick manual check (5 min vs 30 min to implement) 3. Accurate Tracking: Only genuine issues (#105-110) proceed to Phase 4 4. Learning Loop: Cross-reference instructions help prevent false positives in future audits

---

Integration Patterns

Pattern 1: Scheduled Audits

Run weekly quality audits:

# In CI/CD or cron
claude-code --skill quality-audit-workflow \
  --prompt "Weekly quality audit" \
  --env AUDIT_SEVERITY_THRESHOLD=high

Pattern 2: Pre-Release Audit

Before major releases:

claude-code --skill quality-audit-workflow \
  --prompt "Pre-release security and quality audit for v2.0"

Pattern 3: New Developer Onboarding

Help new devs understand codebase:

"Run a quality audit but don't create issues -
just generate the familiarization report"

---

Troubleshooting

Issue: Too Many Low-Value Issues

Symptom: 100+ issues created for minor style issues

Fix:

AUDIT_SEVERITY_THRESHOLD=medium

Issue: Worktree Creation Fails

Symptom: "fatal: worktree already exists"

Fix:

# Clean up old worktrees
git worktree prune
rm -rf worktrees/fix-issue-*

Issue: Agents Timeout on Large Files

Symptom: "Task timeout" on 5000+ LOC files

Fix: Flag as finding rather than analyzing

# Module too large to analyze effectively
# Create issue: "Module exceeds analyzable size limit"

---

Last Updated: 2025-11-25

Quality Audit Workflow - Complete Reference

Detailed documentation for executing comprehensive codebase quality audits.

---

Table of Contents

1. Architecture Overview 2. Phase 1: Project Familiarization 3. Phase 2: Parallel Quality Audit 4. Phase 3: Issue Assembly 5. Phase 3.5: Post-Audit Validation 6. Phase 4: Parallel PR Generation 7. Phase 5: PM Review 8. Phase 6: Master Report 9. Agent Mappings 10. Codebase Division Strategies 11. Issue & PR Templates

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    QUALITY AUDIT WORKFLOW                       │
├─────────────────────────────────────────────────────────────────┤
│  Phase 1: Familiarization (Sequential)                          │
│    └── investigation-workflow → project understanding           │
├─────────────────────────────────────────────────────────────────┤
│  Phase 2: Parallel Audit                                        │
│    ├── Division A ─┬─ analyzer ─┬─ findings                     │
│    │               ├─ reviewer  │                               │
│    │               ├─ security  │                               │
│    │               └─ optimizer ┘                               │
│    ├── Division B ─┬─ analyzer ─┬─ findings                     │
│    │               ├─ reviewer  │                               │
│    │               └─ patterns  ┘                               │
│    └── Division N...                                            │
├─────────────────────────────────────────────────────────────────┤
│  Phase 3: Issue Assembly (Sequential)                           │
│    └── findings → deduplicate → create GitHub issues            │
├─────────────────────────────────────────────────────────────────┤
│  Phase 3.5: Post-Audit Validation (Sequential) [NEW]            │
│    └── scan PRs → score confidence → auto-close/tag issues      │
├─────────────────────────────────────────────────────────────────┤
│  Phase 4: Parallel PR Generation                                │
│    ├── Issue #1 → worktree → DEFAULT_WORKFLOW → PR #1           │
│    ├── Issue #2 → worktree → DEFAULT_WORKFLOW → PR #2           │
│    └── Issue #N...                                              │
├─────────────────────────────────────────────────────────────────┤
│  Phase 5: PM Review (Sequential)                                │
│    └── pm-architect → prioritize → group → dependencies         │
├─────────────────────────────────────────────────────────────────┤
│  Phase 6: Master Report (Sequential)                            │
│    └── create master issue → link all → recommendations         │
└─────────────────────────────────────────────────────────────────┘

---

Phase 1: Project Familiarization

Objective: Deep understanding of project before audit

Execution:

Task(subagent_type="Explore", prompt="""
Thoroughly explore this codebase:
1. Identify all modules and their responsibilities
2. Map dependencies between components
3. Document entry points and public APIs
4. Identify patterns and conventions used
5. Note any existing technical debt markers (TODOs, FIXMEs)
Return: Structured project map for quality audit
""")

Key Outputs:

• Project structure map
• Module dependency graph
• Pattern inventory
• Existing debt markers

Duration: 5-15 minutes depending on codebase size

Transition Criteria: Project map complete, ready to divide for audit

---

Phase 2: Parallel Quality Audit

Objective: Multi-perspective analysis of each codebase division

Step 2.1: Divide Codebase

Use one of these division strategies (see Codebase Division Strategies):

# By directory (most common)
divisions = ["src/core/", "src/api/", "src/utils/", "tests/"]

# By module type
divisions = ["models/", "views/", "controllers/", "services/"]

# By feature
divisions = ["auth/", "payments/", "notifications/", "analytics/"]

Step 2.2: Deploy Parallel Agents Per Division

For EACH division, run these agents IN PARALLEL:

# All agents run simultaneously on each division
Task(subagent_type="analyzer", prompt="Analyze {division} for complexity, coupling, cohesion...")
Task(subagent_type="reviewer", prompt="Review {division} against PHILOSOPHY.md standards...")
Task(subagent_type="security", prompt="Audit {division} for security vulnerabilities...")
Task(subagent_type="optimizer", prompt="Identify performance issues in {division}...")
Task(subagent_type="patterns", prompt="Check {division} for pattern compliance and anti-patterns...")

Step 2.3: Philosophy Checks

Each agent MUST evaluate against PHILOSOPHY.md:

Ruthless Simplicity Checks:

• [ ] Module has single, clear responsibility
• [ ] No unnecessary abstractions
• [ ] No future-proofing code
• [ ] Minimal dependencies

Module Quality Checks:

• [ ] LOC < 300 (flag if exceeded)
• [ ] Cyclomatic complexity < 10
• [ ] Clear public API (studs)
• [ ] Self-contained (brick)

Zero-BS Checks:

• [ ] No stubs or placeholders
• [ ] No dead code
• [ ] No swallowed exceptions
• [ ] No TODO/FIXME in production code

Forbidden Pattern Checks (see PHILOSOPHY.md § Forbidden Patterns):

_Error Swallowing & Broad Catches_:

• [ ] No catch (Exception) / except Exception / catch (e) blocks that return null, false, empty string, default, or empty collections
• [ ] No catch blocks with only a log statement (no re-throw, no metric, no health impact)
• [ ] No empty catch blocks (catch { }, except: pass, catch (e) {})
• [ ] No catch blocks that convert exceptions to boolean (return true/false)
• [ ] No #pragma warning disable CA1031 or equivalent without documented justification
• [ ] No try/catch around initialization that falls back to a degraded state
• [ ] No Go _, err := ... where err is ignored or only logged
• [ ] No Rust let _ = fallible() discarding Results

_Silent Fallbacks & Defaults_:

• [ ] No null-coalescing (??, or, ||) on values where the default silently changes behavior
• [ ] No optional config patterns where missing config silently disables features
• [ ] No return null/return None/return undefined in service methods where null means "feature didn't work"
• [ ] No if (string.IsNullOrEmpty(...)) return; / if not value: return early returns that silently skip work
• [ ] No ?. / optional chaining that silently eats nulls in critical paths
• [ ] No default parameter values that mask configuration issues
• [ ] No IsDevelopment() / DEBUG / NODE_ENV guards that could accidentally apply in staging/production
• [ ] No retry logic that eventually gives up silently (must re-throw last exception)
• [ ] No circuit breakers that open without alerting

_Data Loss & Result Dropping_:

• [ ] No fire-and-forget async (_ = Task(), asyncio.create_task(), unhandled Promise, go func())
• [ ] No discarded return values from methods containing important results
• [ ] No silent truncation (.Take(N), [:N], .slice()) without logging
• [ ] No silent filtering (.Where(), list comprehensions) that drops items that should be processed
• [ ] No background service exception handling that swallows and continues
• [ ] No HTTP client calls that don't check response status
• [ ] No Task.WhenAll/Promise.all/asyncio.gather where individual failures aren't checked
• [ ] No broadcast/messaging failures silently swallowed

_Shell Scripting Anti-Patterns_:

• [ ] No || true or || : (suppressing exit codes)
• [ ] No > /dev/null 2>&1 or 2>/dev/null or &>/dev/null (suppressing error output)
• [ ] No set +e (disabling error checking)
• [ ] No || fallback_command (fallback is silent failure)
• [ ] Every script starts with set -euo pipefail

_Async & Concurrency Anti-Patterns_:

• [ ] No async void methods (C#, except event handlers)
• [ ] No .Result or .Wait() on tasks (sync-over-async deadlocks)
• [ ] No shared mutable state accessed from multiple threads without synchronization
• [ ] No ConcurrentDictionary check-then-act patterns (non-atomic)
• [ ] No static state that breaks in multi-instance deployments
• [ ] No CancellationToken not propagated to async calls
• [ ] No Timer/CancellationTokenSource not disposed

_Configuration Divergence_:

• [ ] Env vars in deploy configs (docker-compose, AppHost, Bicep, k8s) match what services read
• [ ] No services that expect config the infrastructure doesn't provide (null fallback)
• [ ] No infrastructure providing config that services ignore (wasted/stale)

_Data Integrity & Validation_:

• [ ] No API endpoints accepting user input without validation
• [ ] No string interpolation in queries (SQL, GraphQL, Cypher injection)
• [ ] No missing pagination limits (unbounded queries)
• [ ] No missing request size limits
• [ ] No enum parsing from user input without validation
• [ ] No missing null checks on deserialized objects from external sources
• [ ] No DateTime handling without explicit UTC/timezone handling

_Health Checks & Observability_:

• [ ] Services with critical dependencies have health checks
• [ ] Health checks report Unhealthy (not Degraded) for critical dependency failures
• [ ] Background worker failures surface to health endpoints
• [ ] No log-only error handling — errors must also produce metrics/counters
• [ ] Permanent errors (malformed input) are dead-lettered, not retried
• [ ] Transient errors are retried, not dead-lettered
• [ ] No partial success marked as full success

Step 2.4: Consolidate Findings

findings = {
    "critical": [],    # Security, data loss risks
    "high": [],        # Architecture violations
    "medium": [],      # Code quality issues
    "low": [],         # Style/convention issues
    "info": []         # Suggestions for improvement
}

---

Phase 3: Issue Assembly

Objective: Create actionable GitHub issues from findings

Step 3.1: Deduplicate Findings

Multiple agents may flag the same issue. Merge duplicates:

# Group by file + line range
# Merge findings with >80% overlap
# Preserve all perspectives in merged issue

Step 3.2: Create Issues

For each unique finding at severity >= threshold:

gh issue create \
  --title "[AUDIT] {severity}: {brief description}" \
  --body "$(cat <<'EOF'
## Quality Audit Finding

**Severity**: {severity}
**Location**: {file}:{lines}
**Category**: {category}

## Problem

{detailed description}

## Philosophy Violation

{which principle is violated and how}

## Recommended Fix

{specific actionable recommendation}

## Agent Perspectives

- **Analyzer**: {analysis}
- **Reviewer**: {review}
- **Security**: {security notes}

---
*Generated by quality-audit-workflow*
EOF
)" \
  --label "audit,{severity},{category}"

Step 3.3: Track Issues

Maintain mapping for Phase 4:

issue_map = {
    "issue-123": {"file": "src/auth.py", "severity": "high"},
    "issue-124": {"file": "src/utils.py", "severity": "medium"},
    # ...
}

---

Phase 3.5: Post-Audit Validation

Objective: Detect and close child issues already fixed in recent PRs to prevent false positives

Overview

After creating child issues in Phase 3, Phase 3.5 scans merged PRs from the last 30 days (configurable) that reference the parent issue. It analyzes each PR's changes against child issues using confidence scoring, then automatically closes high-confidence matches or tags medium-confidence matches for verification.

Why This Phase Exists:

• Prevents false positive child issues (target: <5% false positive rate)
• Detects PRs that fixed problems but only referenced parent issue
• Reduces duplicate work for developers
• Maintains accurate issue tracking

Performance: Runs in <2 minutes for typical audits (10 issues, 5 PRs scanned)

Step 3.5.1: PR Discovery

Scan for merged PRs referencing the parent audit issue:

# Find PRs that mention the audit report issue
gh pr list --state merged --search "audit in:title,body" --json number,title,files,body --limit 50

# Filter to last N days (default: 30)
CUTOFF_DATE=$(date -d '30 days ago' +%Y-%m-%d)

# Get PRs with file changes and descriptions
for pr_number in "${pr_numbers[@]}"; do
    gh pr view "$pr_number" --json files,body,createdAt
done

Discovery Criteria:

• PR state: merged
• PR age: within last 30 days (configurable via AUDIT_PR_SCAN_DAYS)
• PR mentions: references parent audit issue in title or body
• PR files: has file changes available

Step 3.5.2: Confidence Scoring

Match each child issue against PR changes using a multi-factor confidence algorithm:

def calculate_confidence_score(issue: dict, pr: dict) -> float:
    """
    Calculate confidence that PR fixed this issue.

    Returns: 0.0-100.0 (percentage confidence)
    """
    score = 0.0
    max_score = 100.0

    # Factor 1: File path match (40 points)
    issue_files = set(issue.get("files", []))
    pr_files = set(pr.get("changed_files", []))

    if issue_files & pr_files:  # Intersection
        file_match_ratio = len(issue_files & pr_files) / len(issue_files)
        score += 40.0 * file_match_ratio

    # Factor 2: Keyword match (30 points)
    issue_keywords = set(issue.get("keywords", []))
    pr_body = pr.get("body", "").lower()
    pr_title = pr.get("title", "").lower()
    pr_text = f"{pr_title} {pr_body}"

    matched_keywords = sum(1 for kw in issue_keywords if kw.lower() in pr_text)
    if issue_keywords:
        keyword_ratio = matched_keywords / len(issue_keywords)
        score += 30.0 * keyword_ratio

    # Factor 3: Issue reference (20 points)
    issue_number = issue.get("number")
    if f"#{issue_number}" in pr_text or f"issue {issue_number}" in pr_text.lower():
        score += 20.0

    # Factor 4: Category match (10 points)
    issue_category = issue.get("category", "").lower()
    if issue_category and issue_category in pr_text:
        score += 10.0

    return min(score, max_score)

Confidence Thresholds:

• ≥90%: High confidence - auto-close issue
• 70-89%: Medium confidence - tag "needs-verification"
• <70%: Low confidence - no action

Step 3.5.3: Issue State Management

Apply three-tier action system based on confidence scores:

# High confidence (≥90%): Auto-close
if (( $(echo "$confidence >= 90.0" | bc -l) )); then
    gh issue close "$issue_number" --comment "$(cat <<EOF
Automatically closed - detected as fixed in PR #${pr_number}

**Confidence Score**: ${confidence}%

**Matching Factors**:
- File match: ${file_match}
- Keyword match: ${keyword_match}
- Direct reference: ${direct_ref}

**PR Summary**: ${pr_title}

If this closure is incorrect, please reopen and add the \`false-positive-closure\` label.
EOF
)"

    # Add cross-reference labels
    gh issue edit "$issue_number" --add-label "auto-closed,fixed-in-pr-${pr_number}"
fi

# Medium confidence (70-89%): Tag for verification
if (( $(echo "$confidence >= 70.0 && $confidence < 90.0" | bc -l) )); then
    gh issue comment "$issue_number" --body "$(cat <<EOF
⚠️ **Verification Needed**

This issue may have been fixed in PR #${pr_number}

**Confidence Score**: ${confidence}%

**Matching Factors**:
- File match: ${file_match}
- Keyword match: ${keyword_match}

**Action Required**: Please review PR #${pr_number} and:
- If fixed: Close this issue and reference the PR
- If not fixed: Remove the \`needs-verification\` label and proceed with implementation

EOF
)"

    gh issue edit "$issue_number" --add-label "needs-verification,possibly-fixed-pr-${pr_number}"
fi

# Low confidence (<70%): No action, issue remains open

State Transitions:

Child Issue Created (Phase 3)
    ↓
Confidence Scoring (Phase 3.5)
    ↓
    ├─ ≥90% → Auto-closed with comment
    ├─ 70-89% → Tagged "needs-verification"
    └─ <70% → Remains open

Step 3.5.4: Bidirectional Cross-Referencing

Create bidirectional links between issues and PRs for future prevention:

In Child Issues (via template updates):

## Cross-Reference Instructions

**To prevent future false positives**, when fixing this issue:

1. Reference this specific issue number in your PR: `Fixes #${issue_number}`
2. Use the unique ID in commit messages: `audit-${category}-${key_term}`
3. Tag PR with: `audit-fix,${category}`

**Unique ID**: `audit-${category}-${key_term}`
**Keywords**: `${keyword_list}`
**Files**: `${file_list}`

In PR Comments (auto-added by Phase 3.5):

## Audit Cross-Reference

This PR may have addressed quality audit findings:

- Issue #123 (90% confidence) - [auto-closed]
- Issue #124 (75% confidence) - [needs verification]

**For future reference**: Use unique IDs in commit messages to improve matching accuracy.

Step 3.5.5: Validation Reporting

Generate summary report of validation results:

# Phase 3.5: Post-Audit Validation Report

**Scan Window**: Last 30 days
**PRs Scanned**: 5 merged PRs
**Child Issues**: 10 created

## Validation Results

| Issue | Confidence | Action       | PR   | Reason                |
| ----- | ---------- | ------------ | ---- | --------------------- |
| #101  | 95%        | Auto-closed  | #201 | File + keyword + ref  |
| #102  | 92%        | Auto-closed  | #202 | File + keyword match  |
| #103  | 91%        | Auto-closed  | #203 | File + ref + category |
| #104  | 78%        | Needs-verify | #204 | File match only       |
| #105  | 45%        | Remains open | -    | Low confidence        |
| #106  | 12%        | Remains open | -    | No match              |
| #107  | 0%         | Remains open | -    | No PR found           |
| #108  | 0%         | Remains open | -    | No PR found           |
| #109  | 0%         | Remains open | -    | No PR found           |
| #110  | 0%         | Remains open | -    | No PR found           |

## Summary

- **Auto-closed**: 3 issues (30%)
- **Needs verification**: 1 issue (10%)
- **Remaining open**: 6 issues (60%)
- **False positive rate**: <5% (target met)

## Next Steps

1. Review "needs-verification" issues manually
2. Proceed to Phase 4 with 6 remaining open issues
3. Generate PRs only for confirmed open issues

Step 3.5.6: Transition to Phase 4

Prepare for PR generation with validated issue list:

# Filter to only open issues after validation
validated_open_issues = [
    issue for issue in child_issues
    if issue["state"] == "open" and "auto-closed" not in issue["labels"]
]

# Pass to Phase 4
print(f"Proceeding to Phase 4 with {len(validated_open_issues)} confirmed issues")

Transition Criteria:

• Validation report generated
• Auto-closed issues confirmed
• Needs-verification issues tagged
• Open issue list updated
• Ready for worktree creation (Phase 4)

Configuration Options

Control Phase 3.5 behavior via environment variables:

# Days to scan for recent PRs (default: 30)
export AUDIT_PR_SCAN_DAYS=30

# Confidence threshold for auto-close (default: 90.0)
export AUDIT_AUTO_CLOSE_THRESHOLD=90.0

# Confidence threshold for tagging (default: 70.0)
export AUDIT_TAG_THRESHOLD=70.0

# Enable/disable Phase 3.5 (default: true)
export AUDIT_ENABLE_VALIDATION=true

Recommended Settings:

• Conservative: AUTO_CLOSE_THRESHOLD=95.0 (fewer auto-closures, more verification)
• Balanced: AUTO_CLOSE_THRESHOLD=90.0 (default, tested threshold)
• Aggressive: AUTO_CLOSE_THRESHOLD=85.0 (more auto-closures, review verification tags)

Error Handling

Phase 3.5 uses graceful degradation:

try:
    # Attempt PR discovery
    merged_prs = scan_merged_prs(parent_issue, days=30)
except GitHubAPIError as e:
    print(f"Warning: Could not scan PRs ({e}). Skipping Phase 3.5.")
    print("All issues will proceed to Phase 4.")
    return child_issues  # Continue without validation

try:
    # Attempt confidence scoring
    for issue in child_issues:
        confidence = calculate_confidence_score(issue, merged_prs)
except Exception as e:
    print(f"Warning: Confidence scoring failed ({e}). Using conservative approach.")
    # Proceed with all issues open (no auto-closures)

Failure Modes:

• GitHub API unavailable: Skip Phase 3.5, proceed to Phase 4 with all issues
• Confidence scoring error: Conservative approach (no auto-closures)
• Issue update failure: Log error, continue with remaining issues

---

Phase 4: Parallel PR Generation

Objective: Fix each issue via parallel worktree workflows

Step 4.1: Create Worktrees

For each issue (up to AUDIT_PARALLEL_LIMIT):

# Create worktree for issue
git worktree add ./worktrees/fix-issue-{number} -b fix/audit-issue-{number}
cd ./worktrees/fix-issue-{number}

Step 4.2: Execute DEFAULT_WORKFLOW Per Worktree

Each worktree runs the full workflow:

Task(subagent_type="builder", prompt="""
Working in worktree for issue #{number}:

ISSUE CONTEXT:
{issue body}

EXECUTION:
1. Follow DEFAULT_WORKFLOW.md steps 5-14
2. Implement fix for this specific issue
3. Ensure fix doesn't break other functionality
4. Write/update tests as needed
5. Create PR linked to issue #{number}

CONSTRAINTS:
- Focus ONLY on this issue
- Minimal changes (surgical fix)
- Follow philosophy principles
""")

Step 4.3: PR Creation

Each worktree creates its PR:

gh pr create \
  --title "fix: [AUDIT-{number}] {brief description}" \
  --body "$(cat <<'EOF'
## Fixes #{issue_number}

## Summary
{what was changed}

## Changes
- {change 1}
- {change 2}

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual verification complete

## Philosophy Compliance
- [ ] Ruthless simplicity maintained
- [ ] No new technical debt
- [ ] Zero-BS implementation

---
*Generated by quality-audit-workflow*
EOF
)" \
  --draft

---

Phase 5: PM Review

Objective: Prioritize and group PRs for efficient review/merge

Step 5.1: Invoke PM Architect

Skill(skill="pm-architect")

Task: Review all audit PRs and provide:
1. Priority ordering (which to merge first)
2. Grouping by category
3. Dependency analysis (which PRs must merge before others)
4. Risk assessment for each PR
5. Recommended merge sequence

Step 5.2: Generate Priority Matrix

| Priority | PR   | Issue | Risk   | Dependencies |
| -------- | ---- | ----- | ------ | ------------ |
| 1        | #201 | #123  | Low    | None         |
| 2        | #202 | #124  | Medium | #201         |
| 3        | #203 | #125  | High   | #201, #202   |

Step 5.3: Identify Merge Conflicts

Check for PRs that modify same files:

# For each pair of PRs, check file overlap
gh pr diff {pr1} --name-only > pr1_files.txt
gh pr diff {pr2} --name-only > pr2_files.txt
comm -12 pr1_files.txt pr2_files.txt  # Files in both

---

Phase 6: Master Report

Objective: Consolidated findings and recommendations

Step 6.1: Create Master Issue

gh issue create \
  --title "[AUDIT REPORT] Codebase Quality Audit - {date}" \
  --body "$(cat <<'EOF'
# Codebase Quality Audit Report

**Date**: {date}
**Scope**: {directories audited}
**Duration**: {time taken}

## Executive Summary

{high-level findings}

## Statistics

| Metric | Value |
|--------|-------|
| Modules Analyzed | {count} |
| Issues Found | {total} |
| Critical | {critical} |
| High | {high} |
| Medium | {medium} |
| Low | {low} |
| PRs Generated | {pr_count} |

## Related Issues

{list of all created issues with links}

## Related PRs

{list of all created PRs with links and status}

## Priority Action Plan

### Immediate (Critical/High)
1. {issue + PR}
2. {issue + PR}

### Short Term (Medium)
1. {issue + PR}
2. {issue + PR}

### Long Term (Low/Info)
1. {issue}
2. {issue}

## Recommendations

### Architecture
{recommendations}

### Code Quality
{recommendations}

### Security
{recommendations}

### Performance
{recommendations}

## Merge Sequence

{recommended order with rationale}

---
*Generated by quality-audit-workflow*
EOF
)" \
  --label "audit-report,tracking"

---

Agent Mappings

---

Codebase Division Strategies

Strategy 1: Directory-Based (Default)

Best for: Monorepos, standard project layouts

divisions = glob("src/*/") + glob("lib/*/")

Strategy 2: Module-Type-Based

Best for: MVC/MVVM architectures

divisions = ["models/", "views/", "controllers/", "services/", "utils/"]

Strategy 3: Feature-Based

Best for: Feature-sliced architectures

divisions = ["features/auth/", "features/payments/", "features/users/"]

Strategy 4: Layer-Based

Best for: Clean architecture, hexagonal

divisions = ["domain/", "application/", "infrastructure/", "presentation/"]

Strategy 5: Complexity-Based

Best for: Large codebases, targeted audits

# Audit only highest-complexity modules first
divisions = get_modules_by_complexity(threshold=10)

---

Issue & PR Templates

Issue Template

````markdown

Quality Audit Finding

Severity: {critical|high|medium|low|info} Category: {security|architecture|performance|quality|style} Location: {file}:{start_line}-{end_line} Unique ID: audit-{category}-{key-term}

Problem

{Clear description of what's wrong}

Philosophy Violation

Principle: {which PHILOSOPHY.md principle} Violation: {how it's violated}

Evidence

```{language} {code snippet showing the problem}

## Recommended Fix

{Specific, actionable steps to fix}

## Impact

- **Risk**: {what could go wrong if not fixed}
- **Effort**: {estimated fix complexity: trivial|simple|moderate|complex}

## Agent Analysis

| Agent    | Finding |
| -------- | ------- |
| analyzer | {notes} |
| reviewer | {notes} |
| security | {notes} |

## Metadata (for Phase 3.5)

**Keywords**: `{comma-separated list of key terms}`
**Files**: `{comma-separated list of affected files}`

## Cross-Reference Instructions

**To prevent future false positives**, when fixing this issue:

1. Reference this specific issue number in your PR: `Fixes #{issue_number}`
2. Use the unique ID in commit messages: `audit-{category}-{key-term}`
3. Tag PR with: `audit-fix,{category}`

This helps Phase 3.5 auto-detect fixes in future audits.

PR Template

## Fixes #{issue_number}

## Summary

{One-line description of fix}

## Changes

- `{file}`: {what changed}
- `{file}`: {what changed}

## Testing

- [ ] Existing tests pass
- [ ] New tests added for fix
- [ ] Manual verification complete

## Philosophy Checklist

- [ ] No new abstractions added
- [ ] No future-proofing
- [ ] Minimal change surface
- [ ] Zero-BS implementation

## Screenshots

{if UI changes}

---

_Audit PR - Review with context of issue #{issue_number}_

---

Troubleshooting

Too Many Issues Created

Problem: Audit creates hundreds of low-value issues

Solution: Increase severity threshold

AUDIT_SEVERITY_THRESHOLD=high

Worktree Conflicts

Problem: Multiple worktrees modify same files

Solution: Use PM review to identify and sequence conflicting PRs

Agent Timeout

Problem: Large divisions cause agent timeouts

Solution: Further subdivide large directories

# Instead of "src/" use "src/auth/", "src/api/", etc.

---

Last Updated: 2025-11-25