docs: add docs/ISSUES.md tactical issue tracker + CLAUDE.md rules

Introduces `docs/ISSUES.md` as the tactical rolling list of known bugs +
small deferred features. Scope is strict: anything fitting in one-to-two
commits lives here; anything larger gets promoted to a Phase in the
roadmap. Complement, not replacement, of the strategic roadmap.

Schema per issue:
- Sequential integer ID (#1, #2, ...)
- Status (OPEN / IN-PROGRESS / DONE)
- Severity (HIGH / MEDIUM / LOW)
- Filed date, component, description, root cause, files, research,
  acceptance
- DONE items move to "Recently closed" at the bottom with commit SHA

Four seeded issues from the 2026-04-24 sky-debug session:

  #1 — Rain falls only to horizon, not to player (weather/particles)
  #2 — Lightning visual not wired (dat-baked PES triggers; research done)
  #3 — Client clock drifts from retail after ~10 min (periodic TimeSync)
  #4 — Sky horizon-glow disabled (fog-mix skipped on sky meshes)

CLAUDE.md adds an "Issue tracking" section right after roadmap
discipline with the four maintenance rules: (1) scan OPEN at session
start, (2) add/close at session end, (3) reference IDs in commit
messages, (4) promote to a Phase if an issue grows. Calls out the
strategic-vs-tactical split so future sessions know when to reach for
the roadmap vs the issues file.

README.md gets one line pointing at `docs/ISSUES.md` below the existing
roadmap link for first-class discoverability.

No code changes; doc-only.
This commit is contained in:
Erik 2026-04-25 00:08:15 +02:00
parent 7e84d489d0
commit b9455259f0
3 changed files with 176 additions and 0 deletions

View file

@ -229,6 +229,27 @@ acdream's plan lives in two files committed to the repo:
The roadmap is not sacred — it changes. It IS the source of truth at any
given moment. When it's wrong, fix it. When it's right, follow it.
## Issue tracking — `docs/ISSUES.md`
Tactical rolling list of known bugs + small deferred features. Scope:
anything that fits in one-to-two commits; larger work stays as a Phase
in the roadmap. Maintenance rules:
1. **Start-of-session:** scan OPEN issues in `docs/ISSUES.md` — any of
them in the area you're about to touch? Plan accordingly.
2. **End-of-session:** if this session observed a defect and didn't fix
it inline, add an issue. If this session fixed an OPEN issue, move
it to **Recently closed** with the commit SHA.
3. **Commit messages:** reference issue IDs when a commit closes one
(`fix #3: periodic TimeSync parsing`). Makes `git log --grep='#3'`
return the full fix history.
4. **Promotion:** if an issue grows into multi-commit work, promote it
to a Phase in the roadmap. Close the issue as
`DONE (promoted to Phase X)` and reference the roadmap commit.
The roadmap is strategic (month-scale, phase-level). ISSUES is tactical
(week-scale, bug-level). They reference each other but don't duplicate.
## Running the client against the live server
The user runs a **local ACE (Asheron's Call Emulator) server on