diff --git a/.claude/skills/technical-document/SKILL.md b/.claude/skills/technical-document/SKILL.md deleted file mode 100644 index b60a258a..00000000 --- a/.claude/skills/technical-document/SKILL.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -name: technical-document -description: "Convert changelog/TEMPLATE_POINT_FORM.md from point form into a written technical specification. Use the exact template structure. Apply ASD-STE100-inspired Simplified Technical English and Google technical-writing guidance while preserving technical facts, uncertainty, and scope." -version: 2.0.0 ---- - -# Convert the point-form template into a written specification - -Use this skill for one task only: convert the repository template -`changelog/TEMPLATE_POINT_FORM.md` into a complete written specification. - -Do not use this skill to create a generic RFC, design document, technical overview, -or implementation plan. The template is the source of truth for the output structure. - -## Source template - -Read and follow: - -```text -changelog/TEMPLATE_POINT_FORM.md -``` - -Also follow the repository guidance in: - -```text -changelog/AGENTS.md -changelog/README.md -``` - -## Required reading before drafting - -Before writing any output, read every file below in full. These are the bundled, -offline copies of this skill's writing rules — use them as the authoritative source -instead of fetching the external sites they summarize: - -```text -references/template-point-form.md -references/simplified-technical-english.md -references/google-technical-writing.md -``` - -Do not skip this reading pass, and do not substitute a `WebFetch` of the external URLs -named in Steps 5 and 6 for reading these files — the referenced sites may be unreachable, -paywalled, or have drifted from what this skill applies, and the bundled files are the -version this skill is designed against. - -## Exact output structure - -The output must use this structure and heading text in this order: - -```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 -``` - -Template conformance is mandatory: - -- Use the exact heading text and heading order. -- Keep all required headings, even when a section contains a TODO. -- Do not add headings such as `Goals`, `Risks`, `Open Questions`, `Decision`, - `Rollout`, or `Appendix`. -- Put content that would normally use those headings into the closest defined section. -- Add headings under `## Specs` only when the source template or user explicitly requires them. -- Do not add generic preambles, summaries, transformation notes, or closing reports. -- Return only the completed specification unless the user explicitly asks for an audit or explanation. - -## Conversion workflow - -### 1. Read the complete input - -Read the entire point-form document before drafting. Extract: - -- Feature name, start date, authors, and title. -- Summary and audience. -- Problem, motivation, and current limitations. -- Background concepts, prior art, standards, and existing patterns. -- Interface changes, including functions, events, errors, signatures, and selectors. -- Behavioral changes, including execution flow, storage, compatibility, and gas effects. -- Examples, expected values, emitted events, and call sequences. -- Design decisions and rejected alternatives. -- Migration steps, deprecations, compatibility, and breaking changes. - -Treat comments in the template as instructions. Do not copy those comments into the output. - -### 2. Map content to the fixed sections - -Use this mapping: - -- Metadata → document metadata. -- Summary bullets → `## Summary`. -- Problem and rationale → `## Motivation`. -- Prerequisites, prior art, standards, and terminology → `## Background`. -- Interface facts → `### Interface Changes`. -- Runtime, storage, gas, and compatibility facts → `### Behavioural Changes`. -- Before/after snippets and call sequences → `### Examples`. -- Chosen approach and rejected options → `## Design Decisions & Alternatives Considered`. -- Integrator adoption and rollout actions → `## Migration Steps`. - -Do not move content to a new heading to make the document easier to organize. - -### 3. Preserve technical fidelity - -- Preserve every fact, number, condition, qualifier, and scope boundary. -- Preserve uncertainty. Keep `may`, `could`, `estimated`, and `unknown` unchanged in strength. -- Do not invent selectors, topic values, signatures, storage slots, gas costs, owners, dates, or compatibility claims. -- Mark missing information with `[TODO: ...]` in the relevant section. -- Mark an inference with `[Inferred — verify: ...]`. -- If a technical value is not verified, write `[TODO: verify against source]`. -- Keep code and signatures exactly as provided unless the user asks for a correction. - -Before citing a function signature, event signature, error selector, topic0, function -selector, or ERC-165 interface ID, verify it against the source or mark it for verification. - -### 3a. Offer to help fill `### Interface Changes` and `### Examples` gaps - -`### Interface Changes` and `### Examples` are the two sections most likely to need facts -the point-form input does not supply in full: exact signatures, selectors, topic0 values, -or a working call sequence. When either section would otherwise ship with a `[TODO: ...]` -or `[TODO: verify against source]` marker, stop before finalizing that section and ask the -user whether they want help closing the gap — for example, whether you should search the -repository (`src/interfaces/**` and related source) to find or verify the missing -signature, selector, or example, or whether they would rather supply the value themselves -or leave the TODO in place. - -- Ask once per document, covering all outstanding interface/example gaps together, rather - than once per gap. -- If the user says yes, read the relevant source before writing the section, and verify - each value you cite rather than guessing. -- If the user declines, or doesn't respond, keep the `[TODO: ...]` markers rather than - inventing a plausible-looking signature, selector, or example. -- Do not ask about gaps elsewhere in the document (Summary, Motivation, Background, Design - Decisions, Migration Steps) — only Interface Changes and Examples warrant this offer. - -### 4. Write the specification - -Convert point-form fragments into complete technical prose. Keep the meaning and -technical detail, but improve structure, readability, and consistency. - -Use tables for mappings when the input contains multiple comparable entries. Use -numbered lists for migration steps. Use code blocks for verified code or call sequences. - -### 5. Apply Simplified Technical English principles - -Apply the rules in `references/simplified-technical-english.md` (read in the required -reading pass above). That file is the source of truth for this step — do not fetch the -public `asd-ste100-skill` repository it summarizes. - -Apply these rules: - -- Prefer active voice and name the actor 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 splitting preserves precision. -- Do not use semicolons in procedural text. -- Keep subjects, verbs, articles, and conditions explicit. -- Put conditions before instructions. -- Replace ambiguous phrasal verbs such as `spin up` and `kick off` with plain verbs. -- Use one term for one technical concept. Do not rotate synonyms. -- Prefer direct, common words over formal or vague alternatives. -- Preserve technical terms when simplifying them would reduce accuracy. - -Apply structural rules confidently. Treat dictionary-specific lexical rules as guidance -only. Never claim that the output is officially ASD-STE100 compliant, and never reproduce -the official ASD-STE100 dictionary. - -### 6. Apply Google technical-writing guidance - -Apply the checklist in `references/google-technical-writing.md` (read in the required -reading pass above). That file is the source of truth for this step — do not fetch -developers.google.com. - -Apply these rules: - -- Write for the technical reader’s role and existing knowledge. -- State the purpose and scope in `Summary` and `Motivation`. -- Use clear, descriptive sentence-case headings from the template. -- Put important information before supporting detail. -- Use plain, globally understandable English. -- Define acronyms and unfamiliar domain terms at first use. -- Use numbered lists for ordered steps and bullets for unordered information. -- Avoid idioms, slang, cultural references, buzzwords, and marketing language. -- Replace vague claims with measurements when the input provides measurements. -- Use descriptive link text and unambiguous dates. - -### 7. Review before returning - -Check all of the following: - -- The output matches the exact template heading structure. -- No template heading is missing, renamed, duplicated, or reordered. -- No unsupported technical fact was added. -- No source fact, qualifier, or condition was removed. -- The output contains no invented selector, signature, storage detail, or compatibility claim. -- Interface changes are separated from behavioral changes. -- Examples contain only supplied or verified values. -- Migration steps identify compatibility and breaking changes when the input provides them. -- Missing information uses TODO markers. -- Any Interface Changes/Examples gap was offered to the user per Step 3a before shipping a TODO. -- Active voice, terminology consistency, sentence clarity, and plain language were applied. - -## Output rules - -Return only the written specification by default. Do not explain the conversion and do -not add headings outside the template. - -If the user asks for an audit, return the conforming specification first. Add the audit -after a plain-text separator such as `--- Review ---`, and do not treat the audit as part -of the specification. - -## Boundaries - -This skill will not: - -- Generate other document types. -- Invent technical facts or evidence. -- Claim official ASD-STE100 compliance. -- Reproduce the ASD-STE100 approved-word dictionary. -- Verify repository behavior without reading the relevant source. -- Manufacture selectors, signatures, storage layouts, or migration guarantees. - -## References - -- `references/google-technical-writing.md` -- `references/template-point-form.md` -- `references/simplified-technical-english.md` -- `examples/point-form-input.md` -- `examples/generated-spec.md` diff --git a/.claude/skills/technical-document/examples/generated-spec.md b/.claude/skills/technical-document/examples/generated-spec.md deleted file mode 100644 index 1cdb6c9c..00000000 --- a/.claude/skills/technical-document/examples/generated-spec.md +++ /dev/null @@ -1,57 +0,0 @@ -# Add a temporary worker pool for release builds - -- **Feature Name**: temporary_release_worker_pool -- **Start Date**: 2026-08-18 -- **Authors**: [TODO: provide author] -- **Title**: Add a temporary worker pool for release builds - -## Summary - -Release periods increase build wait time because normal builds and release builds -share one worker pool. This specification defines a temporary worker pool for -release builds. - -## Motivation - -The change reduces release-build wait time without adding permanent workers. The -current wait-time baseline is `[TODO: provide the baseline]`. - -## Background - -One shared worker pool handles normal builds and release builds. The release-period -threshold and available worker capacity are `[TODO: provide the missing values]`. - -## Specs - -### Interface Changes - -No interface changes are currently identified. - -### Behavioural Changes - -The system adds a temporary worker pool for release builds. The system limits the -pool size so release builds cannot use all available capacity. The temporary pool -could starve normal builds. - -### Examples - -Test the pool with one repository before expanding it. The expected wait-time target -is `[TODO: provide the target]`. - -## Design Decisions & Alternatives Considered - -The preferred approach adds a temporary release worker pool. This approach avoids -permanent worker capacity but adds queue configuration and a starvation risk. - -The alternative keeps one pool and increases its size. This approach preserves the -current queue model but adds permanent worker capacity. - -## Migration Steps - -1. Measure the current release-build wait time. -2. Configure the temporary pool for one repository. -3. Monitor normal-build wait time during the pilot. -4. Expand the pool after validation. - -Disable the temporary pool to roll back the change. The rollback owner and trigger -are `[TODO: provide the missing values]`. diff --git a/.claude/skills/technical-document/examples/point-form-input.md b/.claude/skills/technical-document/examples/point-form-input.md deleted file mode 100644 index 22d79415..00000000 --- a/.claude/skills/technical-document/examples/point-form-input.md +++ /dev/null @@ -1,49 +0,0 @@ -# Point-form input for TEMPLATE_POINT_FORM - -- **Feature Name**: temporary_release_worker_pool -- **Start Date**: 2026-08-18 -- **Authors**: [TODO: provide author] -- **Title**: Add a temporary worker pool for release builds - -## Summary - -- Release periods increase build wait time. -- Normal builds and release builds share one worker pool. - -## Motivation - -- Reduce release-build wait time. -- Avoid adding permanent workers. - -## Background - -- One shared worker pool handles normal builds and release builds. -- The current wait-time baseline is not available. - -## Specs - -### Interface Changes - -- No interface changes are currently identified. - -### Behavioural Changes - -- Add a temporary worker pool for release builds. -- Limit the release-pool size. -- The temporary pool could starve normal builds. - -### Examples - -- Test the pool with one repository before expanding it. - -## Design Decisions & Alternatives Considered - -- Preferred approach: add a temporary release worker pool. -- Alternative: keep one pool and increase its size. -- Mitigation: set a maximum release-pool size. - -## Migration Steps - -- Test with one repository. -- Expand after validation. -- The target wait time is not defined. diff --git a/.claude/skills/technical-document/references/google-technical-writing.md b/.claude/skills/technical-document/references/google-technical-writing.md deleted file mode 100644 index 4b847cda..00000000 --- a/.claude/skills/technical-document/references/google-technical-writing.md +++ /dev/null @@ -1,49 +0,0 @@ -# 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/technical-document/references/simplified-technical-english.md b/.claude/skills/technical-document/references/simplified-technical-english.md deleted file mode 100644 index d6b95a8d..00000000 --- a/.claude/skills/technical-document/references/simplified-technical-english.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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/technical-document/references/template-point-form.md b/.claude/skills/technical-document/references/template-point-form.md deleted file mode 100644 index ac6dcb29..00000000 --- a/.claude/skills/technical-document/references/template-point-form.md +++ /dev/null @@ -1,40 +0,0 @@ -# Point-form template mapping - -The canonical source template is: - -```text -changelog/TEMPLATE_POINT_FORM.md -``` - -The skill converts the template into prose without changing its structure. - -## Section mapping - -| Source content | Written specification section | -| --- | --- | -| Feature name, start date, authors, title | Document metadata | -| Summary bullets | `## Summary` | -| Problem and rationale | `## Motivation` | -| Prior art, standards, prerequisites, terminology | `## Background` | -| Functions, events, errors, signatures, selectors | `### Interface Changes` | -| Execution, storage, gas, compatibility | `### Behavioural Changes` | -| Before/after snippets and call sequences | `### Examples` | -| Chosen approach and rejected options | `## Design Decisions & Alternatives Considered` | -| Integrator adoption and compatibility actions | `## Migration Steps` | - -## Required headings - -```text -## 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`, or -`Rollout`. Place that content in the closest required section.