How to use BACKLOG.md

BACKLOG.md is a markdown file you keep in the root of a GitHub repository. It holds the work items for that project: features to build, bugs to fix, things to revisit later. The file is the source of truth. Backlog Viewer reads it, edits it, and writes it back, but the data lives in your repo, not our database.

Option 1: Let Backlog Viewer do it

When you connect a repo that doesn't have a backlog file yet, Backlog Viewer can create one and commit it for you. The generated file includes a project description, an entry format reference, and a blank template item.

Option 2: Create it yourself

In any repo you own, add a new file named BACKLOG.md at the root (you can use .github/BACKLOG.md if you prefer it out of the root). Commit it directly on the default branch or through a pull request.

A backlog file has three parts. Only the item section is required.

1. Context (optional)

A short preamble at the top of the file. Describe what the project is, who it is for, and where to find related resources. Keep it brief; this section is free-form markdown.

2. Entry format reference (optional)

The heading ## Entry format marks an in-file specification. Backlog Viewer hides this section from the app display and treats the example item that follows it as a template, not a real entry. Keeping it in the file helps anyone editing the markdown directly stay consistent.

3. Items (required)

Each item is an H3 heading followed by up to three labeled fields and optional free-form notes. Items are separated by --- rules.

### Fix auth redirect loop on Safari

**Why it matters:** Safari drops the session cookie under certain cache
conditions, trapping users in an infinite login loop.

**When to revisit:** After the next Safari release notes confirm the
underlying WebKit fix, or if support tickets spike again.

**Notes:**
- Reproduces on iOS 17.4 and macOS 14.4.
- Related to issue #312.

---

### Add CSV export to the reports page

**Why it matters:** Enterprise users need offline spreadsheets for
compliance audits; JSON doesn't cut it.

**When to revisit:** Q3 planning, or when the compliance team confirms
the new data-retention policy.

**Notes:**
- Use the existing `reports` module; add a `toCsv` helper.
- Check performance on datasets > 100k rows.

All three fields are optional. You can also include free-form markdown after the labeled fields (lists, links, code blocks). Backlog Viewer preserves anything it does not recognize.

Because the file is plain markdown, you can edit it in any text editor, on GitHub's web interface, or through your IDE. Backlog Viewer will pick up the changes the next time it fetches the file. Just keep the H3-per-item structure and the labeled fields consistent so the parser can read them.

• Use ### for item titles. Other heading levels are treated as plain text or section headers.
• Separate items with --- on its own line for visual clarity. The app works without separators, but they make the raw file easier to scan.
• Don't put markdown tables or complex nested blocks inside labeled field values; they may not round-trip cleanly.

1. Sign in with GitHub.
2. Click "Connect a repo" on the dashboard.
3. Select the repository and the file path (defaults to BACKLOG.md at the root).
4. Choose write mode: direct commits, or pull requests if you prefer review.
5. Backlog Viewer fetches the file, parses the items, and shows them in a focused editing view.

If the repo does not have a backlog file yet, Backlog Viewer can scaffold one and commit it automatically.

• One backlog per repo. If an item spans multiple projects, keep it in a central backlog (for example, ~/.ai/memory/BACKLOG.md) instead of duplicating it.
• Decisions go elsewhere. Active project decisions belong in.ai/memory/DECISIONS.md or equivalent. The backlog is for work items only.
• Don't delete the Entry format section. It is hidden in the app, but it helps teammates and AI tools understand the file structure when editing outside Backlog Viewer.
• Keep titles stable. Backlog Viewer uses the item title as a key for app-side metadata (status, priority, tags). If you rename an item in the raw file, its metadata resets. Rename inside the app to preserve metadata.