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
24 lines
1.9 KiB
Markdown
24 lines
1.9 KiB
Markdown
## 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.
|