From a833e019d613bf23ef611ffa70e2afc00499f9d4 Mon Sep 17 00:00:00 2001 From: Oleh Omelchenko Date: Tue, 16 Jun 2026 21:44:43 +0300 Subject: [PATCH] Skills: eng-council consult leads with need/laziest-rung; alignment flags known-ceiling shortcuts --- .claude/skills/alignment/SKILL.md | 45 ++++++++++++++--------------- .claude/skills/eng-council/SKILL.md | 26 +++++++++++++---- 2 files changed, 43 insertions(+), 28 deletions(-) diff --git a/.claude/skills/alignment/SKILL.md b/.claude/skills/alignment/SKILL.md index 075aa62..9becef6 100644 --- a/.claude/skills/alignment/SKILL.md +++ b/.claude/skills/alignment/SKILL.md @@ -89,7 +89,12 @@ Review all changes in scope. If changes span multiple patterns below, apply all standing _why_, not the story of how this session arrived at it. Rewrite session-decision narration ("this bit us", "we decided", "supersedes the earlier plan", "used to do X") and directives-to-future-self ("keep the escape") into a standing property of the code; keep the - technical fact, drop the resolution framing. + technical fact, drop the resolution framing. A deliberate simplification with a known + ceiling — a naive scan that's fine at current sizes, a coarse heuristic, a + correct-but-unscalable default — gets a comment naming the ceiling and the upgrade path + (`// linear scan; index if the library grows large`), so it reads as a chosen shortcut, + not a missed one; unmarked, it invites a later reviewer to either "fix" it back into + complexity or flag the absent rationale. 7. **Workarounds**: Flag code that works around a problem rather than solving it (`// HACK`, silent catch-and-ignore, feature detection for internal bugs). A justified workaround @@ -126,28 +131,22 @@ Review all changes in scope. If changes span multiple patterns below, apply all apply migrations; destructive actions (delete, revert, reset) confirm; storage failures warn rather than silently lose data. -13. **Documentation hygiene** (the docs are maintained artifacts; keep them at altitude): - - **Self-containment**: documentation and comments must not add pointers that require an - external repository to follow. Knowledge gets captured locally (`docs/spec/`, - `docs/architecture/`), not linked out. - - **Matter-of-fact, as rule #6 demands of comments**: docs state _what the design is_ + - the standing _why_, never the build narration (`this bit us`, `we chose X over Y`, - `resolves the former divergence`, `council resolution recorded`). A decision is recorded - by stating its resulting rule, not the story of reaching it. - - **No stale-prone constructs** — three things rot the moment the code moves: - - **TS code blocks that copy current implementation.** A snippet mirroring a real - module goes stale on its next rename. An illustrative _shape_ sketch is fine; a copy - of specific current code is a finding — replace it with a navigation map (`file → -role`) or the rule it demonstrates. - - **Positional sub-section cross-refs.** Cite a doc by a stable identifier — the file - (`spec §07`, `arch 02`) or a named section / quoted rule — never a positional - sub-section number (`arch 07 §4`) that renumbers when a section is inserted above it. - Applies to code comments too. - - **Volatile exact counts.** Test counts, file/LOC counts, and one-off timings churn - daily and read as stale within a week. State the qualitative fact ("seconds of layout - on a large dataset"), not the measured number. The only homes for exact figures are - `docs/exploration/` records (frozen by definition) and `docs/codebase-metrics.md` (the - deliberately-tracked trend). +13. **Documentation hygiene** (the docs are maintained artifacts; keep them at altitude): - **Self-containment**: documentation and comments must not add pointers that require an + external repository to follow. Knowledge gets captured locally (`docs/spec/`, + `docs/architecture/`), not linked out. - **Matter-of-fact, as rule #6 demands of comments**: docs state _what the design is_ + + the standing _why_, never the build narration (`this bit us`, `we chose X over Y`, + `resolves the former divergence`, `council resolution recorded`). A decision is recorded + by stating its resulting rule, not the story of reaching it. - **No stale-prone constructs** — three things rot the moment the code moves: - **TS code blocks that copy current implementation.** A snippet mirroring a real + module goes stale on its next rename. An illustrative _shape_ sketch is fine; a copy + of specific current code is a finding — replace it with a navigation map (`file → +role`) or the rule it demonstrates. - **Positional sub-section cross-refs.** Cite a doc by a stable identifier — the file + (`spec §07`, `arch 02`) or a named section / quoted rule — never a positional + sub-section number (`arch 07 §4`) that renumbers when a section is inserted above it. + Applies to code comments too. - **Volatile exact counts.** Test counts, file/LOC counts, and one-off timings churn + daily and read as stale within a week. State the qualitative fact ("seconds of layout + on a large dataset"), not the measured number. The only homes for exact figures are + `docs/exploration/` records (frozen by definition) and `docs/codebase-metrics.md` (the + deliberately-tracked trend). 14. **User-facing copy**: keep user-visible strings centralized and written for users (sentence case, active voice, no "please", no exclamation marks in errors). If/when an i18n layer diff --git a/.claude/skills/eng-council/SKILL.md b/.claude/skills/eng-council/SKILL.md index 70c5b96..bfd5027 100644 --- a/.claude/skills/eng-council/SKILL.md +++ b/.claude/skills/eng-council/SKILL.md @@ -1,6 +1,6 @@ --- name: eng-council -description: Convene the engineering council — an evidence-grounded review of codebase structure, consistency, layering altitude, subtraction (what should be deleted), and documentation altitude. Modes - whole-codebase sweep (milestone boundary or backfill), refactor review, new-functionality review, and a pre-build consult. Auto-invoke only the consult mode - before introducing a new module/store/modal/service/hook shape, ask the council for the canonical shape and what already exists to reuse. All other modes run on demand. +description: Convene the engineering council — an evidence-grounded review of codebase structure, consistency, layering altitude, subtraction (what should be deleted), and documentation altitude. Modes - whole-codebase sweep (milestone boundary or backfill), refactor review, new-functionality review, and a pre-build consult. Auto-invoke only the consult mode - before introducing a new module/store/modal/service/hook shape, ask the council whether it needs to exist and the laziest rung that meets the need (stdlib/native/already-shipped dep before new code), then the canonical shape and what already exists to reuse. All other modes run on demand. disable-model-invocation: false --- @@ -109,10 +109,26 @@ not a move-by-move log). ### Consult — before writing code -The cheapest and most preventive mode; the only one that auto-fires. Before building a -new instance of a kind (a modal, store, service, hook, persistence path): line up the -existing instances, name the canonical shape, list what already exists to reuse, and flag -what the new work might make deletable. Two paragraphs, no report scaffolding. +The cheapest and most preventive mode; the only one that auto-fires. Two questions, in +order, before a line is written. + +**Does it need to exist — and at what rung?** Stop at the first rung that holds: (1) the +need is speculative → say so and skip it (YAGNI); (2) stdlib or a language built-in does +it; (3) a native platform feature covers it — `` over a picker lib, CSS +over JS, an IndexedDB/DB constraint over app code; (4) an already-shipped dependency solves +it — Monaco, vega/vega-lite, Zustand are already in the bundle, so never add a dependency, +or hand-roll, for what one of them or a few lines covers (a new dependency owes the +justification `/alignment` demands). Only past the rungs is fresh structure earned. Lazy is +less code, not a flimsier algorithm: between two equal-size options take the one correct on +edge cases, and never simplify away input validation at trust boundaries, error handling +that prevents data loss, or accessibility. + +**If it must be built — what shape?** Line up the existing instances of the kind (modal, +store, service, hook, persistence path), name the canonical shape, list what to reuse, and +flag what the new work might make deletable. An abstraction is earned only by ≥ 2 call +sites that would use it today (deletion rule 3). + +No report scaffolding — these two answers are the output. ## Report format