# Practice: Lightweight Bug Tracking in the Document Store

## The approach

The bug tracker is a single Markdown file ([BUGS.md](notes/BUGS.md)) in the document store. Bugs and feature requests are written as structured sections with consistent fields. Related design decisions, implementation plans, and debriefs are separate documents linked with standard Markdown links. Everything is versioned in git.

## Why it works

It's just a file. No external service, no database schema, no API to learn. Any agent or user with document access can read it, search it, and update it. The Consul files bugs during conversation. The Curator enriches its metadata. The software engineer reads it and writes implementation plans that link back. The deployment engineer files bugs from their own Consul sessions. All of this happens through the same document tools that manage everything else in the workspace.

Because it's in git, you get history for free — who filed what, when, what changed. Because it's in the document store, it's searchable via FTS5 and visible according to the same permission model as everything else.

## Structure

Three sections: **Open** (active bugs), **Feature Requests** (desired improvements), and **Resolved** (closed items with resolution notes). Each entry follows a template:

```markdown
### BUG-NNN: Short description
**Severity:** Critical / High / Medium / Low
**Component:** Which part of the system
**Description:** What's wrong
**Expected behaviour:** What should happen
**Workaround:** If any
**Observed:** Date and context
**Reference:** [link to design note](path/to/note.md), [link to debrief](path/to/debrief.md)
```

Feature requests are similar but with **Priority** and **Requested by** instead of **Severity** and **Workaround**.

## The linking pattern

A bug rarely exists in isolation. The tracker entry is the index; the detail lives in linked documents:

- A bug references the [design note](notes/code/visibility-and-authority.md) where the fix is designed
- The design note references the [implementation plan](plans/implementation-plan-remove-visibility-enum.md) the engineer produced
- The implementation plan references the [outgoing action item](outgoing/user-defined-visibility-tiers.md) that started the conversation
- A debrief document captures [what went wrong operationally](commercial/debrief-workspace-init.md) and the bug references it

The tracker stays concise. The linked documents carry the depth. Moving a bug to Resolved is a one-line edit; the full story is in the linked chain.

## What makes this a good fit for PCE

The practice exploits several PCE features naturally:

- **Full-text search** — `document_search("BUG-014")` or `document_search("world-writable")` finds the relevant entry instantly
- **Git history** — `document_history("notes/BUGS.md")` shows when bugs were filed and resolved
- **Visibility** — the tracker can be public (for open-source projects) or restricted (for commercial workspaces)
- **Agent access** — any agent can read the tracker to understand known issues before starting work
- **Cross-referencing** — Markdown links between the tracker and design notes create an explicit knowledge graph that the Curator can mine for metadata

## Scaling

This approach works well up to perhaps a hundred items. Beyond that, the single file becomes unwieldy and you'd want to split into per-component or per-milestone files, or move to a directory of individual bug documents. But for a small team iterating quickly, the single-file approach has the lowest overhead and the highest visibility.