Entropy Audit (expert-entropy-auditor)

Core Philosophy

"Like a garbage collector, identify 'AI residue' scattered in the codebase and suggest consolidating them into shared utility packages." —— Harness Engineering

The entropy audit skill is specifically designed to discover the gap between "design intent" and "code implementation", identifying entropy increase points in the codebase.

Audit Dimensions

1. PRD and Code Consistency

Audit Method:

• Parse feature points in PRD documents
• Scan code implementation
• Compare feature points with implementation

Example:

PRD Feature: Display welcome message after user login
Code Implementation: Redirect to homepage directly after user login
→ Audit Result: Implementation inconsistent with PRD

2. Spec Document and Code Consistency

Audit Method:

• Parse technical specifications in Spec documents
• Check if code conforms to specifications
• Mark deviations

Example:

Spec Specification: API returns { code, data, message }
Code Implementation: API returns { status, result }
→ Audit Result: Return format does not conform to specification

3. AI Residue Detection

What is AI Residue:

• Repeatedly generated similar code
• Guessed data structures
• Inconsistent naming patterns
• Scattered helper utilities

Detection Method:

• Code similarity analysis
• Naming pattern analysis
• Duplicate code detection

Example:

File A: function formatDate(date) { ... }
File B: function formatDateString(d) { ... }
File C: function dateFormat(dateVal) { ... }
→ Audit Result: AI residue, suggest extracting to shared utility package

4. Technical Debt Accumulation

Detection Method:

• Scan TODO/FIXME/HACK comments
• Check temporary solution markers
• Count technical debt items

Example:

Technical Debt Statistics:
- TODO: 15 items
- FIXME: 3 items
- HACK: 2 items
→ Audit Result: Technical debt accumulated, suggest handling

Audit Process

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Collect   │ ──→ │   Analyze   │ ──→ │    Score    │ ──→ │   Report    │
│             │     │             │     │             │     │             │
│ • PRD Docs  │     │ • Consistency│    │ • Entropy   │     │ • Issues    │
│ • Spec Docs │     │ • Duplication│    │ • Debt Eval │     │ • Suggestions│
│ • Code Impl │     │ • Pattern    │     │ • Risk Rate │     │ • Prioritize │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Entropy Score System

Scoring Dimensions

Score Calculation

Entropy Score = 100 - (Inconsistencies × 5 + AI Residues × 3 + Tech Debts × 2)

Example:
- PRD Inconsistencies: 2 items → Deduct 10 points
- Spec Inconsistencies: 1 item → Deduct 5 points
- AI Residues: 5 items → Deduct 15 points
- Tech Debts: 10 items → Deduct 20 points

Entropy Score = 100 - (10 + 5 + 15 + 20) = 50

Status Determination

Output Format

Entropy Audit Report

# Entropy Audit Report - YYYY-MM-DD

## Entropy Score: XX/100

## Audit Scope
- PRD Documents: X
- Spec Documents: X
- Code Files: X

## Consistency Audit

### PRD and Code Inconsistencies
| PRD Feature | Code Implementation | Deviation Description |
|-----------|---------|---------|
| FP-001 User login welcome message | Not implemented | Missing welcome message display |

### Spec and Code Inconsistencies
| Spec Specification | Code Implementation | Deviation Description |
|----------|---------|---------|
| API return format | Non-compliant | Missing message field |

## AI Residue Detection

### Duplicate Code
| File A | File B | Similarity | Suggestion |
|-------|-------|-------|------|
| utils/formatDate.js | utils/dateFormat.js | 85% | Extract to shared utility package |

### Guessed Data Structures
| File | Issue | Suggestion |
|------|------|------|
| service/UserService.ts | Hardcoded field names | Define type interfaces |

## Technical Debt Statistics

| Type | Count | Average Age |
|------|------|-------------|
| TODO | 15 | 14 days |
| FIXME | 3 | 7 days |
| HACK | 2 | 30 days |

## Improvement Suggestions

### High Priority
1. Fix PRD inconsistencies (2 items)
2. Extract duplicate code to shared utility package (5 items)

### Medium Priority
1. Handle FIXME comments (3 items)
2. Define missing type interfaces (3 items)

### Low Priority
1. Clean up outdated TODOs (12 items)

Configuration Options

# entropy-auditor-config.yaml
entropy_auditor:
  # Audit scope
  scope:
    prd_paths: ["docs/prd/", "docs/业务分析/"]
    spec_paths: ["docs/specs/", "docs/dev-specs/"]
    code_paths: ["src/"]
  
  # Detection thresholds
  thresholds:
    code_similarity: 0.8      # Code similarity threshold
    max_todo_age_days: 30     # Maximum TODO age
    max_fixme_age_days: 14    # Maximum FIXME age
  
  # Scoring weights
  weights:
    prd_consistency: 0.25
    spec_consistency: 0.25
    ai_residue: 0.25
    tech_debt: 0.25

Usage Examples

Example 1: Comprehensive Entropy Audit

User: Execute technical debt audit

AI:
1. Collect PRD, Spec, code
2. Analyze consistency
3. Detect AI residue
4. Calculate entropy score
5. Generate audit report

Example 2: PRD Consistency Check

User: Check if PRD is consistent with code

AI:
1. Parse PRD feature points
2. Scan code implementation
3. Compare feature points with implementation
4. Generate deviation report

Example 3: AI Residue Detection

User: Detect AI residue in code

AI:
1. Code similarity analysis
2. Naming pattern analysis
3. Identify duplicate code
4. Suggest extracting to shared utility package

Collaboration with Other Skills

• pdd-entropy-reduction: Called as a sub-skill by the coordinator
• pdd-doc-gardener: Pass document inconsistency issues
• expert-auto-refactor: Pass refactoring suggestions
• pdd-code-reviewer: Integrate entropy checks into code review