Bugs
Use bugs to capture defects with enough detail for triage, ownership, and repair.
Create bugs directly or bring them in from connected issue trackers such as Jira, Linear, GitHub Issues, or GitLab.
What a bug needs
A useful bug has a clear title, reproduction context, expected behavior, current behavior, owner or assignee, team, reporter, status, and enough taxonomy to route it. Use taxonomy when a defect affects a customer, product area, skill, or goal.
For spec-driven development, the bug is the repair spec. Keep reproduction steps, expected behavior, actual behavior, impact, and any failing links close to the bug before sending it to a person or agent.
Where bugs move
Bugs often start in the backlog or triage queue. From there they can be assigned, planned, moved to in progress, sent for review, blocked, completed, or cancelled.
Bug priorities from connected issue trackers
| Priority | Meaning |
|---|---|
Critical | Highest severity work that needs immediate attention. |
Urgent | Time-sensitive work that should interrupt normal ordering. |
High | Important work that should be handled before the default queue. |
Medium | Normal priority work. |
Low | Useful work that can wait behind higher-impact items. |
Lowest | Low-impact work to keep visible without crowding current planning. |
Guided writing is available for initiatives, not bugs. Use direct fields and comments to keep the reproduction details and repair context clear.
When a bug comes from Jira, Linear, GitHub, or GitLab, we can keep issue fields synchronized with the source issue tracker. Titles, descriptions, status, priority, and assignees may be editable inline depending on the integration and its mappings.
Use private todos for private follow-up work. Synced issues follow the visibility rules of the source app, so assume teammates with access to that issue tracker can inspect the issue there.
When a bug is not ready for execution, move through Triage before it becomes planned work.