From 7cb7aa345578a1a8002d0d7b2fc73a450f2d1e08 Mon Sep 17 00:00:00 2001 From: budhash Date: Mon, 13 Jul 2026 15:45:11 -0700 Subject: [PATCH] docs: LEARNINGS entry for v1.3.0 renumber Record the mutate-structure/report-prose design split, the value of committing specs alongside the PR, and the short-form ID reference surface. --- LEARNINGS.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/LEARNINGS.md b/LEARNINGS.md index f0cdfdf..cbe8aee 100644 --- a/LEARNINGS.md +++ b/LEARNINGS.md @@ -3,6 +3,26 @@ Insights, gotchas, and decisions worth remembering — newest first. For *what* changed see `CHANGELOG.md`; this file records *why* and what it taught us. +## 2026-07-13 — v1.3.0 (`renumber`) + +- **Mutate structure, report prose.** The renumber design's key call (made + explicitly with the user): the tool rewrites only *structured* references it + can identify positionally (`@deps`/`@rel` tag regions, the `## ` notes + header, shadow lines) and merely *reports* free-text mentions (`--refs`, + read-only, repo-wide). Auto-rewriting prose is the #9 false-positive class + in write form; leaving it to the operator keeps the tool trustworthy. This + "detect, don't rewrite" split is the template for #14 (`validate --refs`). +- **Design decisions made in chat evaporate; specs in-repo don't.** The + renumber design sat approved-but-unwritten for ten days across sessions. + Committing `docs/superpowers/specs/…-renumber-design.md` with the PR means + the *why* (no `--force`, refuse-occupied, `--next`) survives the + conversation that produced it. +- **Short-form IDs are part of the reference surface.** Hand-written + `@deps=T-12` and prose `T-12` both mean `T-0012`. The repoint path gets this + free (parse_id_list normalizes), but the `--refs` scanner needed an explicit + `\bT-0*12\b` pattern — matching short forms without swallowing `T-00123`. + Any future reference-scanning feature (#14) must handle both forms too. + ## 2026-07-13 — v1.1.2 / v1.2.0 (shadow-sync fix, `set --title`) - **"First match in file order" is a bug class, not a bug.** `set_tag`,