@@ -77,6 +77,15 @@ Lunatask only supports full replacement, so reproduce the original note verbatim
[New content here]
```
+## Surfacing tech debt
+
+While working, you may notice code smells, outdated patterns, missing tests, or other improvement opportunities related _or unrelated_ to the current task. We might also intentionally introduce tech debt, aware of the trade-offs. Don't let these observations or introductions disappear with the session; ask the user whether you should mention them.
+
+If the user confirms and it's/they're
+
+- **relevant to the handoff**: mention briefly in context section so the receiving agent is aware
+- **worth tracking separately**: suggest capturing as standalone task(s) so the user can pick up or hand off to another agent later. Even as standalone tasks, make sure to include enough context that another agent could pick it up.
+
---
If `lunatask` or `lune` MCP tools are unavailable, see [cli.md](references/cli.md). If the CLI is also unavailable, see [installing-lune.md](references/installing-lune.md).
@@ -27,6 +27,15 @@ If you find significant differences between what the handoff describes and what
Don't try to reconcile the handoff with reality on your own. The user may have context about why things changed.
+## Surfacing tech debt
+
+While working, you may notice code smells, outdated patterns, missing tests, or other improvement opportunities related _or unrelated_ to the current task. We might also intentionally introduce tech debt, aware of the trade-offs. Don't let these observations or introductions disappear with the session.
+
+- Mention them briefly to the user before or after completing the main work
+- Offer to capture them as standalone task(s) so the user can pick up or hand off to another agent later. Even as standalone tasks, make sure to include enough context that another agent could pick it up.
+
+Don't derail the primary task, but don't let useful observations vanish either.
+
## Workflow
When you begin working on the task, update its status according to the area's workflow. When finished, mark it `complete`.