> For the complete documentation index, see [llms.txt](https://engineering.umh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engineering.umh.app/engineering/development-process/how-to-build/tickets/tech-debt.md). # Tech debt What happens to a problem in our code that we chose to fix later, and who owns it until it is fixed. Owner: Jeremy Tech debt is a problem in our code that only a future change can trigger, and that we left for a later fix. Each piece of tech debt has an owner and a ticket. ## Rules * A review finding that is fixed later goes into a stacked pull request or a tech-debt ticket, as [Code review](/engineering/development-process/how-to-build/code-review.md#review-threads) describes. The author chooses which. * A tech-debt ticket sits under a sub-ticket called Tech debt, inside a [rollout ticket](/engineering/development-process/how-to-build/tickets/rollout.md) or a [monitoring ticket](/engineering/development-process/how-to-build/tickets/monitoring.md). * A tech-debt ticket says what is wrong, what it causes, and who has to decide before someone fixes it. * How likely the next change to that code is to trigger the problem sets its priority. ## Fix it now, in a stacked pull request, or in a ticket **Fix a finding in the same pull request.** Google's code review guide calls cleaning up later ["a common way for codebases to degenerate"](https://google.github.io/eng-practices/review/reviewer/pushback.html). **Fix it in a** [**stacked pull request**](/engineering/development-process/how-to-build.md#stacked-pull-requests) **if one small pull request can fix it.** A fix for the code of your change goes on top of it. A fix for older code next to your change goes at the bottom of the stack, like a bug fix. The [Boy Scout rule](/engineering/development-process/how-to-build/coding-standards/code-quality/readability.md#make-the-code-explain-itself) asks for such fixes. The stacked pull request has the same author, so the finding keeps its owner. If that pull request is closed without a merge, file a tech-debt ticket. **If it needs more than one small pull request, file a tech-debt ticket.** The author files it and links it in the review thread of the finding. The author can file one for any problem, including one found outside a review. ## Where a tech-debt ticket lives **All tech-debt tickets of a** [**rollout ticket**](/engineering/development-process/how-to-build/tickets/rollout.md) **or a** [**monitoring ticket**](/engineering/development-process/how-to-build/tickets/monitoring.md) **sit under one sub-ticket called Tech debt.** A tech-debt ticket outside one has no owner. **If the pull request has no rollout or monitoring ticket, the author fixes the finding or files it as for older code, below.** **A tech-debt ticket stays under the rollout ticket after that ticket is done**, as [When it is done](/engineering/development-process/how-to-ship.md#when-it-is-done) says. **Tech debt found in older code goes under the monitoring ticket of that area of the product.** If no area fits, it goes under the monitoring ticket for the maintenance of that repository. ## What a tech-debt ticket says **The title starts with `[TECH DEBT]`.** The body has three parts: * A link to where the problem came up. That is usually the review thread, which shows the code and the discussion. Without a thread, link the pull request or the lines of code. * One sentence on what is wrong, what it causes and for whom. For example: "An empty `Store{}` panics on its first write. Every caller uses `NewStore` today, but the first caller that skips it crashes the process." * Who has to decide before someone fixes it, as [Obvious tech debt and decisions](#obvious-tech-debt-and-decisions) describes. **If a user can run into the problem today, it is a** [**bug**](/engineering/development-process/how-to-build/tickets/bugs.md)**, not tech debt.** A finding of personal taste, such as "this part is messy", gets one of the three answers like any other finding. **A security problem goes under the Security sub-ticket, as** [**Security**](/engineering/development-process/how-to-build/tickets/security.md) **describes.** ## Obvious tech debt and decisions Each piece of tech debt is at one of three levels: * **Obvious.** The problem and the fix are both clear. Nobody has to decide anything first. Anyone can fix it. * **Engineering decision.** There are several ways to fix it, or the fix changes an abstraction, an exported API or a [one-way door](/engineering/development-process/how-to-build.md#one-way-doors). The [Code Owner](/engineering/product-engineer/code-owner.md) picks the way first. * **Product decision.** The fix changes what users see or do. The [Product Owner](/engineering/product-engineer/product-owner.md) decides. **Once the Code Owner or the Product Owner has decided, the tech debt counts as obvious.** If the author and the reviewer disagree on the level, the Code Owner decides. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://engineering.umh.app/engineering/development-process/how-to-build/tickets/tech-debt.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.