From 3dbe0fd12f9ee41d83c657fa71a19f114e1c7919 Mon Sep 17 00:00:00 2001 From: Arthur Date: Mon, 28 Sep 2026 10:26:51 +0200 Subject: [PATCH] docs: ask commit subjects to name the concrete change A subject that paraphrases the effect ("say how to finish the agent's first start") leaves the reader guessing what changed. dev.md and the pr skill now ask for the change itself ("add an install hint to restart core on the first start"), with that pair as the example. The pr skill also asks a description to start with the situation the PR answers, then what it changes. --- .claude/skills/pr/SKILL.md | 8 ++++++++ docs/agent/dev.md | 10 +++++++++- 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/.claude/skills/pr/SKILL.md b/.claude/skills/pr/SKILL.md index 0f5f1add..ba1d1dcc 100644 --- a/.claude/skills/pr/SKILL.md +++ b/.claude/skills/pr/SKILL.md @@ -42,6 +42,8 @@ Never write a title containing "and". - Format: `type(scope)!: subject`. Types and scopes come from the dev.md tables. - The scope names what a reader recognises, a stacklet or a bot, never a file. - Imperative, lowercase after the colon, no full stop, no identifiers. +- Name the concrete change, not its effect: `add an install hint to restart + core on the first start`, not `say how to finish the agent's first start`. - Limit 72 characters as commit-lint counts them; dev.md asks for under 70. The ` (#N)` appended at merge does not count. - Use `!` only when the user must act. The description then carries `Upgrade:` @@ -59,6 +61,12 @@ Refs: #127 ``` - One to three bullets. Footers only when they apply. +- Start with the situation the PR answers, then what it changes: "The agent + is beta. After its first `./stack up agent`, it can sign in only after a + core restart." then "The hints shown after `./stack up agent` tell the + admin to run `./stack restart core`, then `./stack restart agent`." +- Plain technical English: state what the change does. No paraphrase such + as "now say so" or "provide the required information". - No "Test plan" section. Test output and measurements go in a PR comment. - No em dashes. Use a comma, colon, period or parentheses. - No `Co-Authored-By`, no "Generated with" line, no tool link: this repository is diff --git a/docs/agent/dev.md b/docs/agent/dev.md index 174ee8f9..172cad3c 100644 --- a/docs/agent/dev.md +++ b/docs/agent/dev.md @@ -366,12 +366,20 @@ Paperless behaviour; a README fix is `docs(readme):`. A scope outside the table still commits and lands under General, so drift surfaces at release time rather than on the website. -**Subject rules.** Describe the**Subject.** Imperative mood: it completes "If applied, this commit will +**Subject.** Imperative mood: it completes "If applied, this commit will ...". Lowercase after the colon, no full stop, at most 72 characters including the prefix. Describe the change as an admin sees it: no class, file or function names unless an admin types them. A subject that needs "and" is two commits. +Name the concrete change, what is added, fixed or removed, not a +paraphrase of its effect: + +``` +fix(agent): say how to finish the agent's first start # the effect: says nothing +fix(agent): add an install hint to restart core on the first start # the change +``` + **Body.** Blank line after the subject, wrapped at 72. Why the change is needed and what it changes; the diff shows how. It must make sense without the PR. Bullets for sets of changes. No debugging history, test narrative