From e3d4efdeb939e7b63d9958135144f85eb3a7aad6 Mon Sep 17 00:00:00 2001 From: Evan Vetere Date: Tue, 28 Jul 2026 13:44:11 -0400 Subject: [PATCH] docs: extend concision rules to GitHub prose The "Be concise" rule was scoped to responses and code comments, so PR descriptions and issue bodies kept accumulating restated summaries and checklists that duplicated prose already above them. Extend the rule to GitHub prose and name the specific failure modes, alongside the existing hard-wrap scope note. Key changes: - Add a GitHub PR / Issue / Comment Conventions section - Require saying things once, leading with the problem, and cutting words that carry no fact, while compressing rather than omitting --- CLAUDE.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index f7c80b2e..1dc12006 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -197,3 +197,16 @@ Key changes: descriptions, GitHub issues, and comments render as GitHub-flavored markdown — do not hard-wrap them; let prose reflow naturally and only break lines where markdown needs it (lists, tables, code fences). + +## GitHub PR / Issue / Comment Conventions + +The "Be concise" rule above governs responses and code comments. It applies to +GitHub prose too. + +- **Say it once.** Do not describe the same behaviour in prose and again in a + checklist, or restate the summary in the test plan. Reference it instead. +- **Lead with the problem** in plain language, then what changed and why. Push + implementation detail into bullets or a follow-up, not the summary. +- **Cut every word carrying no fact.** One dense paragraph beats three that + re-sell the same point. Brevity must not drop facts — compress, do not omit. +- **Don't hard-wrap** prose (see the commit section above).