From cad19445b0fb4b02af06ac4a10fa4476066779e2 Mon Sep 17 00:00:00 2001 From: Oleh Omelchenko Date: Wed, 10 Jun 2026 17:11:15 +0300 Subject: [PATCH] Add matter-of-fact comment/doc voice rule to alignment and doc-update skills --- .claude/skills/alignment/SKILL.md | 13 +++++++++---- .claude/skills/doc-update/SKILL.md | 4 ++++ 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/.claude/skills/alignment/SKILL.md b/.claude/skills/alignment/SKILL.md index 4f94e84..5988b70 100644 --- a/.claude/skills/alignment/SKILL.md +++ b/.claude/skills/alignment/SKILL.md @@ -48,7 +48,11 @@ Review all changes in scope. If changes span multiple patterns below, apply all 6. **Code Comments**: Comments should not duplicate what the code already says. Remove parroting comments. Ensure comments capture non-obvious _why_ — design decisions, constraints, gotchas. Flag missing comments where a reader would reasonably ask "why is this - done this way?" + done this way?" Write them as **matter-of-fact prose** — state what the code _is_ and the + 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. 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 @@ -58,9 +62,10 @@ Review all changes in scope. If changes span multiple patterns below, apply all 8. **Pre-existing & out-of-scope issues — leave a breadcrumb.** For anything you notice but don't fix (pre-existing patterns the new code follows; observations the change exposes but that are out of scope), mark it with a `// TODO:` at the relevant code site explaining - _what_ could be improved and _why_ (1–3 lines). **If an observation is important enough to - mention in the summary, it is important enough to deserve a `// TODO:` at the code location** - — otherwise the next reader has no way to recover the context. + _what_ could be improved and _why_ (1–3 lines), as matter-of-fact prose (rule #6 — no + session narration). **If an observation is important enough to mention in the summary, it is + important enough to deserve a `// TODO:` at the code location** — otherwise the next reader + has no way to recover the context. ### Architecture & Project-Specific Checks diff --git a/.claude/skills/doc-update/SKILL.md b/.claude/skills/doc-update/SKILL.md index ab96029..adfe9de 100644 --- a/.claude/skills/doc-update/SKILL.md +++ b/.claude/skills/doc-update/SKILL.md @@ -89,6 +89,10 @@ For each target document: ### 4. Apply updates - **Rules and constraints over descriptions**: "X must do Y because Z" beats "X works by A, B, C". +- **Matter-of-fact voice**: write what the design _is_ and the standing _why_, not the story + of how this session arrived at it. No decision-log narration ("this bit us", "we decided", + "supersedes the earlier plan", "used to do X"), no directives-to-future-self ("keep the + escape"). Phrase rationale as a standing property of the system, not a resolution reached. - **Stability over specifics**: no line numbers, no file counts, no volatile details. - **Proportional**: a missing sentence doesn't need a new section; a missing concept does. - **Match existing style**: follow surrounding formatting, heading levels, tone.