Toju/agents-docs/BUG_TRACKER.md

Obsidian Bug Tracker — Agent Contract

User-maintained bug reports live outside the repo. Use this when the user names a bug or asks to triage the backlog.

Inbox: /home/ludde/Nextcloud/Obsidian Vault/Log/Bugs/
Attachments: …/Bugs/attachments/<Bug title>/
Dashboard / template: …/Log/Create bug.md, …/Log/Templates/Bug Report.md

---

Named fix (default — cheap path)

When the user says e.g. fix bug "Images and files in chat doesn't load":

1. Resolve one note under Log/Bugs/ whose title matches (usually Bug - <title>.md). Do not list or read the whole inbox.
2. Read that note (Description, Steps, Expected/Actual, Logs). Read attachments only under that bug’s attachment folder if referenced.
3. Interview before implement (see /AGENTS.md and .cursor/rules/interview-before-fix.mdc): restate the bug, list gaps, present choices with a recommended default, propose scope and proof of done — then wait for the user. Do not start coding until they answer (unless they said “just fix it”).
4. Acceptance criteria = the note’s Expected Result plus the user’s interview answers.
5. Fix in default repo scope (toju-app/ + targeted electron/ + CI) per AGENTS.md. Do not crawl server/ / e2e/ / other packages unless the note or user clearly requires it — then ask once.
6. Prove the asked behavior (not only unit-green). Prefer a regression that encodes the note’s failure mode.
7. When done: set that note’s frontmatter status to Resolved (or Closed if the user prefers). Do not rewrite Description / Investigation / Resolution unless asked.
8. Long thread + more work left → write agents-docs/HANDOFF.md and ask for a new chat.

Do not re-read BUG_TRACKER.md every turn after the first use. Do not load the stale “open bugs” snapshot as truth — the vault files are source of truth.

---

Backlog triage only

If the user asks to list/triage open bugs (not a named fix): ls / glob Log/Bugs/*.md, filter status: Open, summarize titles — still don’t open every body until they pick one.

---

Vault edit policy

Unless the user asks for more:

• Allowed write: frontmatter status (Open → Resolved / Closed); move files if they specify a convention.
• Do not edit: other frontmatter fields, Description, Steps, Investigation, Resolution, etc.

Investigation findings go in chat or the repo — not the vault — unless asked.

---

Bug note format

---
title: Bug - …
type: bug
status: Open          # Open | Resolved | Closed
priority: Low | Medium | High | Critical
severity: Low | Medium | High | Critical
environment: …
created: YYYY-MM-DD HH:mm
tags: [bug]
---

Body: Description, Steps to Reproduce, Expected Result, Actual Result, Logs / Screenshots, Investigation, Resolution.