---
title: "Link every TODO to a ticket · Agent Wranglers"
url: https://agentwranglers.se/playbook/architecture/comments/todos-with-tickets
updated: 2026-10-20
licence: "All rights reserved"
---

# Link every TODO to a ticket

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Comments](https://agentwranglers.se/playbook/architecture/comments)
- Rule: A `TODO` or `FIXME` comment names a ticket, or it is not merged. Loose notes in the code are never planned and never found.
- How: Open a ticket for the work and write its ID in the comment, such as `TODO(SHOP-512)`. If the work is not worth a ticket, delete the note. Remove the comment in the change that closes the ticket.
- Check: The build fails on a `TODO` or `FIXME` without a ticket ID. Examples are Ruff `TD003` for Python, or the grep below for any language.

Example:

```js
// Bad: nobody owns it, so it stays forever
// TODO: handle refunds in other currencies
// Good: the ticket holds the plan and the owner
// TODO(SHOP-512): handle refunds in other currencies
```

```python
# Bad
# TODO: handle refunds in other currencies
# Good
# TODO(SHOP-512): handle refunds in other currencies
```

```sh
grep -rnE '\b(TODO|FIXME)\b' src/ | grep -vE '(TODO|FIXME)\([A-Z]+-[0-9]+\)' && exit 1 || exit 0
```

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers architecture playbook: https://agentwranglers.se/playbook/architecture/comments/todos-with-tickets`.

- Previous: [Keep docblocks only for what types cannot say](https://agentwranglers.se/playbook/architecture/comments/useful-docblocks)
- [Comments](https://agentwranglers.se/playbook/architecture/comments)