Project Health Evaluation
Project Health Evaluation
Purpose
Measure whether governance actually improves the project instead of merely adding process.
Core Dimensions
Score only dimensions that matter to the project.
1. Discoverability
Can a new agent find the main entry points quickly?
2. Predictability
Can the likely location of a file be inferred from its role?
3. Traceability
Can important changes be connected to versions, branches, releases, or other recoverable states?
4. Recoverability
Can risky work be rolled back or restored?
5. Documentation coherence
Do active documents agree about important project facts?
6. Lifecycle hygiene
Are obsolete, temporary, generated, and archived materials controlled?
7. Structural debt
How much unexplained entropy has accumulated?
8. Handoff cost
How much context must a new human or agent reconstruct before productive work?
Lightweight Score
Use a 0-3 scale when a numerical view is useful:
- 0 = unmanaged
- 1 = inconsistent
- 2 = mostly healthy
- 3 = clear and reliable
Do not manufacture precision.
Trigger-Based Review
A useful review rhythm is event-based rather than time-based:
- after major releases
- after major refactors
- before a large migration
- before project handoff
- after repeated confusion about location or current state
- when structural debt becomes noticeable
Do not schedule full audits simply because time has elapsed unless the project benefits from them.
Success Metrics
Possible longitudinal metrics:
- time for a new agent to orient itself
- number of duplicate/obsolete documents
- number of orphaned files
- number of unsafe changes caught before execution
- rollback success rate
- percentage of major changes with recoverable checkpoints
- frequency of conflicting sources of truth
- structural cleanup effort per milestone
The best metric is whether the project becomes easier to change without becoming harder to understand.