Proposal Filing

Create a new Lorekeeper proposal ticket end-to-end.

Prerequisites

• Working directory: ~/Code/lorekeeper/
• Git identity: git config user.name and user.email must be set

Steps

1. Get the next ticket number

Always use the GitHub Issues-based script — this works from any git state (no need to pull latest):

cd ~/Code/lorekeeper
./scripts/next-ticket-number.sh -m

This queries GitHub Issues for the highest existing LKPR-N and returns the next one, e.g. LKPR-43. Also available as machine-parseable:

./scripts/next-ticket-number.sh  # just "LKPR-43"

Do NOT rely on the local git state — you may not have the latest main branch, leading to duplicate ticket numbers.

2. Create the markdown file

cp backlogs/TEMPLATE.md backlogs/LKPR-N-<short-slug>.md

Fill in frontmatter:

---
id: LKPR-N
title: Short descriptive title
type: feature # feature | bug | enhancement | research | chore
status: S:proposal
priority: P2:medium # P0:critical | P1:high | P2:medium | P3:low
sprint: ~
rice_score: ~
filed_by: Diana # whoever is filing
filed_date: YYYY-MM-DD
github_issue: ~ # fill after step 3
---

Required body sections: Problem, Solution, Acceptance Criteria, Affected Files (Backend + Dashboard or _none_), Dependencies.

3. Create the GitHub issue

gh issue create \
  --title "LKPR-N: <title>" \
  --label "S:Proposal,P2: medium" \
  --body "$(cat backlogs/LKPR-N-<slug>.md)" \
  --repo Jessinra/Lorekeeper

Important: GitHub label format has a space between colon and value (e.g. P2: medium, not P2:medium).

4. Add GitHub issue number to frontmatter

After creating the issue, add its number to the frontmatter. The pre-commit hook validates this field — it must be the numeric ID, not the full URL:

github_issue: 211 # number only, not "https://github.com/..."

Then run Prettier — the pre-commit hook checks formatting and will reject unformatted files:

npx prettier --write --prose-wrap preserve backlogs/LKPR-N-<slug>.md

5. Commit the markdown file

git add backlogs/LKPR-N-<slug>.md
git commit -m "[LKPR-0] chore: add LKPR-N <short title>"

Use [LKPR-0] prefix for chores/proposals (not [LKPR-dev] — that's for implementation work).

6. Push and open a PR

Direct pushes to main are blocked by the pre-push hook. Always use a feature branch:

# Create a feature branch for this proposal
git checkout -b proposal/LKPR-N-<slug>

# Commit is already done in step 5, so just push
git push origin proposal/LKPR-N-<slug>

Then open a PR against main:

gh pr create \
  --base main \
  --head proposal/LKPR-N-<slug> \
  --title "LKPR-N: <short title>" \
  --body "Proposal ticket filed. Awaiting PM review." \
  --repo Jessinra/Lorekeeper

Do not merge your own PR. Wait for PM (Akane) or Jason to review and approve.

Troubleshooting

• Pre-commit hook rejects: Two common causes:
• Missing github_issue in frontmatter (fill after step 3)
• Markdown not formatted — run npx prettier --write --prose-wrap preserve backlogs/LKPR-N-<slug>.md
• Pre-push hook timed out: The hook runs mypy + unit tests + E2E tests (~60s). Retry with a longer timeout parameter (300s).
• Labels fail: Labels are "S:Proposal,P2: medium" (space after colon, NOT P2:medium)
• Wrong branch: Development work goes on feature branches. Proposals go to main or chore/backlog

Tips

• File symptoms first, not root cause — label unconfirmed hypotheses clearly
• For ideas that need research first, set type: research and add an Open Questions section
• Run ./scripts/next-ticket-number.sh -m early — it queries GitHub, so no local pull needed
• If you suspect a ticket is stale/low priority, mention it in Notes — PM will triage during sprint review