tracking-technical-debt

Track technical debt by creating a bead with bd create, then link it to code using a DEBT[bd-xxxx] marker at the problem location. This creates an auditable record that persists until you resolve the issue, keeping debt visible and actionable across your team.

Use beads to capture issues like O(n²) loops or duplicated validation when you can't fix them right away. Add a code marker pointing to the problem location so the issue stays linked to concrete code and doesn't get lost in backlog noise.

Yes, you can batch multiple small issues into a single bead when they share context or relate to the same problem area. This reduces marker clutter while keeping related debt together for batch remediation.

After creating a bead, add a DEBT[bd-xxxx] comment marker in your code at the relevant location. This establishes an explicit, traceable relationship between the technical debt record and the actual code that needs attention.

Track problems you can't fix immediately: O(n²) algorithms, duplicated validation logic, MVP-style configurations, or any workaround that needs eventual remediation. Mark it so it remains visible and prioritizable instead of forgotten.