mirror of
https://github.com/olehomelchenko/astrolabe.git
synced 2026-08-08 02:02:33 +00:00
Add matter-of-fact comment/doc voice rule to alignment and doc-update skills
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user