Add writing standard and surface map; rework PR/issue skills and templates

.claude/skills/commit/SKILL.md

@@ -5,6 +5,8 @@ description: Stage relevant files and create a well-formed git commit for the do
 
 # Commit Skill
 
+Read [`.claude/skills/writing-style.md`](../writing-style.md) before writing the commit message.
+
 Creates a clean, well-formed commit following the docs-builder project conventions.
 
 ## Steps
@@ -24,7 +26,6 @@ Do not run `git config` yourself. Do not use `--no-verify`.
 
 ### 2. Understand what changed
 
-Run these in parallel:
 ```bash
 git status
 git diff
@@ -41,19 +42,19 @@ Stage specific files by name — never `git add -A` or `git add .` blindly. Excl
 
 ### 4. Write the commit message
 
-Rules:
-- **First line**: Imperative mood, ≤72 chars, no trailing period (e.g. `Add async timeout handling to assembler`)
-- **Body** (optional): One short paragraph explaining *why*, not what. Skip if the title is self-explanatory.
-- **Trailer**: Always append `Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>`
+- **First line**: Imperative mood, ≤72 chars, no trailing period. Front-load the outcome — a reader scanning `git log` sees this line only.
+- **Body** (optional): One short paragraph explaining *why*, not what. Skip if the title is self-explanatory. Follow the sentence mechanics in `writing-style.md`.
+- **Trailer**: Add a `Co-Authored-By:` line that identifies the model that helped write this commit. Use whatever attribution feels accurate — the model name you know yourself to be running as, or simply `Claude` if you are uncertain. The address is always `noreply@anthropic.com`. The point is honest attribution, not a precise version string.
 
 Always pass the message via HEREDOC to avoid shell escaping issues:
+
 ```bash
 git commit -m "$(cat <<'EOF'
 Title here
 
 Optional body explaining why.
 
-Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
+Co-Authored-By: Claude <noreply@anthropic.com>
 EOF
 )"
 ```
@@ -72,4 +73,8 @@ If a hook fails:
 
 ### 6. Verify success
 
-Run `git status` after the commit to confirm a clean working tree.
+```bash
+git status
+```
+
+Confirm a clean working tree.

.claude/skills/issue/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: issue
+description: File a well-formed bug report or feature request. Use when the user asks to open an issue, report a bug, or request a feature in the docs-builder repo.
+---
+
+# Issue Skill
+
+Read [`.claude/skills/writing-style.md`](../writing-style.md) and [`.claude/skills/surfaces.md`](../surfaces.md) before writing anything.
+
+Files a GitHub issue that matches the repo's templates, applies correct labels, and checks for duplicates first.
+
+## Steps
+
+### 1. Check for duplicates
+
+Search for near-duplicates before opening anything. Link any you find in the issue body rather than filing a second.
+
+```bash
+gh issue list --search "<key terms>" --limit 10
+```
+
+### 2. Determine the issue type
+
+- **Bug** — something that used to work stopped, or produces wrong output. Use `bug-report` structure.
+- **Feature / enhancement** — something that does not exist yet, or needs to be better. Use `enhancement` structure.
+
+### 3. Write the title
+
+- ≤70 characters, no trailing period
+- States the observable problem or the wanted capability — not the internal cause or the implementation
+
+### 4. Write the body
+
+**Bug report:**
+
+```
+<One sentence: what went wrong and, briefly, under what condition. Be specific.>
+
+### What happened
+
+<What you saw. Include the command you ran, the input, and the exact output or
+ error. Commands and error messages go in fenced blocks.>
+
+### How to reproduce
+
+<Minimal steps. A command and the file it ran against is enough if that covers it.
+ Skip this section if the "What happened" section already makes it reproducible.>
+
+### Version or commit
+
+<Output of `docs-builder --version`, or the commit SHA if building from source.
+ This is the single most useful piece of triage data.>
+```
+
+**Feature request:**
+
+```
+<One sentence: the outcome you want, not the implementation.>
+
+### What is getting in your way
+
+<The concrete limitation. What are you trying to do, and what stops you?
+ One to three sentences.>
+
+### What would you like instead
+
+<Your proposed change or outcome. If you have a specific implementation in mind,
+ describe it — but a clear outcome is enough.>
+
+### Anything else
+
+<Examples from other tools, links, screenshots, or context that did not fit above.
+ Skip this section if there is nothing to add.>
+```
+
+Formatting rules:
+- Same plain-language rules as PR bodies — active voice, short sentences, no mechanical noun clusters.
+- Commands and error messages in fenced blocks.
+- Backticks on all identifiers: flags, config keys, file paths, method names.
+- Skip any section that has nothing to say — a blank section adds noise, not structure.
+
+### 5. Choose labels
+
+File with **two or three labels**:
+
+1. **Type** (required, from the template): `bug` or `enhancement`
+2. **Area** (one, if it fits): derived from the surface map in `surfaces.md`. Pick from the repo's existing area labels — do not invent new ones:
+   `authoring` · `links` · `tables` · `attributes` · `versioning` · `build` · `automation` · `migration` · `SEO` · `user-experience` · `tech-debt` · `design`
+3. **`needs triage`** (always)
+
+These are issue labels, not release-drafter PR labels. Do not use `feature`, `chore`, `redesign`, `changelog:skip`, etc. here.
+
+### 6. Create the issue
+
+One call — title, labels, and body together:
+
+```bash
+gh issue create \
+  --title "<title>" \
+  --label "bug,<area-label>,needs triage" \
+  --body "$(cat <<'EOF'
+<lead sentence>
+
+### What happened
+
+...
+
+### Version or commit
+
+...
+EOF
+)"
+```
+
+Replace `bug` with `enhancement` for feature requests. Omit the area label if none fits — do not force one.
+
+### 7. Return the issue URL
+
+Always print the URL so the user can open it directly.

.claude/skills/pr/SKILL.md

@@ -5,13 +5,14 @@ description: Create a GitHub pull request for the current branch with a focused
 
 # PR Skill
 
-Creates a GitHub PR with a body focused on *why* and *what*, labeled for the release changelog.
+Read [`.claude/skills/writing-style.md`](../writing-style.md) and [`.claude/skills/surfaces.md`](../surfaces.md) before writing anything.
+
+Creates a GitHub PR body that a newcomer can orient from in under a minute: front-loaded outcome, grounded Why, behaviour-led What, verifiable by the reviewer.
 
 ## Steps
 
 ### 1. Understand the branch
 
-Run these to see what the PR contains:
 ```bash
 git status
 git log main..HEAD --oneline
@@ -22,74 +23,108 @@ git diff main...HEAD --stat
 
 If the working tree has changes that belong in this PR, read and follow [commit](../commit/SKILL.md) first. Do not commit inline. Do not skip hooks.
 
-### 3. Push the branch (if needed)
+### 3. Push (if needed)
 
 ```bash
 git push -u origin HEAD
 ```
 
 ### 4. Write the PR title
 
-- ≤70 characters
-- Imperative mood, no trailing period
-- Describes the change at a human level (not a file list)
+- ≤70 characters, imperative mood, no trailing period
+- States what changed at a human level — not a file list, not a symbol name
+- No `[bug]` / `[feature]` / `[chore]` prefixes — the label carries the type
 
 ### 5. Write the PR body
 
-Use this structure:
+Required structure:
 
 ```
-## Why
+<One or two sentences, no heading. What this changes and the effect.
+ A newcomer reads only this and knows whether the PR concerns them.>
 
-<One or two sentences: the problem, gap, or need this addresses. What would go wrong without this change?>
+**Affects:** <one to three surfaces from surfaces.md, most affected first>
+
+## Why
+<Two to four sentences. The concrete failure or gap. Active voice, present tense
+ for current behaviour. Do not open with the history of a prior PR.>
 
 ## What
 
-<What changed, at a meaningful level — not a file list. Think: what does a reviewer need to understand to evaluate this?>
+#### <Conceptual label — not a filename>
+<Prose paragraph. Group by what changed conceptually, not by which files moved.
+ Lead with behaviour. Name a symbol only when the reviewer needs it to find the code.
+ Two to four sentences. Three to five sections total.>
+
+## Verify
+<How a reviewer confirms this locally. Use real commands they would run:
+ `./build.sh`, `dotnet test`, `npm run test`, `dotnet run --project …`.
+ If there is no clear local verification step, omit this section entirely.
+ Do not list CI checks, YAML linting, or bash scripts an agent would run
+ to prove their own work — those are not reviewer steps.>
+```
 
