TECHNICAL DEBT DECISION WORKSHEET
Original planning resource, 2026-10-27. Example values are fictional.
Use evidence and ranges; this is not a financial valuation model.

1. NAME THE CONSEQUENCE
Item / owner / date:
Which future change is harder because of the current implementation?
What concrete observation supports that explanation?
Evidence links or references with permission to use them:
What is observed, what is estimated, and what remains unknown?
Does a current defect or urgent risk need its own response?

2. COMPARE OPTIONS
Option A: leave the implementation for now.
Effect on upcoming work:
Risk of waiting / revisit trigger:
Option B: make a bounded incremental repair.
Boundary / smallest reviewable change:
Estimated effort range / confidence / assumptions:
Option C: broader replacement, only if separately justified.
Requirement that makes wider scope necessary:
Migration / compatibility / recovery costs:
What new information would change the choice?

3. WORKED FICTIONAL DECISION
TD1 has three copied permission handlers.
One invented change spent 45 minutes tracing and 25 minutes editing copies.
Those 70 minutes are one observation, not a guaranteed recurring saving.
A new approved feature touches the rule.
The team will investigate a shared-rule extraction, estimated at 2-4 hours.
First characterize allowed and forbidden behavior in every handler.
Move one handler at a time, review equivalence, and retain a rollback route.
A full export rewrite is not justified by this observation alone.

4. DEFINE COMPLETION
Behavior that must remain unchanged:
Behavior that should become easier to change:
Acceptance cases / reviewer:
Rollback or safe stopping point:
What will still remain after this repair?

5. REVIEW AFTER THE NEXT RELEVANT CHANGE
Actual repair effort:
Actual consequence during the next feature:
Did the original explanation hold?
Resolved item / remaining separate item:
Decision: close, revise, continue, or stop.
Do not claim success only because a refactor merged.