diff --git a/.claude/skills/elfuse-conventions/SKILL.md b/.claude/skills/elfuse-conventions/SKILL.md index 08228a69..efe12395 100644 --- a/.claude/skills/elfuse-conventions/SKILL.md +++ b/.claude/skills/elfuse-conventions/SKILL.md @@ -1,6 +1,6 @@ --- name: elfuse-conventions -description: elfuse conventions outside CONTRIBUTING.md. Use when adding, reviewing, or reducing prose in source comments, docstrings, README.md, or docs/*.md; drafting a commit message, PR description, or review reply; adding a file or type; touching an atomic or lock-free access; handling untracked working docs; or wiring the build to a tool absent from a fresh clone. +description: elfuse conventions outside CONTRIBUTING.md. Use when adding, reviewing, or reducing prose in source comments, docstrings, README.md, or docs/*.md; drafting a commit message, PR description, or PR or issue comment; adding a file or type; touching an atomic or lock-free access; handling untracked working docs; or wiring the build to a tool absent from a fresh clone. --- # elfuse conventions @@ -380,6 +380,12 @@ reflow is the precedent. ## Pull requests +Remove all mannered prose. This binds every comment posted on a PR or +issue, by a person or an agent. A reply is a few plain sentences, no +longer than the comment it answers unless it carries a measurement or a +reproduction. Use a list only when the reply answers several separate +review points. + A PR thread is human collaboration, and agent-shaped artifacts are rejected on sight: no pasted walkthroughs or summaries ("We are humans. Don't copy agent-specific reply here.", PR#116), no severity or status tables ("We're diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..71e2b578 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,15 @@ +# Agent instructions + +Mannered prose substitutes metaphor and flourish for direct statement. +Instead of "a parameter worth varying," the mannered writer produces "a dial +worth turning." Instead of "this point still matters," they write "this point +earns its keep." The phrases exist to display the writer, not to convey the +idea, and readers can tell. That is why mannered prose irritates: it makes the +reader work harder so the writer can perform. It is also imprecise. Metaphors +drag in connotations the writer did not choose and cannot control. The fix is +to say what you mean. When a literal phrase is available, use it. + +This covers code comments, commit messages, and every comment posted on a +PR or issue. Read `.claude/skills/elfuse-conventions/SKILL.md`, sections +"Comments", "Commit messages", and "Pull requests", before writing any of +them.