diff --git a/README.md b/README.md index 424440b1..db829a5c 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ The JS and Python versions are kept in lock-step by `release-please` and guarded ## Extensions Catalog -This repository contains **2 marketplace(s)** with **64 extensions** (54 skills, 10 plugins). +This repository contains **2 marketplace(s)** with **65 extensions** (55 skills, 10 plugins). ### large-codebase @@ -108,7 +108,7 @@ OpenHands skills for interacting, improving, and refactoring large codebases Official skills and plugins for OpenHands — the open-source AI software engineer. -**60 extensions** (52 skills, 8 plugins) +**61 extensions** (53 skills, 8 plugins) | Name | Type | Description | Commands | |------|------|-------------|----------| @@ -155,6 +155,7 @@ Official skills and plugins for OpenHands — the open-source AI software engine | openhands-sdk | skill | Reference skill for the OpenHands Software Agent SDK - build AI agents with custom tools, LLM configuration, conversa... | `/sdk` | | pdflatex | skill | Install and use pdflatex to compile LaTeX documents into PDFs on Linux. Use when generating academic papers, research... | — | | plain-english-content | skill | Write and edit clear, accessible prose in a plain English content style: active voice, front-loaded content, sentence... | — | +| pr-design-doc | skill | For a non-trivial pull request, write a self-contained HTML design doc under the temporary .pr/ directory and link it... | `/pr-design-doc`, `/design-doc` | | pr-review | plugin | Automated PR code review — analyzes diffs and posts inline review comments via the GitHub API. | — | | prd | skill | Generate a Product Requirements Document (PRD) for a new feature through an interactive clarifying-question workflow.... | `/prd` | | qa-changes | plugin | Validate pull request changes by actually running the code — setting up the environment, exercising changed behavior,... | — | diff --git a/marketplaces/openhands-extensions.json b/marketplaces/openhands-extensions.json index dfed7887..c6cce3c6 100644 --- a/marketplaces/openhands-extensions.json +++ b/marketplaces/openhands-extensions.json @@ -5,7 +5,7 @@ "email": "contact@all-hands.dev" }, "metadata": { - "description": "Official skills and plugins for OpenHands \u2014 the open-source AI software engineer.", + "description": "Official skills and plugins for OpenHands — the open-source AI software engineer.", "maintainer": "OpenHands", "homepage": "https://github.com/OpenHands/extensions" }, @@ -13,7 +13,7 @@ { "name": "agent-creator", "source": "./skills/agent-creator", - "description": "Create file-based sub-agents as Markdown files \u2014 no Python code required. Guides the user through a structured interview and generates a ready-to-deploy .md agent file following the OpenHands SDK specification.", + "description": "Create file-based sub-agents as Markdown files — no Python code required. Guides the user through a structured interview and generates a ready-to-deploy .md agent file following the OpenHands SDK specification.", "category": "agent-authoring", "keywords": [ "agent", @@ -429,7 +429,7 @@ { "name": "openhands", "source": "./plugins/openhands", - "description": "Unified OpenHands plugin \u2014 bundles Cloud CLI, REST API (openhands-api), and Automations (openhands-automation) into a single plugin.", + "description": "Unified OpenHands plugin — bundles Cloud CLI, REST API (openhands-api), and Automations (openhands-automation) into a single plugin.", "category": "openhands", "keywords": [ "openhands", @@ -470,7 +470,7 @@ { "name": "pr-review", "source": "./plugins/pr-review", - "description": "Automated PR code review \u2014 analyzes diffs and posts inline review comments via the GitHub API.", + "description": "Automated PR code review — analyzes diffs and posts inline review comments via the GitHub API.", "category": "code-quality", "keywords": [ "pr-review", @@ -482,7 +482,7 @@ { "name": "qa-changes", "source": "./plugins/qa-changes", - "description": "Validate pull request changes by actually running the code \u2014 setting up the environment, exercising changed behavior, and posting a structured QA report.", + "description": "Validate pull request changes by actually running the code — setting up the environment, exercising changed behavior, and posting a structured QA report.", "category": "quality-assurance", "keywords": [ "qa", @@ -645,7 +645,7 @@ { "name": "iterate", "source": "./skills/iterate", - "description": "Iterate on a GitHub pull request \u2014 drive it through CI, code review, and QA until merge-ready. Monitors state, fixes failures, addresses review feedback, retries flaky checks, and pushes fixes in one continuous loop.", + "description": "Iterate on a GitHub pull request — drive it through CI, code review, and QA until merge-ready. Monitors state, fixes failures, addresses review feedback, retries flaky checks, and pushes fixes in one continuous loop.", "category": "code-quality", "keywords": [ "github", @@ -770,6 +770,21 @@ "jira", "atlassian" ] + }, + { + "name": "pr-design-doc", + "source": "./skills/pr-design-doc", + "description": "For a non-trivial pull request, write a self-contained HTML design doc under the temporary .pr/ directory and link it in the PR description via htmlpreview, so maintainers grasp the proposal at a glance - the code/API design and the before/after of the change, grounded to real code.", + "category": "code-quality", + "keywords": [ + "pull-request", + "design-doc", + "html", + "review", + "before-after", + "htmlpreview", + "pr" + ] } ] } diff --git a/skills/index.js b/skills/index.js index 5fe5d59c..a5d25fca 100644 --- a/skills/index.js +++ b/skills/index.js @@ -416,6 +416,17 @@ export const SKILLS_CATALOG = [ "category": "writing", "license": "MIT" }, + { + "name": "pr-design-doc", + "description": "For a non-trivial pull request, write a self-contained HTML design doc under the temporary `.pr/` directory and link it in the PR description via htmlpreview, so maintainers grasp the proposal at a glance — code/API design, and the before/after of the change, grounded to real code. Use when opening or updating a non-trivial PR, or when the user says \"add a design doc\", \"document this PR for reviewers\", \"show the before/after\", \"make the design reviewable\", or \"write the .pr/ page\".", + "triggers": [ + "/pr-design-doc", + "/design-doc" + ], + "content": "# pr-design-doc — a reviewable design doc for a non-trivial PR\n\nA diff shows *what changed line by line*. It does not show *the design*: the shape of the\nchange, the API before and after, and why this approach. Reviewers reconstruct that by\nhand, slowly. The scarce resource is the maintainer's attention and trust budget — not the\nagent's effort. Spend extra effort to hand them **one self-contained HTML page** that\nconveys the **big picture** and the **before → after core difference**, with every claim\n**clickable back to the real code**, then link it from the PR description.\n\nThis is the same craft as a \"show me this change\" explainer, aimed at one job: making a\nnon-trivial PR easy to review.\n\n## When to use it\n\n- Opening or updating a **non-trivial** PR: new/changed public API, a new module or\n subsystem, a behavior change in core logic, a migration, or anything a reviewer can't\n fully judge from the diff in a couple of minutes.\n- **Skip it** for trivial PRs — a typo, a one-line guard, a dependency bump, a docs tweak, a simple bug fix.\n A design doc adds more to review. Use judgment; if the diff *is* the explanation, don't add a\n page.\n\n## The `.pr/` workflow (why this is safe to commit)\n\nOpenHands repos use a temporary **`.pr/`** directory for PR-only artifacts. For\nsame-repository PRs it is removed automatically on approval (`.github/workflows/pr-artifacts.yml`\nin `OpenHands/OpenHands`); for **fork** PRs that cleanup does not run, so remove `.pr/`\nyourself before merging to keep it out of `main`. The doc is a review aid that lives with the\nbranch and renders while the PR is open.\n\n## Workflow\n\n1. **Get the change.** You usually already have the branch. Otherwise:\n ```bash\n gh pr view --json title,body,baseRefName,headRefName,files,additions,deletions\n gh pr diff # or: git diff ... / git diff\n gh repo view --json url # for clickable blob links; pin the head SHA\n ```\n Group changed files by area; note the merge base and head SHA for source links.\n\n2. **Read both sides of each logical file.** `git show :` vs head. Capture the\n **function-level** behavioral difference — what the code *did* vs *does now*.\n - new file → no \"before\"; one \"after\" diagram + a line on the role it adds.\n - deleted file → \"before\" diagram + who/what takes over.\n - edited file → a before/after pair, with the delta highlighted.\n\n3. **Classify each file.** *Logic* change (behavior moved) → draw before/after. *Mechanical*\n change (rename, constant, config, import move) → a one-line `before → after` row, no\n diagram. Don't dilute the signal by drawing mechanical edits.\n\n4. **If the change is an API change, lead with the API.** Show the signature/schema/type\n **before and after** side by side (function signature, endpoint + payload, config field,\n event shape). Name the compatibility impact plainly: additive, breaking, or behind a flag.\n\n5. **Find the cross-file story.** If one call chain threads several files, draw a single\n **overview** before/after at the top; per-file cards drill in.\n\n6. **Build the page** per [`references/html-craft.md`](references/html-craft.md) — one\n self-contained, offline, editorial HTML file with hand-drawn SVG figures. Save it to\n the repo's `.pr/` directory, e.g. `.pr/design.html` (or `.pr/.html`). If it\n helps, lean on the `frontend-design` skill to make the page look polished.\n\n7. **Commit under `.pr/`, push, and link it.**\n ```bash\n git add .pr/design.html\n git commit -m \"docs(.pr): design doc for \"\n git push \n ```\n Then add the htmlpreview link near the top of the PR description, pointing at the **fork\n and branch the PR is opened from** (it renders before merge):\n ```\n 📄 Design doc: https://htmlpreview.github.io/?https://github.com///blob//.pr/design.html\n ```\n\n## What the page contains\n\n1. **What changed (decision first)** — one paragraph: the intent, net effect, and why the\n reviewer should care. Put the highest-impact conclusion, risk, or API-compat note in a\n `★` callout, with the most important changed `path:line` nearby. Stats (`N files ·\n +A / −D`) are context, not the lead. If there's a cross-file flow, the **overview\n before/after SVG** goes here.\n2. **API before → after** (when the PR changes an interface) — signatures/schemas/types side\n by side, with the compatibility verdict stated.\n3. **Left rail / index** — changed files grouped by area, each tagged (🟢 added · 🔴 removed ·\n ✏️ changed · ⚙️ mechanical) with +/− counts; click to jump.\n4. **Per-file cards** — for each logical file: a claim-carrying title, a one-line summary of\n how its behavior changed, **before/after** diagrams with real symbol names + `file:line`\n (changed nodes in orange), and the diff in a collapsed `
`. Mechanical files get a\n small `before → after` table, no diagram.\n5. **(optional) Risk / follow-ups** — only if grounded in what you read.\n\n## Non-negotiable principles\n\n1. **Optimize for scarce reviewer attention.** The first screen answers, in ~15 seconds:\n what this PR does, whether it's risky, where to look first, and what evidence backs the\n claim. Lead with the conclusion, not your process.\n2. **Show the difference, not just the after.** For any logic or API change, draw **before**\n and **after** and make the *delta* visually loud (color + line style). The contrast is\n the product.\n3. **Ground everything to code, beside the claim.** Every box, node, and sentence names a\n real symbol + `path:line`, and links to the source (GitHub blob URL at the head SHA)\n where possible. One click from \"this changed\" to the exact code.\n4. **Hand-draw the carrying diagrams.** Prefer bespoke inline SVG for the before/after that\n makes the argument; Mermaid is fine only for quick auxiliary graphs.\n5. **Self-contained & offline.** One HTML file, inline CSS/SVG, opens by double-click,\n survives being copied to another machine (htmlpreview needs this).\n6. **`.pr/` only, and temporary.** The doc is a review aid, not project docs. Keep it in\n `.pr/` and ensure it is removed before merge (automatic on approval for same-repo PRs,\n manual for forks). Do not move design HTML into `docs/` or ship it in the merged tree.\n\n## Anti-patterns\n\n- ❌ Dumping the raw diff / file tree and calling it a \"design doc\" — adds nothing over the\n PR page.\n- ❌ Empty nodes (\"process data\", \"handle request\") — every node is a real symbol +\n location.\n- ❌ Only the after-state when something changed — reviewers want the *contrast*.\n- ❌ A design doc on a trivial PR — noise. Skip it.\n- ❌ Committing the HTML outside `.pr/` (e.g. `docs/`), where it would merge into `main`.\n- ❌ A private-repo htmlpreview link — htmlpreview can't fetch private raw content (auth +\n CORS). Use GitHub Pages or the local-serve fallback in the craft reference instead.", + "category": "code-quality", + "license": "MIT" + }, { "name": "prd", "description": "\"Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD.\"", diff --git a/skills/pr-design-doc/.claude-plugin b/skills/pr-design-doc/.claude-plugin new file mode 120000 index 00000000..665797f0 --- /dev/null +++ b/skills/pr-design-doc/.claude-plugin @@ -0,0 +1 @@ +.plugin \ No newline at end of file diff --git a/skills/pr-design-doc/.codex-plugin b/skills/pr-design-doc/.codex-plugin new file mode 120000 index 00000000..665797f0 --- /dev/null +++ b/skills/pr-design-doc/.codex-plugin @@ -0,0 +1 @@ +.plugin \ No newline at end of file diff --git a/skills/pr-design-doc/.plugin/plugin.json b/skills/pr-design-doc/.plugin/plugin.json new file mode 100644 index 00000000..6e7d54c7 --- /dev/null +++ b/skills/pr-design-doc/.plugin/plugin.json @@ -0,0 +1,20 @@ +{ + "name": "pr-design-doc", + "version": "1.0.0", + "description": "For a non-trivial pull request, write a self-contained HTML design doc under the temporary .pr/ directory and link it in the PR description via htmlpreview, so maintainers grasp the proposal at a glance - the code/API design and the before/after of the change, grounded to real code.", + "author": { + "name": "OpenHands", + "email": "contact@all-hands.dev" + }, + "homepage": "https://github.com/OpenHands/extensions", + "repository": "https://github.com/OpenHands/extensions", + "license": "MIT", + "keywords": [ + "pull-request", + "design-doc", + "html", + "review", + "before-after", + "htmlpreview" + ] +} diff --git a/skills/pr-design-doc/README.md b/skills/pr-design-doc/README.md new file mode 100644 index 00000000..241cd1b3 --- /dev/null +++ b/skills/pr-design-doc/README.md @@ -0,0 +1,25 @@ +# PR Design Doc + +For a non-trivial pull request, write a self-contained HTML design doc under the temporary +`.pr/` directory and link it in the PR description via htmlpreview, so maintainers grasp the +proposal at a glance — the code/API design and the before/after of the change, grounded to +real code. + +## Triggers + +This skill is activated by the following keywords: + +- `/pr-design-doc` +- `/design-doc` + +## Details + +See [SKILL.md](./SKILL.md) for when to use it, the `.pr/` workflow (the directory is removed +on approval for same-repository PRs, and manually before merge for fork PRs), the +step-by-step process, and the non-negotiable principles. + +The HTML craft — the editorial look, hand-drawn before/after SVG technique, code grounding, +and the htmlpreview delivery link — is in +[`references/html-craft.md`](references/html-craft.md). + +Adapted from the `show-me` visualization skill for the OpenHands PR-review workflow. diff --git a/skills/pr-design-doc/SKILL.md b/skills/pr-design-doc/SKILL.md new file mode 100644 index 00000000..a9cbb119 --- /dev/null +++ b/skills/pr-design-doc/SKILL.md @@ -0,0 +1,137 @@ +--- +name: pr-design-doc +description: > + For a non-trivial pull request, write a self-contained HTML design doc under the + temporary `.pr/` directory and link it in the PR description via htmlpreview, so + maintainers grasp the proposal at a glance — code/API design, and the before/after of + the change, grounded to real code. Use when opening or updating a non-trivial PR, or + when the user says "add a design doc", "document this PR for reviewers", "show the + before/after", "make the design reviewable", or "write the .pr/ page". +triggers: +- /pr-design-doc +- /design-doc +license: MIT +metadata: + tags: pull-request, design-doc, html, review, before-after, htmlpreview +--- + +# pr-design-doc — a reviewable design doc for a non-trivial PR + +A diff shows *what changed line by line*. It does not show *the design*: the shape of the +change, the API before and after, and why this approach. Reviewers reconstruct that by +hand, slowly. The scarce resource is the maintainer's attention and trust budget — not the +agent's effort. Spend extra effort to hand them **one self-contained HTML page** that +conveys the **big picture** and the **before → after core difference**, with every claim +**clickable back to the real code**, then link it from the PR description. + +This is the same craft as a "show me this change" explainer, aimed at one job: making a +non-trivial PR easy to review. + +## When to use it + +- Opening or updating a **non-trivial** PR: new/changed public API, a new module or + subsystem, a behavior change in core logic, a migration, or anything a reviewer can't + fully judge from the diff in a couple of minutes. +- **Skip it** for trivial PRs — a typo, a one-line guard, a dependency bump, a docs tweak, a simple bug fix. + A design doc adds more to review. Use judgment; if the diff *is* the explanation, don't add a + page. + +## The `.pr/` workflow (why this is safe to commit) + +OpenHands repos use a temporary **`.pr/`** directory for PR-only artifacts. For +same-repository PRs it is removed automatically on approval (`.github/workflows/pr-artifacts.yml` +in `OpenHands/OpenHands`); for **fork** PRs that cleanup does not run, so remove `.pr/` +yourself before merging to keep it out of `main`. The doc is a review aid that lives with the +branch and renders while the PR is open. + +## Workflow + +1. **Get the change.** You usually already have the branch. Otherwise: + ```bash + gh pr view --json title,body,baseRefName,headRefName,files,additions,deletions + gh pr diff # or: git diff ... / git diff + gh repo view --json url # for clickable blob links; pin the head SHA + ``` + Group changed files by area; note the merge base and head SHA for source links. + +2. **Read both sides of each logical file.** `git show :` vs head. Capture the + **function-level** behavioral difference — what the code *did* vs *does now*. + - new file → no "before"; one "after" diagram + a line on the role it adds. + - deleted file → "before" diagram + who/what takes over. + - edited file → a before/after pair, with the delta highlighted. + +3. **Classify each file.** *Logic* change (behavior moved) → draw before/after. *Mechanical* + change (rename, constant, config, import move) → a one-line `before → after` row, no + diagram. Don't dilute the signal by drawing mechanical edits. + +4. **If the change is an API change, lead with the API.** Show the signature/schema/type + **before and after** side by side (function signature, endpoint + payload, config field, + event shape). Name the compatibility impact plainly: additive, breaking, or behind a flag. + +5. **Find the cross-file story.** If one call chain threads several files, draw a single + **overview** before/after at the top; per-file cards drill in. + +6. **Build the page** per [`references/html-craft.md`](references/html-craft.md) — one + self-contained, offline, editorial HTML file with hand-drawn SVG figures. Save it to + the repo's `.pr/` directory, e.g. `.pr/design.html` (or `.pr/.html`). If it + helps, lean on the `frontend-design` skill to make the page look polished. + +7. **Commit under `.pr/`, push, and link it.** + ```bash + git add .pr/design.html + git commit -m "docs(.pr): design doc for " + git push + ``` + Then add the htmlpreview link near the top of the PR description, pointing at the **fork + and branch the PR is opened from** (it renders before merge): + ``` + 📄 Design doc: https://htmlpreview.github.io/?https://github.com///blob//.pr/design.html + ``` + +## What the page contains + +1. **What changed (decision first)** — one paragraph: the intent, net effect, and why the + reviewer should care. Put the highest-impact conclusion, risk, or API-compat note in a + `★` callout, with the most important changed `path:line` nearby. Stats (`N files · + +A / −D`) are context, not the lead. If there's a cross-file flow, the **overview + before/after SVG** goes here. +2. **API before → after** (when the PR changes an interface) — signatures/schemas/types side + by side, with the compatibility verdict stated. +3. **Left rail / index** — changed files grouped by area, each tagged (🟢 added · 🔴 removed · + ✏️ changed · ⚙️ mechanical) with +/− counts; click to jump. +4. **Per-file cards** — for each logical file: a claim-carrying title, a one-line summary of + how its behavior changed, **before/after** diagrams with real symbol names + `file:line` + (changed nodes in orange), and the diff in a collapsed `
`. Mechanical files get a + small `before → after` table, no diagram. +5. **(optional) Risk / follow-ups** — only if grounded in what you read. + +## Non-negotiable principles + +1. **Optimize for scarce reviewer attention.** The first screen answers, in ~15 seconds: + what this PR does, whether it's risky, where to look first, and what evidence backs the + claim. Lead with the conclusion, not your process. +2. **Show the difference, not just the after.** For any logic or API change, draw **before** + and **after** and make the *delta* visually loud (color + line style). The contrast is + the product. +3. **Ground everything to code, beside the claim.** Every box, node, and sentence names a + real symbol + `path:line`, and links to the source (GitHub blob URL at the head SHA) + where possible. One click from "this changed" to the exact code. +4. **Hand-draw the carrying diagrams.** Prefer bespoke inline SVG for the before/after that + makes the argument; Mermaid is fine only for quick auxiliary graphs. +5. **Self-contained & offline.** One HTML file, inline CSS/SVG, opens by double-click, + survives being copied to another machine (htmlpreview needs this). +6. **`.pr/` only, and temporary.** The doc is a review aid, not project docs. Keep it in + `.pr/` and ensure it is removed before merge (automatic on approval for same-repo PRs, + manual for forks). Do not move design HTML into `docs/` or ship it in the merged tree. + +## Anti-patterns + +- ❌ Dumping the raw diff / file tree and calling it a "design doc" — adds nothing over the + PR page. +- ❌ Empty nodes ("process data", "handle request") — every node is a real symbol + + location. +- ❌ Only the after-state when something changed — reviewers want the *contrast*. +- ❌ A design doc on a trivial PR — noise. Skip it. +- ❌ Committing the HTML outside `.pr/` (e.g. `docs/`), where it would merge into `main`. +- ❌ A private-repo htmlpreview link — htmlpreview can't fetch private raw content (auth + + CORS). Use GitHub Pages or the local-serve fallback in the craft reference instead. diff --git a/skills/pr-design-doc/commands/design-doc.md b/skills/pr-design-doc/commands/design-doc.md new file mode 100644 index 00000000..6beb847f --- /dev/null +++ b/skills/pr-design-doc/commands/design-doc.md @@ -0,0 +1,8 @@ +--- +# auto-generated by sync_extensions.py +description: For a non-trivial pull request, write a self-contained HTML design doc under the temporary `.pr/` directory and link it in the PR description via htmlpreview, so maintainers grasp the proposal at a glance — code/API design, and the before/after of the change, grounded to real code. Use when opening or updating a non-trivial PR, or when the user says "add a design doc", "document this PR for reviewers", "show the before/after", "make the design reviewable", or "write the .pr/ page". +--- + +Read and follow the complete instructions in the SKILL.md file located in this skill's directory. + +$ARGUMENTS diff --git a/skills/pr-design-doc/commands/pr-design-doc.md b/skills/pr-design-doc/commands/pr-design-doc.md new file mode 100644 index 00000000..6beb847f --- /dev/null +++ b/skills/pr-design-doc/commands/pr-design-doc.md @@ -0,0 +1,8 @@ +--- +# auto-generated by sync_extensions.py +description: For a non-trivial pull request, write a self-contained HTML design doc under the temporary `.pr/` directory and link it in the PR description via htmlpreview, so maintainers grasp the proposal at a glance — code/API design, and the before/after of the change, grounded to real code. Use when opening or updating a non-trivial PR, or when the user says "add a design doc", "document this PR for reviewers", "show the before/after", "make the design reviewable", or "write the .pr/ page". +--- + +Read and follow the complete instructions in the SKILL.md file located in this skill's directory. + +$ARGUMENTS diff --git a/skills/pr-design-doc/references/html-craft.md b/skills/pr-design-doc/references/html-craft.md new file mode 100644 index 00000000..87aec12b --- /dev/null +++ b/skills/pr-design-doc/references/html-craft.md @@ -0,0 +1,295 @@ +# html-craft — how to build the page + +Shared craft for every show-me dimension. One self-contained, offline, editorial HTML +page with hand-drawn SVG figures and code-grounded claims. + +## The look (editorial document, light theme) + +Calm, readable, document-like — not a dark dashboard. Skeleton: + +```html + + +{{Title}} + +
+ +
+
{{kind}}

