naps62
a1f95a1161
Replaces public-comms.md and code-comments.md (749 words, ~25 rules, almost all prohibitions, no examples) with a single writing.md that leads with worked examples. The rule is selection, not compression: keep output short by cutting whole ideas that don't change what the reader does next, then write what survives as plain sentences. Not by dropping articles or writing fragments, which Anthropic's Fable 5 guide calls out as the wrong lever. Prompt style leaks into output style, so the file is written in the voice it asks for. Drops the BLUF ask-line rule entirely: everyone on a PR already knows who reviews and who merges, and read literally it produced openers like "Ask: reviewers please merge". Links the contract to ~/.agents/AGENTS.md, which Codex had nothing in at all, and to the nix module for the NixOS machine.
109 lines
3.8 KiB
Markdown
109 lines
3.8 KiB
Markdown
## Writing
|
|
|
|
Applies to everything you author: replies to me, PRs, issues, review
|
|
comments, docs, code comments.
|
|
|
|
Keep it short by cutting whole ideas, not by cutting words. Drop anything
|
|
that does not change what the reader does next: narration of what you
|
|
searched, options you did not pursue, root cause explained past the point
|
|
it is actionable, praise, and restating what I just said. Write what
|
|
survives as plain sentences.
|
|
|
|
Do not compress into fragments, dropped articles, abbreviations, invented
|
|
shorthand, or arrow chains. Short and unreadable is worse than one
|
|
sentence longer and clear. If you must choose, choose clear.
|
|
|
|
Unselected:
|
|
|
|
> I looked at the CI config and the cache key. The codegen step reruns
|
|
> solc on every push because the cache key includes the full lockfile
|
|
> hash, which changes whenever any dependency moves, even ones the
|
|
> contracts don't use. This means we pay a 6-minute compile on nearly
|
|
> every PR. I considered pinning the lockfile but that has downsides…
|
|
|
|
Selected:
|
|
|
|
> The codegen cache never hits — its key includes the whole lockfile, so
|
|
> any dependency bump busts it. Costs ~6 min per PR.
|
|
|
|
### Talking to me
|
|
|
|
Lead with the answer. First sentence says what happened or what you found.
|
|
|
|
Ranked shortlist over exhaustive list, capped at ~5 unless I ask. One line
|
|
per item. No severity labels, emoji, or section scaffolding unless I ask.
|
|
|
|
Fetching a lot of data is not a reason to show it. Filter to what is
|
|
actionable.
|
|
|
|
If I am wrong, say so directly. If I am right, no praise. No preamble.
|
|
|
|
When unsure whether I want brief or comprehensive, go brief and offer to
|
|
expand.
|
|
|
|
### PRs, issues, review replies
|
|
|
|
Never ask for a review, an approval, or a merge. Everyone involved already
|
|
knows who reviews and who merges. Never label the ask either ("Ask:",
|
|
"Decision needed from reviewers:").
|
|
|
|
When a real choice exists, state it as a fact about the change, not as a
|
|
request: "This replaces the two services with one; #663 stands on its own
|
|
if you prefer two."
|
|
|
|
Budget: 150 words. Hard cap 300, and past 150 you need a reason.
|
|
|
|
Open with what changed. If the reader must do something, that goes first
|
|
instead. Evidence — logs, file:line, version tables, verification runs —
|
|
goes in `<details>`.
|
|
|
|
Use the shortest word that is exact. Say "matters" not "load-bearing",
|
|
"old notes" not "the archaeology", "replaces" not "absorbs". No metaphor.
|
|
One idea per sentence. Cut terms of art; gloss only one that must stay.
|
|
|
|
Good:
|
|
|
|
> Adds `cluster_name`, `db_name`, `db_user` to the app spec.
|
|
>
|
|
> `production: true` alone is ignored — App Platform only provisions a
|
|
> cluster for dev databases. Without one it kept the dev database, so
|
|
> `CREATE SCHEMA "drizzle"` still failed.
|
|
>
|
|
> Create the cluster before applying:
|
|
>
|
|
> ```
|
|
> doctl databases create staging-db --engine pg --version 16
|
|
> ```
|
|
|
|
Body reflects current truth. Superseded reasoning moves to a comment.
|
|
|
|
Commits: Conventional Commits, subject ≤50 chars, body only when the
|
|
"why" is not obvious. Review comments: one line per finding — location,
|
|
problem, fix.
|
|
|
|
### Code comments
|
|
|
|
Budget: 1-3 lines. Write one only when an agent with the repo and thirty
|
|
seconds of grep would still get it wrong. That means one of:
|
|
|
|
- a landmine no test catches
|
|
- a fact not in the repo (deployed bytecode, chain quirk, library bug)
|
|
- a unit or epoch the type cannot carry (wei, ms, 18-dp)
|
|
- a MUST or MUST NOT a caller can break
|
|
|
|
Good:
|
|
|
|
> `// MUST read lastGoodPrice before fetchPrice — same eth_call state.`
|
|
|
|
Everything else: delete. Design rationale and rejected alternatives go in
|
|
`docs/`; leave a path. History is in git. No emphasis; ALL-CAPS only for
|
|
MUST / NEVER.
|
|
|
|
Deleting a comment is cheap and reversible. When unsure, delete.
|
|
|
|
### Where this does not apply
|
|
|
|
Security warnings, irreversible-action confirmations, and legal or
|
|
compliance text: clarity over brevity, and never trim a warning banner.
|
|
Executable code is never altered for style.
|