From 8b2e4121dd273a30b3585df3ba725d2097b26c29 Mon Sep 17 00:00:00 2001 From: null Date: Mon, 17 Aug 2026 22:49:23 -0500 Subject: [PATCH] docs(tracker): the milestone naming this template teaches truncates on the card MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit forgejo-issue.py warns that a milestone title starting with a version token has everything after it dropped from the dashboard phase -- `0.2 Payments` displays as `0.2`. README.md was teaching exactly that form, and two adopted repos followed it: Closer-Couples and fruit-fall both carry version-first titles and lose their batch names on the card. PrivacyLLC-Web uses `Batch 05 — ...` and displays whole. The guidance now names the working form, and carries the comma rule the script also enforces: a comma breaks the `milestones=` filter and the card shows the wrong next action. WORK_CYCLE.md gains the trap the same script documents and no document did: the dashboard's next action is the NEWEST open issue in the current milestone, not the most severe -- severity labels have no influence at all. Filing a routine P2 into the active batch silently replaces what the project card shows. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 11 ++++++++--- docs/WORK_CYCLE.md | 8 ++++++++ 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 52272d6..705e9e6 100644 --- a/README.md +++ b/README.md @@ -191,9 +191,14 @@ nothing. ### The rules -- **Milestone = batch.** Name it `0.2 Payments`. The description says what the - batch is for and how anybody will know it landed. A due date means a - commitment — leave it empty rather than inventing one. +- **Milestone = batch.** Name it `Batch 02 — Payments`, and **start it with a + word rather than a version number**: the dashboard reads a leading version + token as the whole phase and drops the rest, so `0.2 Payments` displays as + `0.2` and the batch loses its name on the project card. No comma either — a + comma breaks the `milestones=` filter and the card shows the wrong next + action. The description says what the batch is for and how anybody will know + it landed. A due date means a commitment — leave it empty rather than + inventing one. - **Issue = deliverable.** One per item, in its milestone, ending with a `Verify:` line stating the acceptance check. - **Labels:** `P0` ships broken or loses data · `P1` materially wrong but diff --git a/docs/WORK_CYCLE.md b/docs/WORK_CYCLE.md index 4122746..e454875 100644 --- a/docs/WORK_CYCLE.md +++ b/docs/WORK_CYCLE.md @@ -76,6 +76,14 @@ Monday, specific enough to begin without asking a question. "Continue the work" is not one. If the honest answer is that you do not know, that is a real answer — say what has to be decided and by whom. +**Filing an issue can change what the project card says next, without anyone +choosing that.** The dashboard's next action is the *newest open issue in the +current milestone* — not the most severe one; severity labels have no influence +on it at all. So a routine `P2` filed into the batch you are working in replaces +whatever the card was showing, and it will keep showing that until something +newer arrives. The `nextAction` field is the only way to say something different +on purpose, which is most of why step 7 exists. + `currentSummary`, `nextAction` and `description` are **write-only**: they are deliberately absent from every API response, because free text can name a customer or an unannounced product. Only the admin screen shows them back. Never