diff --git a/.claude/skills/adr-writer/SKILL.md b/.claude/skills/adr-writer/SKILL.md new file mode 100644 index 0000000..fd810e3 --- /dev/null +++ b/.claude/skills/adr-writer/SKILL.md @@ -0,0 +1,172 @@ +--- +name: adr-writer +description: "Write an architecture decision record (ADR) from a case input, the chosen main design plan and the other candidate plans. Uses the point-form changelog headings, copies the Motivation byte for byte and the main plan's change tables row for row, writes the Summary from the main plan, and draws alternatives from the other plans. Use when asked to write, render or update an ADR or changelog entry from design plans." +version: 1.0.0 +--- + +# Write an ADR from design plans + +This skill turns a chosen design plan into an ADR. It records a decision that was +already made. It does not design, choose a plan, change code or run a council. + +## Inputs + +- **`.council/input.md`**: holds only `## Motivation`, `## User flows to optimize for` + (FLOW-n) and `## Must not break` (CANT-n). It has no Summary. You write the Summary. +- **The main plan**: the plan the caller or architect chose. Use the path you are given. + Never pick the main plan yourself by file name, perspective or order. +- **The other plans**: the remaining candidates, if any. They supply the alternatives. +- **The code**, read only to explain current behavior in Background. + +Read every input in full before drafting. Treat all inputs as read-only. + +## Output + +Write the ADR to the path the caller gives. With no path given, write `.council/adr.md`. +Return or write only the ADR. Do not add transformation notes or a review section unless +the user asks for one. + +## Tool use + +Read files with the read tool (or hashread, whichever is available). Explore with the +grep, find and ls tools. Write the ADR with the write and edit tools. Do not use the +shell to read, copy or inspect files, and do not probe it. + +## Required reading + +Before drafting, read these files in full. Resolve the paths from this skill's directory. +They are the offline source for the format and the writing style; do not fetch websites +instead. + +```text +references/template-point-form.md +references/simplified-technical-english.md +references/google-technical-writing.md +``` + +The column headers of the change tables come from the design-plan template at +`../design-plan/references/plan-template.md`, section 3. + +## Exact output structure + +Use the heading tree in `references/template-point-form.md` exactly: the `#` title, the +four metadata bullets, then these headings in this order. + +```markdown +## Summary +## Motivation +## Background +## Specs +### Interface Changes +### Behavioural Changes +### Examples +## Design Decisions & Alternatives Considered +## Migration Steps +``` + +Keep every heading, even when a section is short. Add no other headings. Separate tables +inside one subsection with bold label lines, not headings. + +## Writing each section + +### Summary + +Write two to five sentences from the main plan only. Cover all of these: + +1. What changes: the new or changed behavior, in plain terms. +2. Who it affects: which callers, roles, integrators or operators see a difference. +3. Whether they must act: name the action, or say plainly that no action is needed. + Base this on the plan's `breaking` and `activation` values and its compatibility notes. +4. What stays the same: the existing behavior the change keeps. + +Do not describe a rejected alternative as if it were chosen. + +### Motivation + +Copy the body of `## Motivation` from `.council/input.md` byte for byte: every character +from the line after the heading up to the next `## ` heading. Keep wording, punctuation, +line breaks, list markers and blank lines. Do not summarize, reflow, quote, annotate or +apply the style rules to it. Do not add text of your own to this section. + +### Background + +Explain the current behavior and the terms a reader needs to follow Specs. Use only facts +from the input, the plans and the code you read. Keep it short. + +### Specs + +Under `### Interface Changes`, put the main plan's **Interface** table and its **Errors +and events** table. Under `### Behavioural Changes`, put its **Storage**, **Behavior** and +**New surface** tables. + +- Copy each table row for row: header, separator and every body row in the same order, + with the same IDs and cell text. Do not reword, merge, split, drop, add or reorder rows + or columns. +- If a plan table is empty, keep its header and separator and copy the plan's reason. +- Put a bold label line above each table and prose before or after it. The prose says + what the rows mean together, which rows are breaking and which existing behavior is + kept. Prose never contradicts a row. + +Under `### Examples`, write one or more call sequences from the main plan's user flows and +tests. For each, give the actor and setup, the call, the state change, the events and the +observable result, including at least one failure or authorization case when the plan has +one. Use only signatures and values the plan or code states. + +### Design Decisions & Alternatives Considered + +First the decisions: for each main choice in the main plan's approach, say what was +chosen, why it meets the Motivation and the flows, and what it costs. Take the costs from +the plan's trade-offs section and cite change IDs. + +Then the alternatives: one entry per other plan, named by its perspective. Describe its +approach, what it would gain and what it would cost compared with the main plan. Use the +differences the plans actually show; do not invent a rejection reason. If two plans are +in effect the same, say so. If no other plans were supplied, say that no alternative +plans were considered. + +### Migration Steps + +Write numbered steps from the main plan's changes, interactions, activation and +`breaking` value. Each step names who acts (deployer, admin role, integrator, indexer and +so on), what they do and when. Say which existing behavior needs no action. If nobody +must act, state that and the reason from the plan. Do not invent deployment, rollback or +storage-migration guarantees. + +## Fidelity rules + +- Preserve every fact, number, condition, qualifier and scope limit from the sources. +- Keep uncertainty at the same strength. Carry the main plan's open questions into the + section they affect. +- Do not invent signatures, selectors, storage slots, gas numbers, roles, dates, authors + or compatibility claims. Mark a missing fact with `[TODO: ...]`. +- The byte-for-byte Motivation and the row-for-row tables override every style rule. + +## Style + +Apply `references/simplified-technical-english.md` and +`references/google-technical-writing.md` to the prose you write: name the actor, one +action per sentence, plain words, one term per concept, conditions before instructions, +numbered lists for ordered steps. Never claim official ASD-STE100 compliance. + +## Modes + +- **Live mode** (a user is present): if the main plan is not identified, or a required + input is missing, ask once before drafting. Do not guess the main plan. +- **Eval mode** (run by a script): never ask questions or wait. Use the inputs and paths + given. If a fact is missing, write a `[TODO: ...]` marker. Never edit the input or the + plans. + +## Checklist + +Re-read the sources, not only your draft, when you check. + +- [ ] Title, metadata and headings match the template exactly, in order, with no extras. +- [ ] Motivation is byte-identical to the input's Motivation body. +- [ ] Summary covers what changes, who is affected, whether they must act, and what + stays the same, all from the main plan. +- [ ] All five section 3 tables appear, each row for row, with prose around them. +- [ ] Examples come from the main plan's flows and tests. +- [ ] Decisions come from the main plan's approach and trade-offs; each other plan + appears as an alternative. +- [ ] Migration steps come from the changes, interactions and activation. +- [ ] No invented facts; input and plans unchanged; no questions in eval mode. diff --git a/.claude/skills/adr-writer/references/google-technical-writing.md b/.claude/skills/adr-writer/references/google-technical-writing.md new file mode 100644 index 0000000..4b847cd --- /dev/null +++ b/.claude/skills/adr-writer/references/google-technical-writing.md @@ -0,0 +1,49 @@ +# Google technical-writing checklist + +Use this checklist as a practical guide. It summarizes public Google technical-writing +and developer documentation guidance. It is not a replacement for project-specific style rules. + +## Audience and scope + +- Identify the reader's role and existing knowledge. +- State what the document covers. +- State what the document does not cover when readers could reasonably expect it. +- Explain what the reader should know or do after reading the document. + +## Organization + +- Put the key information in the opening summary. +- Use a logical order based on reader needs. +- Use descriptive, hierarchical headings. +- Use sentence case for titles and headings. +- Do not skip heading levels. +- Introduce a concept before asking the reader to use it. +- Use progressive disclosure for long documents. + +## Voice and language + +- Prefer active voice. +- Address the reader as `you` when giving instructions. +- Use the imperative for procedures. +- Use plain, globally understandable language. +- Avoid idioms, slang, and culturally specific references. +- Define unfamiliar terms and acronyms at first use. +- Prefer specific verbs over vague verbs such as `do`, `occur`, or `happen`. +- Replace subjective claims with data. + +## Formatting + +- Use numbered lists for ordered steps. +- Use bullets for unordered items. +- Use code formatting for commands, identifiers, and code elements. +- Use descriptive link text. +- Add alt text when including images or diagrams. +- Use unambiguous dates such as `2026-08-18`. + +Sources: + +- https://developers.google.com/style +- https://developers.google.com/style/highlights +- https://developers.google.com/style/headings +- https://developers.google.com/tech-writing/one/audience +- https://developers.google.com/tech-writing/one/documents diff --git a/.claude/skills/adr-writer/references/simplified-technical-english.md b/.claude/skills/adr-writer/references/simplified-technical-english.md new file mode 100644 index 0000000..d6b95a8 --- /dev/null +++ b/.claude/skills/adr-writer/references/simplified-technical-english.md @@ -0,0 +1,29 @@ +# Simplified Technical English principles + +This reference applies principles from the public skill: + +https://github.com/danyuchn/asd-ste100-skill + +It does not reproduce the official ASD-STE100 dictionary and does not claim official +ASD-STE100 compliance. + +## Apply these structural rules + +- Prefer active voice when the actor is known. +- Use one clear action per sentence. +- Keep procedures near 20 words per sentence and descriptions near 25 words when possible. +- Split long or compound sentences when precision is preserved. +- Do not use semicolons in procedural text. +- Keep subjects, verbs, articles, and conditions explicit. +- Put conditions before instructions. +- Replace ambiguous phrasal verbs with plain verbs. +- Use one term for one technical concept. +- Preserve every number, condition, qualifier, and scope boundary. + +## Apply lexical rules carefully + +Use plain, common words and consistent terminology. Treat dictionary-specific rules as +guidance only because the official approved-word dictionary is not part of this repository. + +Never convert `may` to a fact, remove a safety condition, or shorten text when the change +would lose technical precision. diff --git a/.claude/skills/adr-writer/references/template-point-form.md b/.claude/skills/adr-writer/references/template-point-form.md new file mode 100644 index 0000000..65be5f4 --- /dev/null +++ b/.claude/skills/adr-writer/references/template-point-form.md @@ -0,0 +1,66 @@ +# ADR template and source mapping + +The ADR uses the point-form changelog structure. Keep every heading below, with this exact +spelling, level and order. Do not add, rename, merge, split or reorder headings. + +## Heading tree + +```markdown +# [Title] + +- **Feature Name**: [value] +- **Start Date**: [value] +- **Authors**: [value] +- **Title**: [value] + +## Summary + +## Motivation + +## Background + +## Specs + +### Interface Changes + +### Behavioural Changes + +### Examples + +## Design Decisions & Alternatives Considered + +## Migration Steps +``` + +Do not add headings such as `Goals`, `Risks`, `Open Questions`, `Decision`, `Rollout` or +`Appendix`. Put that content in the closest section above. When one subsection holds more +than one table, introduce each table with a bold label line (for example `**Interface**`), +not with a new heading. + +## Metadata + +- **Title** and **Feature Name**: a short name for the change, taken from the main plan's + approach. Use the same wording in the `#` title. +- **Start Date** and **Authors**: copy them only when a source states them. Otherwise write + `[TODO: not stated in the sources]`. Never invent a person or a date. + +## Section sources + +| ADR section | Source | How | +| --- | --- | --- | +| `## Summary` | Main plan: approach, changes, compatibility, activation | Write it yourself: what changes, who it affects and whether they must act, what stays the same | +| `## Motivation` | `.council/input.md`, body of `## Motivation` | Copy byte for byte | +| `## Background` | Input, main plan interactions, code you read | Current behavior and terms a reader needs; nothing invented | +| `### Interface Changes` | Main plan section 3: Interface table, Errors and events table | Copy each table row for row, with prose before and after | +| `### Behavioural Changes` | Main plan section 3: Storage, Behavior and New surface tables | Copy each table row for row, with prose before and after | +| `### Examples` | Main plan user flows and test plan | Call sequences with actor, call, state change, events and result | +| `## Design Decisions & Alternatives Considered` | Main plan approach and trade-offs; the other plans | Decisions with reasons and costs, then one alternative per other plan | +| `## Migration Steps` | Main plan changes, interactions, activation, `breaking` | Numbered steps: who acts, what they do, when | + +## Table copying + +The five change tables keep the column headers of the plan template +(`../../design-plan/references/plan-template.md`, section 3). Copy the header row, the +separator row and every body row in order, cell for cell, including IDs and escaped `\|`. +Do not add, drop, merge, reorder or reword rows or columns. If a plan table has no rows, +keep its header and separator and copy the plan's `None:` reason under it.