Skip to content

roadmap.md has become the journal its own header says the issues are for: decide what it is, and move the history #577

Closed

Description

@Gerrrt

What the file says it is, and what it is

docs/roadmap.md opens: "This file is the shape of the work — what is outstanding, and why it is in this order. Whether a thing is started, blocked or done is on its issue. Two places holding the same checkbox is how a checkbox stops being true."

It is 2,791 lines. Everything still to buy carries eleven dated paragraphs — 2026-09-11, 09-13 twice, 09-17 twice, 09-18, 09-19 twice, 09-20 — narrating each purchase, arrival and fit, before the table they describe. The Infrastructure entry for #92 runs to some sixty lines and includes the wrong-account bug, the .part fragments and the zsh glob. The #102 entry is longer. Every one of those sentences was true and worth writing on the day; together they are the journal the header says the issues are for, kept in the one file that promised not to be one.

Two costs, both already paid once:

What to decide

  • What the file is for, in one sentence that the header can keep: the ordered shape of open work, or the estate's changelog. Not both.
  • Where the history goes if it leaves: a docs/changelog.md in the same voice, the ADRs' own dated notes (many of these paragraphs are amendments in all but location), or the closed issues, which already hold most of it verbatim.
  • What a roadmap entry is allowed to contain once the file is the shape: a link, the gate, the order, and why — and the rule that a Done entry moves rather than accretes.
  • Whether the Everything still to buy section survives at all now that the buy table is two rows and check_buy_list ties it to the README.

Done when

The header's sentence is true of the file below it, the history it carried is findable somewhere with a date, and the file is short enough that the next drift fix is one line rather than six.

Refs #536, #487, #486. Documentation only; no host changes.

Activity

  1. added this to the Nothing blocks these milestone on Sep 20, 2026
  2. added
    documentationImprovements or additions to documentation
    seq/1Step 1 within its milestone; same number = can run in parallel
    on Sep 20, 2026
  3. added 4 commits that reference this issue on Sep 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationseq/1Step 1 within its milestone; same number = can run in parallel

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions