Add write-docs skill for Claude Code documentation workflows

.claude/drafts/TEMPLATE.md

@@ -0,0 +1,44 @@
+# [Feature/Change Title]
+
+## Type
+
+<!-- Pick one: new-feature | update | fix | deprecation | explainer -->
+
+## Priority
+
+<!-- Pick one: P1 | P2 | P3 | P4 -->
+
+## Linear Tickets
+
+<!-- Optional. List any related ticket IDs -->
+
+- TRUNK-XXXXX
+
+## What Changed
+
+<!-- Brief description of the product change, if you know it.
+     If you only have context below, leave this blank
+     and the skills will figure it out. -->
+
+## GitHub PRs
+
+<!-- Optional. Link any relevant PRs that implemented the feature/change.
+     The skills will read PR descriptions and diffs for additional context. -->
+
+## Context Links
+
+<!-- Optional. Paste links to any relevant context — Slack threads, Slite docs,
+     Loom videos, Google Docs, Notion pages, external references, etc.
+     All links will be attached to the Linear ticket and included in the PR body. -->
+
+## Target Docs
+
+<!-- Optional. If you know which docs page(s) need updating, list them.
+     Otherwise the skills will determine this from the repo structure. -->
+
+## Context
+
+<!-- Paste Slack messages, engineer notes, screenshots descriptions,
+     or anything else that explains what changed and why.
+     Don't worry about formatting — raw paste is fine.
+     Keep appending new info to the bottom of this section. -->

.claude/skills/write-docs/OUTPUTS.md

@@ -0,0 +1,58 @@
+# Output Formats
+
+Reference for all outputs produced by the write-docs skill.
+
+## Contents
+
+- [PR body format](#pr-body-format)
+- [Slack post format](#slack-post-format)
+- [Report card format](#report-card-format)
+
+## PR Body Format
+
+PR title: `[TRUNK-XXXXX] Short descriptive title` (prefix with Linear ticket ID if one exists).
+
+PR body sections:
+- **Summary** — bullet list of changes
+- **Linear tickets** — clickable links to all related tickets
+- **Context links** — all Slack, Slite, Loom links from the notes
+- **Files changed** — list of files created/modified
+- **Open questions** — things that could not be confirmed from available context
+- **Test plan** — checklist for reviewer (e.g., "check GitBook preview", "verify code example works")
+
+## Slack Post Format
+
+Write to `.claude/tmp/<draft-name>/slack.md`. Must be directly copy-pasteable into Slack.
+
+**MUST use Slack mrkdwn syntax, NOT Markdown:**
+- Bold: `*text*` (single asterisks, not double)
+- Links: `<URL|display text>`
+- Bullets: use the `*` character on a new line (Slack list style)
+- No Markdown headers (`##`), links (`[text](url)`), or bold (`**text**`)
+
+Template:
+```
+*[Feature Name] — docs update ready for review*
+
+[1-2 sentence summary of what changed in the docs.]
+
+* PR: <GitHub PR URL|#NNN>
+* Linear: <Linear ticket URL|TRUNK-XXXXX>
+
+*Open questions for the team:*
+* [list any items needing eng confirmation]
+```
+
+## Report Card Format
+
+Append an HTML card to `.claude/tmp/report.html`. If the file does not exist, create it with basic HTML styling.
+
+Each card includes:
+- PR link
+- Linear link
+- Change type badge
+- Changes summary
+- Context links
+- Related tickets
+- Review focus areas
+- Open questions

.claude/skills/write-docs/OVERLAP-CHECK.md

@@ -0,0 +1,51 @@
+# Duplicate & Overlap Check
+
+Run these checks before starting any work. Stop and ask the user if any match is found.
+
+## Step 1: Check for existing PRs/branches from this draft
+
+1. Derive the expected branch topic from the draft filename (e.g., `flag-as-flaky.md` -> `flag-as-flaky`). Get the username prefix from `git config user.name` (kebab-cased).
+
+2. Search for open PRs matching the branch:
+   ```bash
+   gh pr list --repo trunk-io/docs --state open --head "<username>/<topic>" --json number,title,url,headRefName
+   ```
+   Also search by topic keyword:
+   ```bash
+   gh pr list --repo trunk-io/docs --state open --json number,title,url,headRefName | jq '.[] | select(.headRefName | contains("<topic>"))'
+   ```
+
+3. Check local branches:
+   ```bash
+   git branch --list "*<topic>*"
+   ```
+
+4. **If a match is found**: Show the user the existing PR/branch and ask:
+   - (a) Update the existing PR
+   - (b) Close it and start fresh
+   - (c) Skip this draft
+
+   Do NOT proceed until the user responds.
+
+## Step 2: Check for overlapping PRs from other authors
+
+1. Read the draft to identify target docs files/product area.
+
+2. List all open PRs:
+   ```bash
+   gh pr list --repo trunk-io/docs --state open --json number,title,headRefName,url --limit 50
+   ```
+
+3. For any PR that looks related (by title or branch name matching the same product area), check file overlap:
+   ```bash
+   gh pr view <number> --repo trunk-io/docs --json files --jq '[.files[].path]'
+   ```
+
+4. **If overlapping PRs are found**: Show the user the overlapping PR and affected files, then ask:
+   - (a) Proceed anyway (changes will likely conflict)
+   - (b) Wait for that PR to merge first
+   - (c) Skip this draft
+
+   Do NOT proceed until the user responds.
+
+5. **If no overlaps found**: Continue to Phase 1.