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.
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.
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?
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.
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.
An optional free text field for you to suggest what to do about this debt.
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.
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 [email protected] or book a 15min call with us 🙏
</aside>
Tech debt groups help you organise all the debt we've tracked, typically based on the domains in the codebase. Check out Tech debt groups to learn more.
When you submit a debt report you can choose to assign it to a group there and then, if you know where it should go, or you can decide to send it to the main feed of reports and assign it to a group later.