From 716543f9ee634247fcf1d9e5a5aaffe8c8eac053 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristian=20Pallar=C3=A9s?= Date: Wed, 5 Aug 2026 15:24:12 +0200 Subject: [PATCH 1/2] Adopt Issue/Solution/Docs PR description structure Co-Authored-By: Claude --- .claude/skills/create-pr/SKILL.md | 18 +++++++++--------- CLAUDE.md | 1 + 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/.claude/skills/create-pr/SKILL.md b/.claude/skills/create-pr/SKILL.md index c9d86c00..075daa73 100644 --- a/.claude/skills/create-pr/SKILL.md +++ b/.claude/skills/create-pr/SKILL.md @@ -43,22 +43,21 @@ If the branch name carries no ticket ID, ask whether a Linear issue exists (issu Use this structure: ```markdown -## Motivation +## Issue - + -## Changes +## Solution -- Bullet point per meaningful change -- Group related changes together + -## Review +## Docs - + -## Tests +## Review - + ## Todo @@ -72,6 +71,7 @@ Rules: - Use `Closes TICKET-ID` if the PR fully resolves the issue - Use `Towards TICKET-ID` if it's a partial contribution - Keep bullet points concise — what changed, not how every line was modified +- The Docs section must agree with the docs label: `docs: skip` pairs with an explicit "nothing to document" explanation; `docs: needed` pairs with concrete pointers to what writers should cover. - The Review line reflects lstk's review pilot (small PRs/bug fixes may self-merge; bigger or undiscussed work needs a human). Decide it using `/review-pr`'s "Review scope" checklist (run that skill, or apply the checklist inline if it wasn't run), and say so out loud in the session before creating the PR — don't just silently decide. - Omit Todo section if there are no follow-up items - Don't over-explain; the diff speaks for itself diff --git a/CLAUDE.md b/CLAUDE.md index dba1270a..a49d8f51 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -87,6 +87,7 @@ When `DOCKER_HOST` isn't set, `DockerRuntime` resolves the daemon endpoint in or - Never commit or push unless explicitly asked. - PRs are squash-merged; titles start with an action verb and stay under ~70 characters. - Every PR needs exactly one `semver:` label (`patch`/`minor`/`major`) and one `docs:` label (`skip`/`needed`) — enforced by `check-release-label.yml`. Use `/create-pr` to scaffold title, body, and labels. +- PR descriptions follow the Issue / Solution / Docs / Review structure (template in the `/create-pr` skill): a high-level description of the issue or feature, a solution summary a reviewer can thumbs-up or -down, and a Docs section technical writers triage from — always present, stating explicitly when there is nothing to document. - Issues and tickets live in Linear, not GitHub Issues. Typical flow: Linear issue → branch named from the issue (e.g. `devx-123-...`) → PR body ends with `Closes DEVX-123` (or `Towards DEVX-123` if partial). Ask which Linear team if unclear (e.g. PRO = product, DEVX = developer experience). - Small PRs and straightforward bug fixes may merge without a human approval when the author is confident; bigger features/PRs still need review and an approval, as usual. This shifts weight onto self-review rather than lowering the bar — before treating any PR-sized change as done, run `/review-pr` against it, confirm tests pass, and add integration tests per the Testing section below. Before creating a PR, say in the session whether a human review looks advisable and why, and add a short "Review" line in the PR description itself (new/changed user-facing behavior, undiscussed or speculative work → advise review; straightforward, small, already-discussed → self-merge candidate) so the assessment is visible to both the author and anyone reading the PR, not just implied. If unsure, advise review. From 4988d479d88296cfc25e6be097cdb233c58f7a0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristian=20Pallar=C3=A9s?= Date: Wed, 5 Aug 2026 17:27:29 +0200 Subject: [PATCH 2/2] Rename Issue section to Motivation in PR template Co-Authored-By: Claude --- .claude/skills/create-pr/SKILL.md | 2 +- CLAUDE.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/skills/create-pr/SKILL.md b/.claude/skills/create-pr/SKILL.md index 075daa73..0a2ab17b 100644 --- a/.claude/skills/create-pr/SKILL.md +++ b/.claude/skills/create-pr/SKILL.md @@ -43,7 +43,7 @@ If the branch name carries no ticket ID, ask whether a Linear issue exists (issu Use this structure: ```markdown -## Issue +## Motivation diff --git a/CLAUDE.md b/CLAUDE.md index a49d8f51..c26dbcdd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -87,7 +87,7 @@ When `DOCKER_HOST` isn't set, `DockerRuntime` resolves the daemon endpoint in or - Never commit or push unless explicitly asked. - PRs are squash-merged; titles start with an action verb and stay under ~70 characters. - Every PR needs exactly one `semver:` label (`patch`/`minor`/`major`) and one `docs:` label (`skip`/`needed`) — enforced by `check-release-label.yml`. Use `/create-pr` to scaffold title, body, and labels. -- PR descriptions follow the Issue / Solution / Docs / Review structure (template in the `/create-pr` skill): a high-level description of the issue or feature, a solution summary a reviewer can thumbs-up or -down, and a Docs section technical writers triage from — always present, stating explicitly when there is nothing to document. +- PR descriptions follow the Motivation / Solution / Docs / Review structure (template in the `/create-pr` skill): a high-level description of the issue or feature, a solution summary a reviewer can thumbs-up or -down, and a Docs section technical writers triage from — always present, stating explicitly when there is nothing to document. - Issues and tickets live in Linear, not GitHub Issues. Typical flow: Linear issue → branch named from the issue (e.g. `devx-123-...`) → PR body ends with `Closes DEVX-123` (or `Towards DEVX-123` if partial). Ask which Linear team if unclear (e.g. PRO = product, DEVX = developer experience). - Small PRs and straightforward bug fixes may merge without a human approval when the author is confident; bigger features/PRs still need review and an approval, as usual. This shifts weight onto self-review rather than lowering the bar — before treating any PR-sized change as done, run `/review-pr` against it, confirm tests pass, and add integration tests per the Testing section below. Before creating a PR, say in the session whether a human review looks advisable and why, and add a short "Review" line in the PR description itself (new/changed user-facing behavior, undiscussed or speculative work → advise review; straightforward, small, already-discussed → self-merge candidate) so the assessment is visible to both the author and anyone reading the PR, not just implied. If unsure, advise review.