Reconcile docs with the constitution's Requirements authoring section - #25
Merged
Merged
Conversation
The merged constitution (§ Requirements authoring) codifies prose doctrine
the documents were meant to embody: plain words over jargon-idiom, no
intensifiers or self-description, rationale out of binding statements. Bring
the existing documents into conformance.
- Plain words over jargon-idiom (constitution's exact swaps), everywhere:
"happy path" → "the common case", "escape hatch" → "fallback",
"footgun" → "error-prone". Touches formwork.md, fep-4.md, the default
profile comment, IMPLEMENTATION_PLAN.md, and docs/{competition-research,
mcp-tool-patterns,unstated-requirements,usability-review}.md and the codex
example. "common path" in formwork.md §1 folded to "the common case" so the
spec uses one phrasing.
- formwork.md (the cited exemplar) and fep-4.md: drop banned intensifiers and
self-description ("actually", "real mechanism", "critically", "deliberate
choice", "Note that") and significance-only tails. FW-INV5 loses its
"load-bearing invariant ... hand-wavy" coda so the statement stands alone;
the §5.10 intro drops the "single most valuable ... sharpest tradeoff"
superlative while keeping the confused-deputy substance.
Requirement IDs, anchors, and links are unchanged; the test_requirements.py
canary passes. The constitution itself and Rust code comments (governed by
§ Comments, not requirements authoring) are left as-is.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011agPfWKjH7H2oDaqiZyvnz
…nstitution
Follow-up to the reconciliation pass.
- Remove the "load-bearing" and "paved road" metaphors everywhere (docs, the
default profile, and the three Rust comments that used them), replacing each
with a plain word in context — "central", "essential", "decisive", "the
default path", "what protects you", "nothing depends on it".
- Give constitution.md the same authorship pass the other documents got, on
its own genuine usages (the rule-definition lines that quote banned words as
examples are left intact):
- jargon-idiom: "legal escape hatch" → "lawful exception"; "grep
expedition" → "manual search"; "load-bearing rule" → "central rule".
- intensifiers/self-description: drop filler "actually" (HostProfile,
Testing rationale) and redundant "real" ("real regressions"/"a real
probe" → "regressions"/"a probe"; the real-vs-mock term stays where it
draws the distinction).
- aphorism/personification: cut "restraint is what made good tools good"
and "the threat model walking in the door"; trim "not a lecture".
Requirement IDs, anchors, and links unchanged; the test_requirements.py canary
passes. Comment-only Rust edits — no behavior change.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011agPfWKjH7H2oDaqiZyvnz
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.
The merged constitution (§ Requirements authoring) codifies prose doctrine
the documents were meant to embody: plain words over jargon-idiom, no
intensifiers or self-description, rationale out of binding statements. Bring
the existing documents into conformance.
Plain words over jargon-idiom (constitution's exact swaps), everywhere:
"happy path" → "the common case", "escape hatch" → "fallback",
"footgun" → "error-prone". Touches formwork.md, fep-4.md, the default
profile comment, IMPLEMENTATION_PLAN.md, and docs/{competition-research,
mcp-tool-patterns,unstated-requirements,usability-review}.md and the codex
example. "common path" in formwork.md §1 folded to "the common case" so the
spec uses one phrasing.
formwork.md (the cited exemplar) and fep-4.md: drop banned intensifiers and
self-description ("actually", "real mechanism", "critically", "deliberate
choice", "Note that") and significance-only tails. FW-INV5 loses its
"load-bearing invariant ... hand-wavy" coda so the statement stands alone;
the §5.10 intro drops the "single most valuable ... sharpest tradeoff"
superlative while keeping the confused-deputy substance.
Requirement IDs, anchors, and links are unchanged; the test_requirements.py
canary passes. The constitution itself and Rust code comments (governed by
§ Comments, not requirements authoring) are left as-is.
Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_011agPfWKjH7H2oDaqiZyvnz