-## How (optional)
+Conditional add-ons — each is one or two sentences with a bold lead-in, no heading:
 
-<Only include this section if a completely new architectural mechanism was introduced that future contributors need to understand at a big-picture level. Skip for normal feature additions, fixes, or refactors — those belong in code comments, not here.>
-```
+- **Breaking** — what a consumer must change and when it bites them. Pairs with the `breaking` label.
+- **Out of scope** — a gap this PR deliberately leaves, so a reviewer does not raise it as a finding.
+- **Risk** — shared or production state this touches. Required when the change reaches anything in `CLAUDE.md`'s "Boundaries: never touch / human-gated" list, or leaves state that a code revert will not undo.
+- **Stack** — position and links: `3 of 5, on top of #3855`. A bare `Stack: 3/5` with no links is not enough.
 
-**Do not** include bullet lists of changed files. Do not summarize what's already obvious from the diff.
+**Do not** include bullet lists of changed files. Do not summarize what the diff already states plainly.
 
 ### 6. Choose exactly ONE label
 
-Pick the single best-fit label. Apply it with `--label <label>`.
+`.github/workflows/required-labels.yml` enforces exactly one release-drafter label at `mode: exactly, count: 1` — two labels or zero fails CI. Pick the single best fit.
 
 | Label | Use when |
-|-------|----------|
-| `breaking` | Existing behavior or public API breaks |
-| `feature` | New capability that did not exist before |
-| `enhancement` | Improves or extends an existing feature |
-| `bug` | Fixes a defect in existing behavior |
-| `fix` | Alias for bug fix (use `bug` by preference) |
-| `documentation` | Docs-only change (markdown, /docs/ pages) |
+|---|---|
+| `breaking` | An existing config, invocation, or documented behaviour stops working |
+| `feature` | A capability that did not exist before |
+| `enhancement` | An existing capability got better |
+| `bug` | A defect in existing behaviour is fixed |
+| `documentation` | Docs-only change (`docs/` pages, not incidental doc updates in the same PR) |
 | `chore` | Cleanup, refactor, internal restructure — no user-visible change |
 | `dependencies` | Dependency version bumps |
-| `automation` | CI/CD, GitHub Actions, scripts, build tooling |
-| `ci` | Alias for automation (use `automation` by preference) |
-| `redesign` | Frontend visual/structural redesign work |
-| `changelog:skip` | Housekeeping with no changelog entry (e.g. typo fixes, config tweaks) |
+| `automation` | CI/CD, GitHub Actions, build tooling |
+| `redesign` | Frontend visual or structural redesign |
+| `changelog:skip` | Nothing worth a changelog line |
+
+Never use `fix` (use `bug`) or `ci` (use `automation`) — both are release-drafter aliases that split the same changelog category.
+
+**`feature` vs `enhancement`:** `feature` = didn't exist; `enhancement` = existed but got better.
 
-When in doubt between `feature` and `enhancement`: `feature` = didn't exist, `enhancement` = existed but got better.
+**`breaking` guidance:** use it when an older `docs-builder` invocation or an existing repo config stops working. The canonical trigger is `Configuration` in the `**Affects:**` line plus a rename or removal — [#3856](https://github.com/elastic/docs-builder/pull/3856) removed `output:` from `changelog.yml` profiles and shipped as `feature`; it should have been `breaking`. Internal C# type renames and private method signature changes are not breaking.
 
 ### 7. Create the PR
 
+One call — title, label, and body together. No follow-up `gh pr edit`:
+
 ```bash
 gh pr create --title "<title>" --label "<label>" --body "$(cat <<'EOF'
+<lead sentence(s)>
+
+**Affects:** <surfaces>
+
 ## Why
 
 ...
 
 ## What
 
-...
+- ...
+- ...
+- ...
+
+## Verify
+
+```bash
+<command>
+```
 EOF
 )"
 ```
 
 ### 8. Return the PR URL
 
-Always print the PR URL so the user can open it directly.
+Always print the URL so the user can open it directly.