yonlu/yellowjacket
1
1
Fork 0
Code Issues 55 Pull Requests 6 Actions Packages Projects Releases 12 Wiki Activity

Retire four documents that describe a project that no longer exists #98

New Issue
Closed
opened 2026-08-18 20:38:53 +00:00 by yonlu · 2 comments
yonlu commented 2026-08-18 20:38:53 +00:00
Owner
Copy Link
Copy Source

Four documents describe a project that no longer exists. They are not merely out of date — they contradict the code, which makes them worse than absent, because the only way to find out they are wrong is to trust one and be misled.

Follows #92, which made the tracker the source of truth and cleared .planning/. This is the same pass over docs/ and .pi/.

The rule being applied

Four homes, and anything that answers none of these questions goes:

Home Answers
docs/ how the app behaves and how you operate it now
CLAUDE.md how the code is built and why it is that way
the tracker what is wanted and what is in flight
.planning/NOTES.md measured facts and rejected ideas that outlive one issue

Deleted

docs/dev/roadmap.md (1,648 lines). Its "Current State" describes an app with "basic playback, track list and album grid views, configuration page". Phases 1, 2, 3 and 5 have shipped entire — playlists, shuffle and repeat, keyboard shortcuts, virtualised lists, search, custom columns, smart playlists, the MusicBrainz client, autotag. Its Technical Debt list is twenty unchecked boxes, several of them done. Its Decision Log records "Testing: Deferred — focus on architecture first" against a repo with 836 Vitest tests, a Playwright suite on two engines, and race-detector passes in three build configurations.

.pi/journal.md (118 lines). "Temporal memory: what happened and what's next", frozen at plan 005 and still saying "everything from phase 1 onward is still uncommitted". That is the tracker's job now, and a work log that is wrong about what is committed is a hazard.

docs/dev/overview.md (53 lines). A shallower and partly incorrect version of CLAUDE.md's architecture section. README pointed at it; it points at CLAUDE.md now.

docs/dev/config-suggestions.md (194 lines). Eight numbered suggestions, of which one is still live — it went to #97. The rest were overtaken by rewrites: applyDefaults exists, scan concurrency is configurable as ScanConcurrency with SSD/HDD detection, and httphandler.go and the WriteHeader-after-render bug it described are gone entirely.

Salvaged first, so nothing is lost

Issue From
#94 device sync over MTP, with re-encoding roadmap phase 6
#95 UI layout customisation — registry, layouts, editor roadmap phase 4
#96 AcoustID fingerprinting roadmap 5.2
#97 config.Config has a dozen setters and no lock config-suggestions #2

Kept, and why

docs/android-release.md, docs/PROFILING.md and docs/index-cache.md are operational and accurate. docs/dev/resources.md is eight lines of links. .planning/NOTES.md, .planning/audits/ and .planning/plans/completed/ hold the measurements and arguments that CLAUDE.md compresses into conclusions — that is compression, not duplication.

AGENTS.md is a symlink to CLAUDE.md. That is the convention working, not redundancy.

Done when

Every remaining document describes either the app as it is or a decision as it was made, and nothing describes work nobody is doing.

