oleh/astrolabe
1
0
Fork 0
mirror of https://github.com/olehomelchenko/astrolabe.git synced 2026-08-08 02:02:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add matter-of-fact comment/doc voice rule to alignment and doc-update skills

Browse Source
This commit is contained in:
Oleh Omelchenko
2026-06-10 17:11:15 +03:00
parent 62d0697f0e
commit cad19445b0
2 changed files with 13 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/alignment/SKILL.md
+9 -4
View File
@@ -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 6. **Code Comments**: Comments should not duplicate what the code already says. Remove
parroting comments. Ensure comments capture non-obvious _why_ — design decisions, parroting comments. Ensure comments capture non-obvious _why_ — design decisions,
constraints, gotchas. Flag missing comments where a reader would reasonably ask "why is this 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`, 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 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 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 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 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 _what_ could be improved and _why_ (1–3 lines), as matter-of-fact prose (rule #6 — no
mention in the summary, it is important enough to deserve a `// TODO:` at the code location** session narration). **If an observation is important enough to mention in the summary, it is
— otherwise the next reader has no way to recover the context. 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 ### Architecture & Project-Specific Checks
.claude/skills/doc-update/SKILL.md
+4
View File
@@ -89,6 +89,10 @@ For each target document:
### 4. Apply updates ### 4. Apply updates
- **Rules and constraints over descriptions**: "X must do Y because Z" beats "X works by A, B, C". - **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. - **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. - **Proportional**: a missing sentence doesn't need a new section; a missing concept does.
- **Match existing style**: follow surrounding formatting, heading levels, tone. - **Match existing style**: follow surrounding formatting, heading levels, tone.