diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 5921c3d..d6c4592 100644 --- 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 index 5921c3d..d6c4592 100644 --- 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 index cd89d8a..cd8d37c 100644 --- 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 index b6ea333..d417032 100644 --- 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 | diff --git a/skills/guide/SKILL.md b/skills/guide/SKILL.md index e609400..b859d81 100644 --- 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 index 9919d11..4207475 100644 --- 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 `. ## Rules diff --git a/skills/to-doc/SKILL.md b/skills/to-doc/SKILL.md index 4e4809b..c2d4aeb 100644 --- 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: ' [] [--one-pager]' +argument-hint: ' [] [--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 index ac92246..906a0a3 100644 --- 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.