| 1 | # đŸ¤– Review brief: the platform changelog spec |
| 2 | |
| 3 | You are reviewing `docs/superpowers/specs/2026-10-06-platform-changelog-design.md` |
| 4 | in this repo (carlos/platform), at the commit you are run on. You are the |
| 5 | independent second reader; the author is Claude. |
| 6 | |
| 7 | The website it renders on is a separate checkout at |
| 8 | `/home/paulca/github.com/carlosframework/website` (read `AGENTS.md`, |
| 9 | `eleventy.config.js`, `hack/sync-docs.mjs`, `hack/check-docs.mjs` there). |
| 10 | |
| 11 | ## Fixed: do not reopen |
| 12 | |
| 13 | The four rulings at the top of the spec are Paul's. Report only where the |
| 14 | mechanism fails to honour them, not whether they are right. |
| 15 | |
| 16 | ## What to look for |
| 17 | |
| 18 | 1. **Wrong facts.** Check every claim in "What exists" against the repo: |
| 19 | run `git log --first-parent`, `git for-each-ref refs/amadan/closed` |
| 20 | (may need `git fetch origin '+refs/amadan/closed/*:refs/amadan/closed/*'` |
| 21 | first; if you cannot fetch, say so), and read `internal/docsite`. |
| 22 | 2. **Mechanisms that produce wrong output.** Branch-name parsing, the |
| 23 | own-commit ranges (squash with tombstone, two-parent merge, direct), |
| 24 | credit resolution, discussion-number filtering, docs-link derivation, |
| 25 | notes parsing across both shapes. Name a concrete commit or tag in |
| 26 | this repo where the rule gives a wrong or misleading line. |
| 27 | 3. **Privacy and accuracy on a public page.** Anything that could publish |
| 28 | an email address, a private repo link, or credit the wrong person. |
| 29 | 4. **Gaps the gate misses.** What could be wrong in the committed JSON |
| 30 | and still pass `changelog_test.go` and the website's check. |
| 31 | 5. **Scope.** Anything that should be cut. |
| 32 | |
| 33 | ## Output |
| 34 | |
| 35 | A numbered list of findings, each with severity (P1 breaks the page or |
| 36 | publishes something wrong; P2 misleading or fragile; P3 nit), the spec |
| 37 | line it is about, the evidence (command and output, or file:line), and a |
| 38 | proposed fix. Then a one-line verdict: accept, accept with fixes, or |
| 39 | reject. Do not edit any file. |
| 40 | |
amadan