docs(cold-read): rename to cold-read-changelog.md + add cold-read-adopter.md (second-surface-is-real trigger from #326) #366

New issue

Closed

opened 2026-07-04 08:35:38 +02:00 by bosun · 0 comments

bosun commented

2026-07-04 08:35:38 +02:00

Owner

Motivation

Herald flagged during #326 review (2026-07-03): "if the adopter-docs cold-read ever gets an in-repo home, THAT's the clean moment for a paired rename." That trigger is now firing.

First surface: docs/cold-read-prompt.md (Changelog Verifier, in-repo since #326) — the mechanical + editorial review companion to the changelog-body-check.yml linter.

Second surface (newly real): the full-project adopter-simulation cold-read prompt used to prime outside-model reviewers (fresh ChatGPT / Claude sessions). Currently canonical at BookStack release-toolkit book page 212 (https://docs.saratow.net/books/release-toolkit/page/cold-read-prompt-full-project-adopter-simulation). Used successfully in rounds 1, 2, 3 (2026-07-03/04) to grade v1.0.0 candidate; primed the reviews that produced tracker clusters #329-#338 + #355-#360.

Scope

Rename docs/cold-read-prompt.md → docs/cold-read-changelog.md. Distinguisher leads (matches Herald H1 rename in #326: "Changelog Cold-Read Prompt").
Add docs/cold-read-adopter.md with the full-project prompt from BookStack page 212. Preserve the v2 changelog + related links.
Update inbound references to the renamed file:
- docs/integration.md — cold-read linter reference
- changelog.d/.template.md — cold-read prompt link
- .forgejo/workflows/reusable-changelog-body-check.yml — comment reference
- Any other files grep finds
Update BookStack:
- Page 208 (legacy Changelog Verifier): add deprecation-pointer to in-repo canonical (already noted as legacy)
- Page 212 (this new adopter-simulation page): add deprecation-pointer to in-repo canonical
Verify: grep -rn cold-read-prompt.md returns zero hits post-merge; all references updated to the split filenames.

Verification AC

docs/cold-read-changelog.md exists with the current changelog-verifier content
docs/cold-read-adopter.md exists with the full-project prompt from BookStack page 212
All inbound references updated
BookStack pages 208 + 212 have deprecation-pointers to in-repo canonicals
Grep for cold-read-prompt.md returns zero hits in-repo

Post-v1.0.0 timing

This is deliberately post-v1.0.0 work to avoid in-repo churn during the cut chain. The BookStack page 212 canonical serves the maintainer workflow in the interim.

Anchor

Herald naming-decision trigger from PR #326 review + BookStack page 212 creation 2026-07-04. Sibling to feedback_scoped_mechanism_vs_open_substrate class discipline (second-surface trigger fires cleanly rather than premature-refactor).

## Motivation Herald flagged during #326 review (2026-07-03): "if the adopter-docs cold-read ever gets an in-repo home, THAT's the clean moment for a paired rename." That trigger is now firing. **First surface**: docs/cold-read-prompt.md (Changelog Verifier, in-repo since #326) — the mechanical + editorial review companion to the changelog-body-check.yml linter. **Second surface** (newly real): the full-project adopter-simulation cold-read prompt used to prime outside-model reviewers (fresh ChatGPT / Claude sessions). Currently canonical at BookStack release-toolkit book page 212 (https://docs.saratow.net/books/release-toolkit/page/cold-read-prompt-full-project-adopter-simulation). Used successfully in rounds 1, 2, 3 (2026-07-03/04) to grade v1.0.0 candidate; primed the reviews that produced tracker clusters #329-#338 + #355-#360. ## Scope 1. **Rename** `docs/cold-read-prompt.md` → `docs/cold-read-changelog.md`. Distinguisher leads (matches Herald H1 rename in #326: "Changelog Cold-Read Prompt"). 2. **Add** `docs/cold-read-adopter.md` with the full-project prompt from BookStack page 212. Preserve the v2 changelog + related links. 3. **Update inbound references** to the renamed file: - `docs/integration.md` — cold-read linter reference - `changelog.d/.template.md` — cold-read prompt link - `.forgejo/workflows/reusable-changelog-body-check.yml` — comment reference - Any other files grep finds 4. **Update BookStack**: - Page 208 (legacy Changelog Verifier): add deprecation-pointer to in-repo canonical (already noted as legacy) - Page 212 (this new adopter-simulation page): add deprecation-pointer to in-repo canonical 5. **Verify**: `grep -rn cold-read-prompt.md` returns zero hits post-merge; all references updated to the split filenames. ## Verification AC - `docs/cold-read-changelog.md` exists with the current changelog-verifier content - `docs/cold-read-adopter.md` exists with the full-project prompt from BookStack page 212 - All inbound references updated - BookStack pages 208 + 212 have deprecation-pointers to in-repo canonicals - Grep for `cold-read-prompt.md` returns zero hits in-repo ## Post-v1.0.0 timing This is deliberately post-v1.0.0 work to avoid in-repo churn during the cut chain. The BookStack page 212 canonical serves the maintainer workflow in the interim. ## Anchor Herald naming-decision trigger from PR #326 review + BookStack page 212 creation 2026-07-04. Sibling to feedback_scoped_mechanism_vs_open_substrate class discipline (second-surface trigger fires cleanly rather than premature-refactor).

bosun added the

priority/medium

size/S

kind/docs

labels

2026-07-04 08:35:38 +02:00