{{Title}}

+

{{one-paragraph mental model — the big picture in 2-3 sentences}}

+

1…

…
+
+
+``` + +Numbered sticky TOC + one-paragraph mental model up top + sectioned body. No JS needed +for this shell. + +## First screen: 15-second orientation + +The reader's attention is the budget. The first viewport should answer four questions +without requiring a full read: + +1. **What is this?** A one-paragraph mental model in the title subtitle. +2. **Why does it matter?** The highest-impact conclusion, risk, or action in a `★` + callout near the top. +3. **Where should I jump?** A numbered sticky TOC whose labels carry information, not + just categories. +4. **Why should I trust it?** Nearby source links (`path:line`, test, command, commit, + or fixture) for the first substantive claim. + +Do not open with "I read these files" or a chronological work log. Start with the +reader's decision: what changed, how the system works, what path matters, or where to +look next. Put methods, command output, and raw diffs behind `
` unless they +are the point of the report. + +## Skimmable structure + +Design the page so a busy reader can scan headings, captions, callouts, and tables +before choosing where to dive: + +- **Headings make claims.** Prefer "Writes only cross the queue" over "Architecture", + when the section has a specific finding. Generic labels are acceptable only when the + title/subtitle already carries the finding. +- **One paragraph, one judgment.** Keep paragraphs short; split when a sentence starts + proving a different point. +- **Number parallel points.** If you say "three rules" or "two risks", number them so + the reader can reconcile the claim with the list. +- **Use tables only for stable comparison axes.** A table should reduce cognitive + work, not force subtle judgments into neat boxes. +- **Make captions do work.** A caption states the takeaway of the figure, not merely + its type. + +## Callouts (give them semantic types) + +The `.callout` / `.callout.warn` / `.callout.note` styles aren't interchangeable — assign +each a fixed job and the reader learns to skim by them: + +- **`★` key takeaway** (accent) — the one load-bearing sentence of a section. At most one per + section; it's what the reader should remember if they read nothing else. +- **`ⓘ` note** (`.note`, muted) — a reading hint for a figure, an aside, a "why we did it this + way" that isn't on the critical path. +- **`⚠` warning** (`.warn`) — a boundary, a risk, a gotcha, a guardrail: trust boundaries, + "this does NOT do X", "never commit the secret". Reserve it for things that bite. + +Don't let callouts become wallpaper — if every paragraph is a colored box, none of them carry +weight. A glyph prefix (`★ ⓘ ⚠`) makes the type legible before the reader parses the text. + +## Hand-drawn SVG figures (the diagrams that carry the argument) + +Draw bespoke inline `` with a `` for arrow markers and a +scoped `