Skip to content

Move the backlog to the project board and remove docs/backlog - #27

Closed
meketreve wants to merge 1 commit into
OpenPerpetuum:developfrom
meketreve:backlog-migrate-to-project-board
Closed

Move the backlog to the project board and remove docs/backlog#27
meketreve wants to merge 1 commit into
OpenPerpetuum:developfrom
meketreve:backlog-migrate-to-project-board

Conversation

@meketreve

Copy link
Copy Markdown
Contributor

This deletes docs/backlog/ — 85 entries, 3071 lines of your project memory. Please read the whole
thing before deciding, and reject it without hesitation if the answer is no. Nothing else depends on
it.

What was done

All 85 backlog entries now exist as draft issues on the
Game Server board, each keeping its
ISSUE-NNN / IMPROVEMENT-NNN identifier in the item title and its complete body text.

File Entries Board status
docs/backlog/issues.md 21 17 to BACKLOG, the rest by their own status
docs/backlog/improvements.md 29 mapped by status
docs/backlog/completed.md 35 Done
docs/backlog/active-sprint.md 0 empty since it was added

Statuses mapped TODO/DEFERREDBACKLOG, IN_PROGRESSIn progress, DONEDone.
The board went from 80 items to 165.

Draft issues, not real issues — nothing was created in the repository's issue tracker.

The import already happened. This pull request is only the removal half. If you close it, the
board keeps the entries and docs/backlog/ keeps working exactly as it does today; you would have a
duplicate rather than a breakage. That is the current state, and it is why this exists: one backlog
in two places is worse than either arrangement alone.

What this touches besides the deletion

CLAUDE.md's Backlog Management section is rewritten, not removed. Same rules, same statuses,
same priorities, same entry format — pointing at the board and describing an item instead of a
markdown section. Deleting the files without this would leave CLAUDE.md naming four paths that no
longer exist, which is the exact defect class of ISSUE-034.

Three differences are stated in CLAUDE.md rather than left to be discovered:

  • the board has no BLOCKED or DEFERRED status. Both import as BACKLOG. One entry is affected,
    IMPROVEMENT-035, which was DEFERRED
  • the board has no priority field, so Priority stays in the item body
  • reading the board needs the read:project scope, which a fresh gh token does not carry —
    gh auth refresh -h github.com -s project

docs/superpowers/plans/ and docs/superpowers/specs/ reference docs/backlog/ about thirty times
and are left untouched. Both are dated records of work already done and were accurate when
written; rewriting them would be rewriting history rather than documenting the present. The
identifiers they cite still resolve, because the board keeps them in the title.

Two things found while importing

Reproduced on the board as-is rather than silently reconciled, because they are your records to fix:

  1. IMPROVEMENT-018 is used twice, both inside completed.md — once for "New Robot dialog UX
    improvements" and once for "Season Config: Activity Points Scoring Mode". The second heading
    carries a (Season Config) qualifier, which is presumably how it survived.
  2. IMPROVEMENT-024 appears in both improvements.md and completed.md. Same defect class as
    ISSUE-031 and ISSUE-032, which Move ISSUE-033 and ISSUE-034 to completed.md, and finish ISSUE-034 in docs/codebase #22 asked about and which is still open: CLAUDE.md says completed
    items move to completed.md, and the files show that sometimes they get copied instead.

Why you might not want this

Stating the case against, because it is real:

  • The board is titled "Game Server" and had tracked PerpetuumServer, OP-Project, OPDB and
    OPDiscordBot. It had never held a PerpetuumServer2 item. This makes server2 the majority of it.
  • A markdown file in the repository is greppable, diffable, reviewable in a pull request, and
    available offline. A project board is none of those.
  • Board access is an organisation permission. Anyone who can clone the repository can read
    docs/backlog/; not everyone who can clone it can read the board.

If any of that outweighs having one home for the backlog, close this. The alternative middle ground —
blanking the files and leaving a pointer to the board — is a smaller change and I am happy to send
that instead.

All 85 entries from docs/backlog/ now exist as draft issues on the Game Server
board, https://github.com/orgs/OpenPerpetuum/projects/6, each keeping its
ISSUE-NNN / IMPROVEMENT-NNN identifier in the item title and its full body
text. Statuses were mapped onto the board's Status field: TODO and DEFERRED to
BACKLOG, IN_PROGRESS to In progress, DONE to Done.

This commit removes the four files so the backlog has one home rather than two.
Their content remains in git history.

  docs/backlog/issues.md          21 entries
  docs/backlog/improvements.md    29 entries
  docs/backlog/completed.md       35 entries
  docs/backlog/active-sprint.md   0 bytes, empty since it was added

CLAUDE.md's Backlog Management section is rewritten rather than deleted. It
still carries the same rules, statuses, priorities and entry format; it now
points at the board and describes an item instead of a markdown section. Three
differences are stated there explicitly rather than left to be discovered:

  - the board has no BLOCKED or DEFERRED status, so both import as BACKLOG
  - the board has no priority field, so Priority stays in the item body
  - reading the board needs the read:project scope, which a fresh gh token does
    not carry

References under docs/superpowers/plans/ and docs/superpowers/specs/ are left
untouched. Both are dated records of work already done and were accurate when
written; rewriting them would be rewriting history rather than documenting the
present. The item identifiers they cite still resolve, because the board keeps
them in the title.

Two duplicate identifiers surfaced while importing and are reproduced on the
board as-is rather than silently reconciled:

  - IMPROVEMENT-018 is used twice in completed.md, for "New Robot dialog UX
    improvements" and for "Season Config: Activity Points Scoring Mode"
  - IMPROVEMENT-024 appears in both improvements.md and completed.md
@meketreve

Copy link
Copy Markdown
Contributor Author

Closing this. The destination was weaker than what it replaced, and I should have checked before
opening it.

The 85 entries were imported to the board as draft issues, and a draft issue supports only a
title, a body and assignees. It has no number, no URL, no comments, and no linked pull requests. So a
draft cannot be referenced from a commit or a pull request, cannot be discussed, and can never
populate the board's "Linked pull requests" column. Deleting docs/backlog/ in favour of that would
have traded a greppable, diffable, reviewable file for something that cannot even be cited in a commit
message.

GitHub Issues already covers what this was reaching for — assignee, discussion, cross-references and
automatic closing from a pull request — and this repository has issues enabled with none filed, while
the org's other repositories run on them.

Nothing was deleted. docs/backlog/ is untouched on develop.

Two findings from the import are worth keeping regardless of this pull request, and I will raise them
separately rather than let them close with it:

@meketreve meketreve closed this Aug 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant