Tech debt reports are the fundamental building block of Stepsize.

They're an expressive, flexible way to track the debt you come across or experience while you work as an individual contributor in an engineering team.

As an engineer, it's important to develop a habit of regularly submitting debt reports to realise the full value of Stepsize — managing tech debt successfully requires knowing which debt exists and what its impact is. This is the role of debt reports.

How to submit debt reports

You typically come across tech debt while you work, which is why we've built a number of workflow integrations. They're the best way to report debt:

You can also submit debt reports from the web app, but these reports will lack some of the extra context that can be attached when you use an integration — most notably they'll lack a link to the relevant code. You can always link to the code in the report's description, but you'll need to grab that link yourself.

Reporting capabilities — what makes up a debt report

🗒 Description

A free text field for you to provide extra context about your report.

Does the code need to be refactored? Is it missing something? Did you just take a shortcut and the code will need to be improved later?

⏳ Time lost

An optional field for you to indicate that you lost time due to this debt.

This is an important metric decision-makers will look at to prioritise debt to address, so make sure to report it when applicable.

🐞 Quality issue

An optional field for you to report that this debt caused a product quality issue like a bug.

This is another important metric decision-makers will look at to prioritise debt to address, so make sure to report it when applicable.

💡 Suggestion

An optional free text field for you to suggest what to do about this debt.

👉 Code location

A link to the code the debt report relates to.

This is attached to your report automatically when you submit it from your editor or from a pull request.

🔗 Pull request / message attachment

A link to the pull request or message the report was submitted from.

This is attached to your report automatically when you submit it from a pull request or Slack message.

Note: When you report debt from a pull request, you'll initially only submit a report with a description, but you can then edit the report on the web app to add other metadata.

<aside> 🗣️ Looking for feedback!

We want to improve the reporting UX and would love your input. You can find our WIP wireframes here — reach out at hello@stepsize.com or book a 15min call with us 🙏

</aside>