From aeb901de8b19f94f38d823406c350f0060285675 Mon Sep 17 00:00:00 2001 From: Rayyan Alam Date: Thu, 22 Oct 2026 16:19:19 -0400 Subject: [PATCH] feat(skills): retire the legacy changelog skills The motivation check and the design council replace the interview-style changelog flow, and the ADR writer gets its own deterministic checks. --- .claude/skills/changelog-gap-check/skill.md | 124 -------------------- .claude/skills/changelog-grill/SKILL.md | 41 ------- 2 files changed, 165 deletions(-) delete mode 100644 .claude/skills/changelog-gap-check/skill.md delete mode 100644 .claude/skills/changelog-grill/SKILL.md diff --git a/.claude/skills/changelog-gap-check/skill.md b/.claude/skills/changelog-gap-check/skill.md deleted file mode 100644 index 13db8ac7..00000000 --- a/.claude/skills/changelog-gap-check/skill.md +++ /dev/null @@ -1,124 +0,0 @@ -# changelog-gap-check - -Check a changelog entry for progressive-discovery ordering and content quality. - -## When to use - -Invoke with `/changelog-gap-check ` where `` is the absolute or repo-relative path to a changelog markdown file (e.g. `changelog/02_Cobalt_B20_seize.md`). - -## What this skill does - -This is a **read-only audit**. It produces a report with reorder suggestions and consolidation recommendations — it does not modify the file. - -### 1. Progressive-discovery check - -For each section (delimited by `##` headings), scan the bullet points and sentences in order. A concept (identifier, acronym, named entity) must be **introduced before it is referenced**. If sentence/bullet N references concept X but concept X is first defined or introduced at sentence/bullet M where M > N, flag it as an ordering violation. - -**How to detect:** -- Extract named concepts: function names, role names, policy names, event names, error names, acronyms, and domain terms that are not common English. -- For each concept, record its first-mention position (section + bullet/sentence index). -- If a reference appears before its introduction within the same section, report it. - -**Output format for each violation:** -``` -REORDER: section "" - - "" (line ~N) - references `X`, first introduced at line ~M ("") - → Suggest: move introduction before first reference -``` - -### 2. Duplicate/redundant content check - -Scan across all sections for bullets or sentences that convey the same information. Flag pairs where: -- The same fact is stated in two places (even with different wording). -- A later bullet restates what an earlier bullet already covered. - -**Output format:** -``` -DUPLICATE: - - line ~N: "" - - line ~M: "" - → Suggest: consolidate into a single bullet, keep in whichever section introduces it first -``` - -### 3. Point-form style recommendations - -For any paragraph-style prose that could be tightened into point-form technical English, suggest a rewrite. Technical English means: -- Active voice, present tense -- One fact per bullet -- No filler words ("it should be noted that", "in order to", "basically") -- Named subjects (not "it" or "this" without antecedent) - -**Output format:** -``` -STYLE: line ~N - Original: "" - Suggested: - - - - -``` - -### 4. Motivation gap detection (what without why) - -Scan for statements that introduce a NEW capability, behavior change, or design decision without explaining the problem it solves or the reason it exists. - -**Symptoms to flag:** -- "allows X to Y" / "enables X" / "adds support for X" without a preceding or following "because" / "so that" / problem statement -- Specs sections that describe HOW a mechanism works (storage layout, gas, ordering, event sequence) without stating WHY it matters to the reader -- Design-decision bullets that state a choice without rationale ("we chose X" with no "because Y") - -**What is NOT a gap (do not flag):** -- A feature whose motivation is explained earlier in the same document (Summary or Motivation section) does not need re-explanation in Specs — unless the Specs section exceeds ~30 lines, at which point a reader skimming only that section loses context -- Standard interface conformance ("ERC-8056 conformant") is a valid WHY when the standard is linked or named -- Backwards-compatibility statements ("unchanged for back-compat") are self-motivating -- Q&A pairs in a "Guarantees and edge cases" section — these answer "how does it behave?" which is their purpose - -**Output format:** -``` -WHY-GAP: line ~N, section "" - Statement: "" - Missing: motivation / problem statement — why does this capability exist? - Hint: -``` - -**Example:** -``` -WHY-GAP: line ~12, section "Summary" - Statement: "The new scheduled path allows issuers to define a new multiplier in advance and activate it at a specific future timestamp." - Missing: motivation — why do issuers need advance scheduling rather than instant updates? - Hint: State the operational driver (e.g., corporate actions require advance notice to exchanges/custodians before the multiplier flips). -``` - -## Output structure - -``` -# Changelog Audit: - -## Progressive Discovery -### Section: - - -## Duplicates - - -## Style Suggestions - - -## Motivation Gaps - - -## Summary -- Ordering violations: N -- Duplicate pairs: N -- Style suggestions: N -- Motivation gaps: N -``` - -## Rules - -- Do NOT edit the file. Report only. -- If the user passes `--fix`, then apply the suggested reorderings and consolidations directly to the file. Still output the report showing what changed. -- Treat markdown tables as atomic units — do not reorder rows within a table for progressive discovery (tables have their own sort order conventions). -- Ignore the audience blockquote (`> **Audience:**...`) — it's introductory framing, not subject to reorder. -- Cross-section references are fine: a concept introduced in an earlier section can be referenced in a later section without violation. -- Only flag ordering issues within the same `##` section. diff --git a/.claude/skills/changelog-grill/SKILL.md b/.claude/skills/changelog-grill/SKILL.md deleted file mode 100644 index 385b0006..00000000 --- a/.claude/skills/changelog-grill/SKILL.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -name: changelog-grill -description: Interview the user relentlessly about a changelog or ADR template until reaching shared understanding. Proposes point-form edits after each round. ---- - -# Changelog Grill - -Interview me relentlessly about every aspect of this plan until we reach a shared understanding. - -## Setup - -1. Read the template file (path provided by user, or pasted content). -2. Read `changelog/TEMPLATE_POINT_FORM.md` for expected structure. -3. Inspect related source, interfaces, tests, and existing changelog entries to verify facts. - -## Protocol - -Walk down each branch of the design tree resolving dependencies between decisions one by one. - -- Ask exactly ONE question per message. Never ask two or more questions in the same output. -- If the question can be answered by exploring the codebase, explore the codebase instead of asking. If there are key details missing in the template suggest them. -- For each question, provide your recommended answer. -- After the user responds, apply the edit to the point-form template immediately, then ask the - next single question. - -Question format: - -``` -❓ ****: <question + context> -➡️ **Recommendation:** <your recommended answer and why> -``` - -## After each answer - -Apply the result directly to the point-form template file. Edits must use point-form technical -English: active voice, present tense, one fact per bullet, named subjects, state WHY alongside WHAT. - -## Completion - -Done when every section has been reviewed, no assumption remains silent, and the user confirms -shared understanding.