From 892d5b6bab8dadfcfec73e786fa4540210cd826d Mon Sep 17 00:00:00 2001 From: Evan Vetere Date: Wed, 29 Jul 2026 13:00:37 -0400 Subject: [PATCH] docs: sharpen concision rules for GitHub prose "Be concise" was too soft to act on: PR bodies restate the summary as test-plan checkboxes and re-sell the same point across paragraphs, and nothing in the skill named that as wrong. Key changes: - Add "say it once" and "cut every word carrying no fact" as Core Principles, with a compress-don't-omit clause so brevity never costs facts - Add matching rows to the PR "What to Avoid" table --- CHANGELOG.md | 6 ++++++ plugins/datum-platform/.claude-plugin/plugin.json | 2 +- plugins/datum-platform/skills/pr-conventions/SKILL.md | 5 ++++- 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d444f95..73f4d55 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ Notable changes to the Datum Cloud Claude Code plugins. +## [1.8.2] - 2026-07-29 + +### Changed + +- **GitHub conventions skill** (`pr-conventions`, datum-platform) — Sharpened "be concise" into two enforceable rules: say it once (no restating the summary as test-plan checkboxes, no describing the same behaviour in prose and again in a checklist) and cut every word carrying no fact, with a compress-don't-omit clause so brevity never costs facts. Added the two matching rows to the PR "What to Avoid" table. + ## [1.8.1] - 2026-07-09 ### Changed diff --git a/plugins/datum-platform/.claude-plugin/plugin.json b/plugins/datum-platform/.claude-plugin/plugin.json index 73cc59d..1851117 100644 --- a/plugins/datum-platform/.claude-plugin/plugin.json +++ b/plugins/datum-platform/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "datum-platform", "description": "Kubernetes platform engineering automation with aggregated API servers, controller patterns, GitOps deployment, and platform capabilities", - "version": "1.8.1", + "version": "1.8.2", "author": { "name": "Datum Cloud", "url": "https://github.com/datum-cloud" diff --git a/plugins/datum-platform/skills/pr-conventions/SKILL.md b/plugins/datum-platform/skills/pr-conventions/SKILL.md index 73293de..7cf90fb 100644 --- a/plugins/datum-platform/skills/pr-conventions/SKILL.md +++ b/plugins/datum-platform/skills/pr-conventions/SKILL.md @@ -10,7 +10,8 @@ This skill covers how to work with GitHub effectively — writing pull requests, ## Core Principles - Write for humans, not machines. Avoid jargon unless the audience is explicitly technical. -- Be concise. Respect the reader's time. +- **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. +- **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. - Focus on goals and outcomes, not implementation details. - Use comments to add depth — keep the primary description focused. - Close issues deliberately. Linking is not closing. @@ -112,6 +113,8 @@ Write like you're explaining the change to a teammate. Non-technical stakeholder | PRs without an issue link | Every change should trace to intent | | Technical jargon in summaries | Not all readers have the same context | | Bullet-point-only summaries | Lead with prose for orientation | +| Test-plan items that restate the summary | The test plan says what you verified, not what you wrote | +| Paragraphs re-selling a point already made | Say it once, densely | | Hard-wrapping prose at a fixed column | GitHub reflows Markdown — wrap only where syntax requires | | Tool attribution / watermarks | Clutters the PR | | Empty sections | Omit optional sections rather than leaving them blank |