Free Tech Debt Declaration Template

A tech debt declaration is the document an engineer writes when they ship something that knowingly takes on debt. Not a refactor backlog item. Not a "todo" comment in code. A standing record, written at the moment the debt is incurred, that says: this is the compromise we made, here is why we made it, here is what it will cost us if we never come back, here is the trigger that should make us come back. The template below is what such a record looks like.

The point is not to slow down shipping. The point is to make debt visible at the moment it is being created, so the team can decide whether the debt is the right shape. Most teams operate on invisible debt, complain about it constantly, and never have a productive conversation about it because they do not know what they actually have. The declaration makes it inventoriable.

When to use it

• Any time you ship a solution you know is wrong-shaped but ship-able.
• Any time you skip a test you would normally write.
• Any time you use a library or pattern your team has formally moved away from.
• Any time you take on a known performance, security, or scalability cliff.
• Any time the PR description has the phrase "for now."

The template structure

This is the structure of the template. Copy it into a Notion page, a Linear doc, or a markdown file in your repo — it works in any of them.

TECH DEBT DECLARATION
ID:          DEBT-[NNN]
Declared:    [date]
Declarer:    [name]
Status:      [active / addressed / accepted-permanent]

WHERE
  System / component: [name]
  Code locations:     [file:line] or [link]

WHAT
  One sentence describing the shape of the debt.
  Example: "Auth tokens are stored in plain text in the session cache
  because the encryption layer is not yet built."

WHY (the trade we made)
  What were we optimizing for when we took this debt?
  Example: "Shipping the demo for the customer call on the 18th. We
  had a working but unencrypted version; the alternative was missing
  the call."

WHAT IT COSTS US
  Today:     [...]    (e.g., security risk severity, perf cost)
  At 10x scale: [...]
  Worst-case incident: [...]

REPAYMENT
  Estimated effort: [rough]
  Owner: [name or team]
  Trigger to repay (any of):
    - [event] (e.g., "before adding any third auth provider")
    - [event]
    - [date] (hard expiry, if any)

WORKAROUND IN THE MEANTIME
  How do we live with it safely?
  Example: "Alerting in place for unusual session-cache access. Rotation
  every 24 hours. Production access restricted to break-glass."

LINKS
  Original PR:        [...]
  Tracking ticket:    [...]
  Related decision:   [...]

How to use it well

• Declare debt at the moment of incurring it, not later. Retrospective debt declarations are inventory of regret. Real declarations are decisions. Put the form in the PR template if you need to.
• The trigger to repay is the most important field. Open-ended debt accumulates forever. Tying repayment to a future event ("before adding the third provider") makes the debt finite — it has an expiration condition.
• Cost at 10x scale is where the conversation gets honest. Most debt is cheap today and ruinous later. Forcing the writer to imagine the 10x scenario surfaces whether the debt is the right shape now.
• Accepted-permanent is a valid status. Some debt is debt the team chooses to live with forever. Naming it that way is more honest than pretending it will be addressed.
• Review the declarations quarterly. Tie it to the quarterly decision review. A debt declaration that has been "active" for four quarters is either lying about being active or wrong about being repayable.

What to skip

Skip turning the declarations into a leaderboard. The moment debt declarations are measured per engineer, engineers stop writing them. The visibility is the value; tying performance to the number of declarations destroys the visibility.

Skip declaring TODOs as debt. A TODO in code that is just a future enhancement is not debt — it is unfinished work. Debt is a compromise that has costs. The distinction matters because otherwise the declaration backlog becomes everything-anyone-meant-to-do-eventually.

Frequently asked questions

Is this template free?

Yes. The template above is the whole structure. Most teams keep declarations in a /debt folder in the relevant repo, or in a single team Notion.

Can I edit it?

Yes. Teams with formal SLOs sometimes add a row for which SLOs this debt threatens. Teams without performance pressure drop the 10x scale row.

Do I need to give my email?

No. The structure is the template; the download is a formatted copy and the email is for our newsletter only.