graph TD
Start([Start: Comments Audit]) --> Scan[Phase 1: Scan
Find source files, detect language]
Scan --> Extract[Phase 2: Extract
Parse inline comments + docstrings]
Extract --> Cat1[Category 1: WHY not WHAT
Check comment intent vs code restatement]
Cat1 --> Cat2[Category 2: Density 15-20%
Calculate comment-to-code ratio]
Cat2 --> Cat3[Category 3: No Forbidden Content
Epic IDs, Task IDs, dates, history]
Cat3 --> Cat4[Category 4: Docstrings Quality
Match signatures, params, returns]
Cat4 --> Cat5[Category 5: Actuality
Comments vs code, stale references]
Cat5 --> Cat6[Category 6: Legacy Cleanup
TODO, commented code, deprecated]
Cat6 --> Score[Phase 3: Calculate Scores
X/10 per category]
Score --> Report[Phase 4: Generate Report
Findings + Recommended Actions]
Report --> Output([Output: Audit Report])
classDef discovery fill:#e1f5fe,stroke:#01579b
classDef processing fill:#fff3e0,stroke:#e65100
classDef action fill:#e8f5e9,stroke:#2e7d32
class Start,Scan,Extract discovery
class Cat1,Cat2,Cat3,Cat4,Cat5,Cat6 processing
class Score,Report,Output action