# 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

```yaml
---
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**.