Backlog Management

How tickets work in the Lorekeeper project. Every ticket has a lifecycle and a home.

Where Tickets Live

~/Code/lorekeeper/backlogs/
├── proposal/           # Raw ideas, S:Proposal
├── ready/              # Validated + prioritized, S:Ready
├── done/               # Shipped + verified, S:Done
├── cancelled/          # Won't do, S:Cancelled
└── TEMPLATE.md         # Template

Tickets are PROPOSAL → READY → DONE (or CANCELLED). File location must match status — when status changes, git mv the file to the corresponding subdirectory. Zero files should live at backlogs/ root level.

Currently deferred tickets (S:Deferred) remain in proposal/ with the deferred label; they aren't ready for promotion but aren't dead either. Cancelled tickets are never reborn.

Ticket Lifecycle

S:proposal → S:ready → S:in-progress → S:review → S:done
                         ↓
               S:deferred / S:cancelled

Numbering Convention

SEQUENTIAL only. Highest existing number + 1. Gaps are from done tickets moved to backlogs/done/. Never fill gaps.

Check all subdirectories (proposal/, ready/, done/, cancelled/) to find the highest number.

Frontmatter Convention

Each file has a YAML frontmatter with metadata. The github_issue field is mandatory and enforced by the pre-commit hook:

---
id: LKPR-N
title: Short descriptive title
type: bug | feature | enhancement | research | chore
status: S:Proposal
priority: P2:medium # P0:critical | P1:high | P2:medium | P3:low
sprint: ~
rice_score: ~
filed_by: Akane | Diana | Jason
filed_date: YYYY-MM-DD
github_issue: 123 # REQUIRED — pre-commit hook validates this
---

Status and priority must stay in sync between file frontmatter and GitHub labels. Both are sources of truth. When promoting a ticket (e.g. proposal → ready), update BOTH:

1. File: change status: S:Proposal → S:Ready, git mv to new subdirectory
2. GitHub: gh issue edit N --add-label "S:Ready" --remove-label "S:Proposal"

The daily backlog triage cron job (lorekeeper-daily-backlog-triage) checks for drift between file status and GH labels and reports mismatches.

Sections: Problem, Solution, Acceptance Criteria, Affected Files (Backend + Dashboard), Dependencies, Open Questions, Notes.

For dashboard changes, list the UI component. If backend-only, write _none_ for Dashboard.

Scripts

lorekeeper-backlog.sh — View tickets

cd ~/Code/lorekeeper
./scripts/lorekeeper-backlog.sh
./scripts/lorekeeper-backlog.sh proposal
./scripts/lorekeeper-backlog.sh backlog

next-ticket-number.sh — Get the next available number

./scripts/next-ticket-number.sh
./scripts/next-ticket-number.sh -m  # machine-parseable

Uses GitHub Issues API — authoritative regardless of which branch you're on.

Promoting a Ticket (Proposal → Ready)

cd ~/Code/lorekeeper
git mv backlogs/proposal/LKPR-N-<slug>.md backlogs/ready/
# Edit status: S:Proposal → S:Ready
npx prettier --write --prose-wrap preserve backlogs/ready/LKPR-N-<slug>.md
gh issue edit N --add-label "S:Ready" --remove-label "S:Proposal"
git add backlogs/ready/LKPR-N-<slug>.md
git commit -m "[LKPR-0] chore: promote LKPR-N to ready"

Closing a Ticket (Done)

cd ~/Code/lorekeeper
git mv backlogs/ready/LKPR-N-<slug>.md backlogs/done/
# Edit status: S:Ready → S:Done
gh issue close N
git add backlogs/done/LKPR-N-<slug>.md
git commit -m "[LKPR-0] chore: close LKPR-N (shipped)"

Reconciling Backlog Drift

When files and GitHub issues have drifted:

1. Audit: Compare file frontmatter vs GH labels for every ticket
2. File location: Ensure file is in correct subdirectory matching its status
3. Status sync: Update file status: to match GH label
4. Title collision: If GH title claims wrong LKPR-N vs body id:, fix the title
5. Missing `github_issue`: Add the field — pre-commit validates it
6. Root-level files: Move to appropriate subdirectory
7. Duplicate files: Remove the copy in wrong directory, keep the correct one

Filing a New Ticket

# 1. Get next number
./scripts/next-ticket-number.sh
# 2. Copy template
cp backlogs/TEMPLATE.md backlogs/proposal/LKPR-NEXT-<slug>.md
# 3. Fill in, create GH issue, add github_issue to frontmatter
# 4. npx prettier --write --prose-wrap preserve
# 5. Commit on proposal branch

Pitfalls

• Don't fill gaps in numbering — sequential only
• Don't leave status: in-progress across sessions without context
• File-GH label drift is common — the daily triage cron catches it
• When creating a file from an existing GH issue body, check for title/number collisions first
• Pre-commit hook validates: github_issue, prettier, ticket prefix
• Use git push --no-verify to bypass pre-push hook only on proposal branches, never main