helderberto · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "hb",
   "description": "Helder Berto's 🛠️ Battle-tested software engineering skills for AI coding agents 🤖, from idea to PR.",
-  "version": "4.10.0",
+  "version": "4.11.0",
   "author": {
     "name": "Helder Burato Berto",
     "email": "helder@helderberto.com"

diff --git a/.plugin/plugin.json b/.plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "hb",
   "description": "Helder Berto's 🛠️ Battle-tested software engineering skills for AI coding agents 🤖, from idea to PR.",
-  "version": "4.10.0",
+  "version": "4.11.0",
   "author": {
     "name": "Helder Burato Berto",
     "email": "helder@helderberto.com"

diff --git a/AGENTS.md b/AGENTS.md
@@ -89,7 +89,7 @@ OpenCode uses a **skill-driven execution model** — the agent reads this file p
 | Is a risky change or PR worth it?       | suggest `/hb:debate`                           |
 | Fix prose / typos in markdown           | `revise`                                       |
 | Restructure an article draft            | `revise`                                       |
-| Write a doc or one-pager (Confluence, GitHub issue, Markdown) | suggest `/hb:to-doc`     |
+| Write a doc, one-pager or ADR (Confluence, GitHub issue, Markdown) | suggest `/hb:to-doc`     |
 | Hand off mid-session work to a fresh agent | suggest `/hb:handoff`                       |
 | Retrospective on a session (improve the agent's environment) | suggest `/hb:retro`       |
 | Last message didn't land — re-explain plainly | suggest `/hb:wait-what`                  |

diff --git a/README.md b/README.md
@@ -181,7 +181,7 @@ Focused capabilities the agent applies based on the task; both-tier ones are als
 | [`zoom-out`](skills/zoom-out/SKILL.md)         | Explain code with visual diagrams and analogies                                                                                     |
 | [`create-skill`](skills/create-skill/SKILL.md) | Author a new skill with proper structure                                                                                            |
 | [`revise`](skills/revise/SKILL.md)             | Restructure article drafts, or polish any markdown (typos, dashes, filler)                                                          |
-| [`to-doc`](skills/to-doc/SKILL.md)             | Typed: turn an investigation, data, or a decision into a doc on Confluence (with a Page Properties header), a GitHub issue, or Markdown: TL;DR panel, tables, Mermaid diagrams, verified sources; `--one-pager` keeps it to a five-minute read |
+| [`to-doc`](skills/to-doc/SKILL.md)             | Typed: turn an investigation, data, or a decision into a doc on Confluence (with a Page Properties header), a GitHub issue, or Markdown: TL;DR panel, tables, Mermaid diagrams, verified sources; `--one-pager` keeps it to a five-minute read, `--adr` records a decision |
 
 </details>
 

diff --git a/skills/guide/SKILL.md b/skills/guide/SKILL.md
@@ -61,7 +61,7 @@ Model skills that other skills pull in. Reach for them directly in plain words w
 - **`/hb:safe-repo`** — check a repo for secrets and sensitive data.
 - **`/hb:to-adr`** — record one architectural decision.
 - **`/hb:revise`** — restructure a draft or polish prose.
-- **`/hb:to-doc`** — turn an investigation, data, or a decision into a doc on Confluence, a GitHub issue, or Markdown; `--one-pager` for a five-minute read.
+- **`/hb:to-doc`** — turn an investigation, data, or a decision into a doc on Confluence, a GitHub issue, or Markdown; `--one-pager` for a five-minute read, `--adr` for a decision record.
 - **`/hb:create-skill`** — author a new skill.
 - **`/hb:handoff`** — a portable doc for a new harness, directory, or colleague.
 - **`/hb:wait-what`** — the last message didn't land; re-pitch it plainly in glossary terms.

diff --git a/skills/to-adr/SKILL.md b/skills/to-adr/SKILL.md
@@ -62,7 +62,7 @@ Most ADRs won't need any of these.
 
 ### 5. Show the user
 
-Print the file path and the rendered content. Don't auto-commit — let the user stage it (matches their git rules).
+Print the file path and the rendered content. Don't auto-commit — let the user stage it (matches their git rules). The team needs a full ADR on Confluence → suggest `/hb:to-doc --adr <url>`.
 
 ## Rules
 

diff --git a/skills/to-doc/SKILL.md b/skills/to-doc/SKILL.md
@@ -1,13 +1,13 @@
 ---
 name: to-doc
-description: Turn what's in context (an investigation, measured data, a decision) into a doc for readers across the company, published to Confluence, a GitHub issue or a Markdown file; `--one-pager` keeps it to a five-minute read.
+description: Turn what's in context (an investigation, measured data, a decision) into a doc for readers across the company, published to Confluence, a GitHub issue or a Markdown file; `--one-pager` keeps it to a five-minute read, `--adr` records one architectural decision.
 disable-model-invocation: true
-argument-hint: '<topic> [<confluence-url | issue-url | github | path.md>] [--one-pager]'
+argument-hint: '<topic> [<confluence-url | issue-url | github | path.md>] [--one-pager | --adr]'
 ---
 
 # To Doc
 
-Topic, destination and format: $ARGUMENTS. Empty → ask what the doc is about. `--one-pager` → the one-pager format in [template.md](references/template.md), else the full doc.
+Topic, destination and format: $ARGUMENTS. Empty → ask what the doc is about. `--one-pager` or `--adr` → that format in [template.md](references/template.md), else the full doc.
 
 | Destination | Argument |
 |---|---|
@@ -27,6 +27,8 @@ Done when you know whether you create, fill or replace, and any replacement is c
 
 One question round at most, only for what the context doesn't answer: the one takeaway, the audience, the destination. Confluence adds the header's reviewers, approvers, related pages and tickets.
 
+`--adr` → check [to-adr](../to-adr/SKILL.md)'s gate first: hard to reverse, surprising without context, a real trade-off. A failed criterion → name it and stop.
+
 Done when the takeaway is one sentence you could put after `TL;DR.`
 
 ## 3. Gather sources

diff --git a/skills/to-doc/references/template.md b/skills/to-doc/references/template.md
@@ -1,14 +1,15 @@
 # Doc template
 
-One skeleton, two formats. Sections the context has nothing for are dropped, never left empty.
+Two skeletons, three formats. Sections the context has nothing for are dropped, never left empty.
 
-| | Doc (default) | `--one-pager` |
-|---|---|---|
-| TL;DR panel | yes | yes |
-| Table of contents | when the page has more than 4 `h2` sections | never |
-| Length | what the topic needs | a five-minute read, about 1,000 words |
-| Diagrams | one per idea | 3 at most |
-| What we learned, Sources | full | the strongest 3–5 items each |
+| | Doc (default) | `--one-pager` | `--adr` |
+|---|---|---|---|
+| Skeleton | doc | doc | [ADR](#adr) |
+| TL;DR panel | yes | yes | yes: the decision |
+| Table of contents | when the page has more than 4 `h2` sections | never | never |
+| Length | what the topic needs | a five-minute read, about 1,000 words | what the decision needs |
+| Diagrams | one per idea | 3 at most | one per flow that changes |
+| What we learned, Sources | full | the strongest 3–5 items each | References only |
 
 Confluence pages open with a metadata header: status, authors, date, reviewers. A GitHub issue keeps that in its assignees and labels, a Markdown file in its git history.
 
@@ -124,3 +125,64 @@ The header is a Page Properties macro, so a Page Properties Report can list ever
 ```
 
 Drop the `toc` extension for `--one-pager` and for pages with 4 `h2` sections or fewer.
+
+## ADR
+
+One decision per page, same rules as above. The title is `ADR-NNNN: {the decision}`, not the question: "ADR-0003: Use Postgres for the write model". `NNNN` is the next number among the ADRs beside it: the parent page's children, or `docs/adr/`. Present tense, no hedging. Context, Decision and Consequences are required; Technical details, Alternative options and References are optional.
+
+The Confluence header keeps only the Authors, Date, Status and Approvers rows. Its statuses line is `DRAFT` (yellow), `PROPOSED` (blue), `APPROVED` (green), `REJECTED` (red) and `SUPERSEDED` (purple). The Approvers row reads "For each approval needed, create an action item assigned to the approver." The TL;DR panel holds the decision, and **Ask:** names the approvers.
+
+````markdown
+# ADR-{NNNN}: {The decision}
+
+> **TL;DR.** {What we decided and the main reason, one sentence.}
+>
+> **Ask:** {Who must approve it, and by when. Drop once approved.}
+
+## Context
+
+{The issue that motivates this decision. Point first, then how it works today.}
+
+## Decision
+
+{The change we propose or make, in present tense. The one reason that tipped it.}
+
+## Consequences
+
+{What becomes easier or harder because of this change.}
+
+**Positive**
+
+- {What gets easier.}
+
+**Negative**
+
+- {What gets harder, what we accept.}
+
+## Technical details
+
+### {Proposed change, one heading per area}
+
+{The new behavior. A diagram when a flow changes.}
+
+### Implementation plan
+
+1. {Step, in delivery order.}
+
+### Rollout
+
+{The flag, the environments in order, the stop condition, who to page.}
+
+## Alternative options considered
+
+| Option | Pros | Cons | Outcome |
+|---|---|---|---|
+| **A.** {option} | {pro} | {con} | Chosen |
+| **B.** {option} | {pro} | {con: why it lost} | Rejected |
+
+## References
+
+- <{official URL or supporting doc}>
+````
+
+In Confluence HTML, each section follows the doc skeleton's patterns, and Related and Tickets stay in the header.