Four documents describe a project that no longer exists. They are not merely out of date — they contradict the code, which makes them worse than absent, because the only way to find out they are wrong is to trust one and be misled. Follows #92, which made the tracker the source of truth and cleared `.planning/`. This is the same pass over `docs/` and `.pi/`. ## The rule being applied Four homes, and anything that answers none of these questions goes: | Home | Answers | |---|---| | `docs/` | how the app behaves and how you operate it **now** | | `CLAUDE.md` | how the code is built and **why it is that way** | | the tracker | what is wanted and what is in flight | | `.planning/NOTES.md` | measured facts and rejected ideas that outlive one issue | ## Deleted **`docs/dev/roadmap.md` (1,648 lines).** Its "Current State" describes an app with "basic playback, track list and album grid views, configuration page". Phases 1, 2, 3 and 5 have shipped entire — playlists, shuffle and repeat, keyboard shortcuts, virtualised lists, search, custom columns, smart playlists, the MusicBrainz client, autotag. Its Technical Debt list is twenty unchecked boxes, several of them done. Its Decision Log records **"Testing: Deferred — focus on architecture first"** against a repo with 836 Vitest tests, a Playwright suite on two engines, and race-detector passes in three build configurations. **`.pi/journal.md` (118 lines).** "Temporal memory: what happened and what's next", frozen at plan 005 and still saying "everything from phase 1 onward is still uncommitted". That is the tracker's job now, and a work log that is wrong about what is committed is a hazard. **`docs/dev/overview.md` (53 lines).** A shallower and partly incorrect version of CLAUDE.md's architecture section. README pointed at it; it points at CLAUDE.md now. **`docs/dev/config-suggestions.md` (194 lines).** Eight numbered suggestions, of which **one** is still live — it went to #97. The rest were overtaken by rewrites: `applyDefaults` exists, scan concurrency is configurable as `ScanConcurrency` with SSD/HDD detection, and `httphandler.go` and the `WriteHeader`-after-render bug it described are gone entirely. ## Salvaged first, so nothing is lost | Issue | From | |---|---| | #94 device sync over MTP, with re-encoding | roadmap phase 6 | | #95 UI layout customisation — registry, layouts, editor | roadmap phase 4 | | #96 AcoustID fingerprinting | roadmap 5.2 | | #97 `config.Config` has a dozen setters and no lock | config-suggestions #2 | ## Kept, and why `docs/android-release.md`, `docs/PROFILING.md` and `docs/index-cache.md` are operational and accurate. `docs/dev/resources.md` is eight lines of links. `.planning/NOTES.md`, `.planning/audits/` and `.planning/plans/completed/` hold the measurements and arguments that CLAUDE.md compresses into conclusions — that is compression, not duplication. `AGENTS.md` is a symlink to `CLAUDE.md`. That is the convention working, not redundancy. ## Done when Every remaining document describes either the app as it is or a decision as it was made, and nothing describes work nobody is doing.
yonlu added the Kind/Documentation
Priority
Medium
3
 labels 2026-08-18 20:38:53 +00:00
yonlu self-assigned this 2026-08-18 20:39:07 +00:00
yonlu added the
Status
In Progress
 label 2026-08-18 20:39:07 +00:00
yonlu commented 2026-08-18 20:39:07 +00:00
Author
Owner
Copy Link
Copy Source

Starting work on this on docs/retire-stale-planning-docs.

Starting work on this on `docs/retire-stale-planning-docs`.
yonlu commented 2026-08-18 21:15:36 +00:00
Author
Owner
Copy Link
Copy Source

Shipped in main via #99 — 31ada14, merged as 1a221a4. The four documents are gone and the README repoint is in.

Closing by hand: 31ada14's footer said Refs #98, not Closes, and #99's merge commit body was a lone Reviewed-on: trailer — so no closing keyword ever reached main. Consistent with what #100 describes.

Shipped in `main` via #99 — `31ada14`, merged as `1a221a4`. The four documents are gone and the README repoint is in. Closing by hand: `31ada14`'s footer said `Refs #98`, not `Closes`, and #99's merge commit body was a lone `Reviewed-on:` trailer — so no closing keyword ever reached `main`. Consistent with what #100 describes.
yonlu closed this issue 2026-08-18 21:15:36 +00:00
yonlu removed the
Status
In Progress
 label 2026-08-18 21:15:36 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Area/Design
Area/Downloads
Area/Explore
Area/Library-UI
Area/Metadata
Area/Packaging
Area/Player
Area/Queue
Area/Settings
Area/Shell-Nav
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
 Platform/Android
Platform/Desktop
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Medium
3
The priority is medium
Priority
Low
4
The priority is low
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
In Progress
Somebody is actively working on this right now
No labels Kind/Documentation
Priority
Medium
3
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
logan yonlu
No Assignees yonlu
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: yonlu/yellowjacket#98