naps62
08195c1cd4
comms-lint.py and comment-lint.py lived only in ~/.claude, which is not a git repo. Contract prose lived in ~/.claude/CLAUDE.md. Neither survived a machine rebuild. Prose moves to claude-md/ fragments, imported via @name.md. Linters move to hooks/. link.sh and home.nix distribute both. settings.json wiring stays manual — it holds machine-local MCP/statusline config this repo must not own. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VaGR6ERGCfzWTtuv2rebGe
1.9 KiB
1.9 KiB
Public comms — issues, PRs, review comments
Overrides the caveman skill's "Code/commits/PRs: write normal" boundary. Normal prose, but these rules bind. Enforced by ~/.claude/hooks/comms-lint.py.
Structure (BLUF — bottom line up front):
- Line 1 is the ask. What decision or action do I want, from whom. Never make the reader reach the end to find it.
- Line 2-3 is the consequence in plain words a non-engineer PM would follow. "If we find a bug after launch we cannot fix it" — not "nothing bound to a compliance is upgradeable".
- Then: problem, options, proposed work. In that order.
- ≤300 words above the fold. Everything else — file:line cites, version tables, upstream verification, transcript evidence — goes inside
<details><summary>Evidence</summary>or a follow-up comment. - State the appetite when proposing work: roughly how much time this is worth.
Language:
- One concept per sentence. Break compound sentences with two or more subordinate clauses.
- Every term of art gets a plain-language gloss on first use, or gets cut. Assume the curse of knowledge is operating — I am the last to notice which labels are load-bearing jargon.
- No self-invented shorthand ("degrade-don't-brick guard", "blocking-adjacent", "identity-aggregating"). Say the thing.
- Bold ≤4 spans per document. No italics for emphasis or tone.
- Headings name their contents (Problem / Options / Work / Evidence). Not essay headings ("What is actually the case", "The third option", "What this is not for").
Content:
- Three or more alternatives go in a table: Option | What we do | Cost | What we get. Never prose sections.
- Scope exclusions get one line. Do not re-litigate a decided ADR or pre-empt objections nobody raised.
- Body reflects current truth. Superseded reasoning moves to a comment — never leave a dead decision above the live one.
Refs: BLUF (US Army), inverted pyramid, Pinker's curse of knowledge, Google Technical Writing One, Shape Up pitch.