Adopt Motivation/Solution/Docs PR description structure

.claude/skills/create-pr/SKILL.md

@@ -45,20 +45,19 @@ Use this structure:
 ```markdown
 ## Motivation
 
-<Why this change is needed. 1-2 sentences.>
+<High-level description of the issue or feature this PR addresses. 1-3 sentences a reader can follow without opening the diff.>
 
-## Changes
+## Solution
 
-- Bullet point per meaningful change
-- Group related changes together
+<High-level description of the solution — written so a reviewer can read it and thumbs-up or thumbs-down the approach. Bullet points for the meaningful changes; fold in how it was tested (new tests, manual verification) rather than a separate Tests section.>
 
-## Review
+## Docs
 
-<Self-merge candidate — one-line reason. Or: Human review advised — one-line reason.>
+<Context for technical writers to pick up: user-facing changes, new/changed commands, flags, env vars, or behavior worth documenting. Always include this section — when nothing is user-facing, say so explicitly and why (e.g. test-only change, internal refactor), so writers can triage from the PR alone.>
 
-## Tests
+## Review
 
-<How this was tested — new tests added, manual verification, etc.>
+<Self-merge candidate — one-line reason. Or: Human review advised — one-line reason.>
 
 ## 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

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 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.