From de9dbf3ec848cf83857c80ccd904829c25a8c723 Mon Sep 17 00:00:00 2001 From: Oleh Omelchenko Date: Sun, 14 Jun 2026 23:57:39 +0300 Subject: [PATCH] Docs hygiene: enforce in /alignment, add eng-council Documentation seat and beyond-scope notes --- .claude/skills/alignment/SKILL.md | 25 ++++++++-- .claude/skills/doc-update/SKILL.md | 7 +++ .claude/skills/eng-council/SKILL.md | 75 +++++++++++++++++++---------- 3 files changed, 79 insertions(+), 28 deletions(-) diff --git a/.claude/skills/alignment/SKILL.md b/.claude/skills/alignment/SKILL.md index 9cf75b5..075aa62 100644 --- a/.claude/skills/alignment/SKILL.md +++ b/.claude/skills/alignment/SKILL.md @@ -126,9 +126,28 @@ 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. **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. +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/doc-update/SKILL.md b/.claude/skills/doc-update/SKILL.md index adfe9de..fef6086 100644 --- a/.claude/skills/doc-update/SKILL.md +++ b/.claude/skills/doc-update/SKILL.md @@ -108,6 +108,13 @@ or a major new section was added that should be discoverable. Not for minor addi - **Code walkthroughs**: prose that restates the code; goes stale on any rename. (Navigation maps that list file roles are fine.) +- **TS code blocks that copy current implementation**: a snippet mirroring a real module + rots on its next rename. An illustrative _shape_ sketch is fine; for real code, point to + the file (navigation map) or state the rule it demonstrates. +- **Stale-prone references**: positional sub-section cross-refs (`arch 07 §4` renumbers when + a section is inserted — cite the file `arch 07` or a named section) and exact counts + (test/file/LOC counts, one-off timings — state the qualitative fact; `codebase-metrics.md` + owns the tracked numbers). - **Obvious-from-code patterns**: if reading the file makes it clear, don't add docs. - **Session-specific context**: current task details, debugging steps taken. - **Speculative patterns**: only document conventions confirmed across multiple instances. diff --git a/.claude/skills/eng-council/SKILL.md b/.claude/skills/eng-council/SKILL.md index aa265b1..70c5b96 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, and subtraction (what should be deleted). 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 for the canonical shape and what already exists to reuse. All other modes run on demand. disable-model-invocation: false --- @@ -8,9 +8,18 @@ disable-model-invocation: false The structural counterpart to `/council`. The design council guards what the user sees; the engineering council guards the shape of the codebase — structure, consistency, -altitude, and above all **net growth**. `/alignment` reviews a diff in isolation and can't -see cross-cutting drift: parallel patterns forming, near-duplicate helpers, modules -outgrowing their responsibility. This skill exists to see that whole picture. +altitude, documentation, and above all **net growth**. `/alignment` reviews a diff in +isolation and can't see cross-cutting drift: parallel patterns forming, near-duplicate +helpers, modules outgrowing their responsibility, docs accreting a move-by-move log. This +skill exists to see that whole picture. + +**The lens is wider than the diff — on purpose.** `/alignment` stays inside the change and +parks anything else as a `// TODO:`. The engineering council is the opposite: it reviews +the change _from altitude_, and is expected to lift its eyes to what surrounds it and +record improvement opportunities it notices outside the reviewed lines. A review that finds +nothing beyond its own diff has stayed too close to the ground. Those observations are +**noted, not fixed** (see Beyond-scope notes in the report) — surfacing them is the value; +the user triages. **Seats are evidence lenses, not personas.** The design council works because every seat quotes a real corpus. There is no external canon for software structure, so a seat here is @@ -37,14 +46,17 @@ encoded in the report format instead: Run **sequentially, in this order, in this session** — no subagent fan-out. Later seats consume earlier findings (Subtraction needs Consistency's verdict on which variant is -canonical before deciding which duplicate dies). +canonical before deciding which duplicate dies; Documentation runs last so it can check the +docs against what the other seats actually found — a doc describing a shape Consistency says +no longer exists is stale). -| Seat | Question | Evidence it gathers | -| --------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Structure** | Is the dependency picture still the documented one? | `npx madge --circular --extensions ts,tsx src` (cycles); `npx madge --json src` for fan-in/fan-out outliers; grep for layer leaks (`docs/architecture/00-overview.md` defines the layers — core imports nothing from app; only infrastructure touches browser APIs). Oversized modules: files ≫ their peers' size doing > 1 job. | -| **Consistency** | How many shapes does each _kind_ of thing have? | Line up all instances of a kind (modals, stores, services, hooks, confirm flows, persistence subscribers) side by side. Count distinct shapes; name the canonical one; list divergers. Divergence is only visible in the line-up — never judge an instance alone. | -| **Altitude** | Is logic at the layer where it's cheapest to test? | Testable logic stuck in components that belongs in `src/core/` or stores (the testing philosophy in `AGENTS.md` is the canon: core hardest, components lightest). Spec operations outside core. Duplicated derivations that should be a store selector. | -| **Subtraction** | What can be deleted? | `npx knip` (dead exports, unused files/deps); `npx jscpd src --min-tokens 50` (duplication); grep for abstractions with a single implementation, re-implementations of an existing utility, props/options/branches no caller exercises, spec'd-then-abandoned remnants. Consumes all prior seats' findings. | +| Seat | Question | Evidence it gathers | +| ----------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Structure** | Is the dependency picture still the documented one? | `npx madge --circular --extensions ts,tsx src` (cycles); `npx madge --json src` for fan-in/fan-out outliers; grep for layer leaks (`docs/architecture/00-overview.md` defines the layers — core imports nothing from app; only infrastructure touches browser APIs). Oversized modules: files ≫ their peers' size doing > 1 job. | +| **Consistency** | How many shapes does each _kind_ of thing have? | Line up all instances of a kind (modals, stores, services, hooks, confirm flows, persistence subscribers) side by side. Count distinct shapes; name the canonical one; list divergers. Divergence is only visible in the line-up — never judge an instance alone. | +| **Altitude** | Is logic at the layer where it's cheapest to test? | Testable logic stuck in components that belongs in `src/core/` or stores (the testing philosophy in `AGENTS.md` is the canon: core hardest, components lightest). Spec operations outside core. Duplicated derivations that should be a store selector. | +| **Subtraction** | What can be deleted? | `npx knip` (dead exports, unused files/deps); `npx jscpd src --min-tokens 50` (duplication); grep for abstractions with a single implementation, re-implementations of an existing utility, props/options/branches no caller exercises, spec'd-then-abandoned remnants. Consumes all prior seats' findings. | +| **Documentation** | Do the docs hold a structured general picture, or accrete a move-by-move log? | Doc sizes & growth (`wc -l docs/architecture/*.md`; the `codebase-metrics.md` trend). Grep `docs/` for decision-log narration (`this bit us`, `we chose`/`we decided`, `supersed`, `resolves the former`, `previously`, `council resolution recorded`, one-off measurements) and for per-instance worked examples that re-illustrate a principle already stated generally or restate code. Embedded TS blocks that copy current code (vs. illustrative shape-sketches). Sections > 50 lines (doc-update's own bar). Stale-prone refs: line/file/test counts, positional sub-section cross-refs (`arch 07 §4`) that renumber, one-off timings. **Docs-vs-code drift:** a doc describing a shape the other seats found no longer exists. The bar (from `/doc-update`): docs state _what the design is_ + the standing _why_ at a stable altitude — not how the build arrived there. | Tool notes: `madge`, `knip`, `jscpd` are **not** project dependencies — run via `npx`, treat output as evidence, not verdict (knip false-positives on entry points and dynamic @@ -65,8 +77,9 @@ divergence whose rationale is recorded nowhere is itself a finding. ### Sweep — whole codebase For: milestone boundaries, the one-off backfill, "how healthy are we?" on demand. -**Never on a schedule.** Scope: all of `src/` (+ `styles/` for the Structure seat). All -four seats. Output: the full report (format below) **plus a metrics snapshot row** +**Never on a schedule.** Scope: all of `src/` (+ `styles/` for the Structure seat, `docs/` +for the Documentation seat). All five seats. Output: the full report (format below) **plus a +metrics snapshot row** appended to `docs/codebase-metrics.md` (create on first sweep): ``` @@ -80,8 +93,9 @@ The trend line is the point — accretion becomes visible instead of felt. For: a landed or in-progress refactor (`git diff` / `git diff --staged`). Scope: changed files **plus their one-hop import neighborhood** (importers and imports) — drift is only visible relative to neighbors. Seats: Consistency and Subtraction always; Structure if -imports moved. Center question: did this refactor _reduce_ the number of shapes, or add -variant N+1? (Deletion rule 4 applies with full force.) +imports moved; Documentation if the change touched a doc or makes one stale. Center +question: did this refactor _reduce_ the number of shapes, or add variant N+1? (Deletion +rule 4 applies with full force.) ### New-functionality review @@ -89,7 +103,9 @@ For: a new feature in the diff. Scope: changed files + one-hop neighborhood. Sea Consistency (does it follow the canonical shape for its kind?), Altitude (is the logic in core/stores, not the component?), Subtraction (does it re-implement an existing utility? does every prop/option/branch have a caller?), Structure if a new module or dependency -appeared (a new dependency needs the same justification `/alignment` demands). +appeared (a new dependency needs the same justification `/alignment` demands), Documentation +if the feature added or should have added docs (and whether what it added stays at altitude, +not a move-by-move log). ### Consult — before writing code @@ -103,17 +119,26 @@ what the new work might make deletable. Two paragraphs, no report scaffolding. For sweep and review modes: 1. **Verdict** — two or three sentences: overall shape, the one thing to act on first. -2. **Findings** — per seat, each finding: `file:line`, the evidence, the proposed fix, - net LOC delta. Skip seats with nothing to say in one line, not zero. -3. **Remove** — the mandatory section (deletion rule 2). -4. **Net delta** — total LOC delta if all findings were accepted. -5. **Rules discovered** — recurring patterns worth making law (see Close the loop). +2. **Findings** — per seat (Structure, Consistency, Altitude, Subtraction, Documentation), + each finding: `file:line`, the evidence, the proposed fix, net LOC delta. Skip seats + with nothing to say in one line, not zero. +3. **Beyond-scope notes** — improvement opportunities the review noticed _outside_ the + reviewed change: a shape worth revisiting elsewhere, a doc drifting, an abstraction + forming across files the diff didn't touch. Noted with `file:line` and a one-line why, + **not fixed here** — the user triages. Expected to be non-empty in a healthy review; an + empty one means either a pristine codebase or a council that stayed too close to the diff. +4. **Remove** — the mandatory section (deletion rule 2). +5. **Net delta** — total LOC delta if all findings were accepted. +6. **Rules discovered** — recurring patterns worth making law (see Close the loop). **Fix vs. propose:** mechanical, behavior-preserving removals (dead exports, unused files, -unreferenced props) — fix directly, keep `npm run typecheck` + `npm test` green. -Structural findings (merge two shapes, move logic across layers, kill an abstraction) — -propose with the evidence; they're the user's call. Out-of-scope observations get a -`// TODO:` breadcrumb at the code site, same rule as `/alignment`. +unreferenced props) — fix directly, keep `npm run typecheck` + `npm test` green. Trimming +decision-log narration from a doc back to the matter-of-fact bar is the documentation +equivalent of a behavior-preserving removal — fix directly. Structural findings (merge two +shapes, move logic across layers, kill an abstraction, restructure or consolidate a doc) — +propose with the evidence; they're the user's call. An in-scope out-of-place observation +gets a `// TODO:` breadcrumb at the code site (same rule as `/alignment`); a beyond-scope +one goes in the Beyond-scope notes section so it surfaces rather than scattering as TODOs. ## Close the loop