SPEC structure: the 24 files #1570 missed, a section sdd.md forbids, and three worked examples - #1572
Merged
Merged
Conversation
Three things, in increasing order of how much judgement they took. #1570 renamed the footer in every `*.SPEC.md` and missed the 24 `SPEC.md` files — the directory-level ones, including the root. They still said "Before writing", which is the wording that let me read the rule as "authoring a new file" and edit six SPECs without opening the spec at all. They now say what the others say. `event-stream.SPEC.md` carried a `## Notes` section, which sdd.md does not list and says never to invent. What it held was the history of a deleted package and a type-parameter detail — one belongs in git, the other in the code. The third is the part that cannot be done in bulk. sdd.md defines `## TLDR` as a summary of the content below it, and (since brillout/sdd@d6f417f) says `## Flows` describes what the code does with no context and no history, which goes in `## Rationales`. 180 SPEC files here have a TLDR and nothing below it: one bullet list carrying flows, rationale and history together, summarising nothing. Three are restructured here as worked examples — the gitignore, the repo config, and the agent store, which is the biggest of them. Same content, sorted: what it does under Flows, why it is that way under Rationales, and a TLDR that is now actually a summary. The other 177 are left for a decision rather than a script. Splitting a bullet into what-happens and why is a judgement per sentence; done mechanically across 177 files it would produce exactly the prose the spec exists to prevent, in someone else's voice. The three here are what the answer looks like — if it is the right answer, the rest is a known, finite job. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PGg6YdQthErYV63HRVPzrw
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Finding 7 from the #1536 review, kept separate from the code fixes in #1571. Independent of that PR — no overlapping files.
The 24 files #1570 missed
#1570 renamed the footer to
## Before modifying/creating SPEC.md filesin every*.SPEC.md. It matched that pattern, so it skipped the 24 directory-levelSPEC.mdfiles — including the rootSPEC.mdand every package and subsystem one. They still said "Before writing SPEC.md files" and "Read" rather than "Always read and respect".Worth naming why that wording matters, since I am the evidence: "before writing" is what I read as authoring a new file, which is how I edited six SPECs in
10f280cwithout opening the spec at all. The files most likely to be read first were the ones still carrying it.A section sdd.md forbids
event-stream.SPEC.mdhad a## Notessection. sdd.md lists the allowed sections and says never to invent others. What it held: the history of a package that was deleted, and a note that a type parameter is required — one belongs in git, the other in the code. Removed.After both, every one of the 543 SPEC files carries the required section, uses only sections sdd.md lists, and orders them as the spec does.
The part that cannot be done in bulk — and a decision to make
sdd.mddefines## TLDRas "a summary of the content below", and since brillout/sdd@d6f417f says## Flowsdescribes what the code does with no context and no history, which belongs in## Rationales.180 SPEC files here have a TLDR and nothing below it — one bullet list carrying flows, rationale and history together, summarising nothing. (333 files are a single sentence, which the spec explicitly allows; 21 have Rationales, 7 have Flows.) That means the new Flows rule has nothing to bite on, and the altitude defect I introduced in my own six SPECs was structurally invited.
Three files are restructured here as worked examples —
framework-gitignore,config, andstore/agent-store, the biggest of them. Same content, sorted: what it does under Flows, why it is that way under Rationales, and a TLDR that is now actually a summary.The other 177 are left for your call rather than a script. Splitting a bullet into what-happens and why is a judgement per sentence; done mechanically across 177 files it would produce exactly the prose the spec exists to prevent, in your voice rather than mine. The three here are what the answer looks like — if it is the right answer, the rest is a known and finite job, and I would rather do it with a yes than assume one.
Verification
Docs only — no source, no test, no build input changed. A conformance check over all 543 files reports no violations: required section present everywhere, no section sdd.md does not list, and TLDR → Flows → Rationales in that order wherever they appear.
Generated by Claude Code