Task: Project Maintenance & Health Audit

Overview

Execute a rigorous 7-point maintenance sweep to identify structural deviations, documentation inconsistencies, dead code, complexity hotspots, technical debt, missing code documentation, and terminology drift. All findings must be actionable and saved to whiteboard.

Context

Rules & Constraints

Instructions

<step_by_step>

1. Initialize & Plan

   • Use a task management tool (e.g., todo_write, todowrite) to create a plan covering the 7 phases below.
   • Read project whiteboard to preserve existing long-term notes (if any), but clear old automated reports.
   • Identify project's primary language and source directories.

2. Phase 1: Structural Integrity

   • File placement: Check that all source files reside in expected directories per project conventions (e.g., src/, lib/, scripts/). Flag files at wrong levels.
   • Dead directories: Identify empty or orphaned directories with no purpose.
   • Naming conventions: Verify file and directory names follow project conventions (case, separators).
   • Config files: Ensure project config files (deno.json, package.json, etc.) are at expected locations.

3. Phase 2: Code Hygiene & Dependencies

   • Dead Code: Identify exported/public symbols in source directories that are never imported/called elsewhere.
   • Unused Imports: Scan source files for imports/includes that are not used in the file body.
   • Test Quality: Read test files (e.g., *.test.*, *_test.*, test_*.py). Flag tests that:
     • Have no assertions.
     • Use trivial assertions (e.g., expect(true).toBe(true), assert True).
     • Are commented out.

4. Phase 3: Complexity & Hotspots

   • Files: Flag any source file exceeding 500 lines.
   • Functions: Scan for functions/methods exceeding 50 lines.
   • God Objects: Identify classes/modules with mixed concerns (e.g., logic + UI + database in one file).

5. Phase 4: Technical Debt Aggregation

   • Scan: Search for TODO, FIXME, HACK, XXX tags in the codebase.
   • Group: Organize by file/module.
   • Analysis: Flag any that look critical or like "temporary" fixes that became permanent.

6. Phase 5: Consistency (Docs vs. Code)

   • Terminology: Extract key terms from README.md and documents/. Check if code uses different synonyms (e.g., "User" in docs vs "Customer" in code).
   • Drift: Pick 3 major claims from documents/*.md (e.g., "The system handles X asynchronously"). Verify if the code actually does that.

7. Phase 6: Code Documentation Coverage

   • Rule: Every file, class, method, and exported function MUST have documentation (JSDoc, Docstring, Rustdoc, etc.).
   • Check:
     • Responsibility: Does the comment explain what it does?
     • Nuances: For complex logic (cyclomatic complexity > 5 or > 20 lines), are there examples or edge case warnings?
   • Scan: primary source directories.
   • Report: List undocumented symbols.

8. Phase 7: Reporting

   • Compile all findings into whiteboard with the following format:

     markdown
     1# Maintenance Report (YYYY-MM-DD)
     2
     3## 1. Structural Issues
     4
     5- [ ] File X is in root but should be in Y. (Fix: Move file)
     6
     7## 2. Hygiene & Quality
     8
     9- [ ] Unused export `myFunc` in `utils.*`. (Fix: Delete)
     10- [ ] `main.*` is 550 lines. (Fix: Extract `processLogic` to new file)
     11
     12## 3. Technical Debt
     13
     14- [ ] 5 TODOs in `api.*` regarding error handling.
     15
     16## 4. Consistency
     17
     18- [ ] Docs say "User", code says "Client". (Fix: Standardize on User)
     19
     20## 5. Documentation Coverage
     21
     22- [ ] `utils.*` - function `parseData` missing docs. (Fix: Add docs)
     23- [ ] `ComplexClass` missing usage example. (Fix: Add example)

</step_by_step>

Verification