@clipboard-health/ai-rules 2.30.0 → 2.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/ai-rules",
-  "version": "2.30.0",
+  "version": "2.31.0",
   "description": "Pre-built AI agent rules for consistent coding standards.",
   "keywords": [
     "ai",

package/skills/cb-babysit/SKILL.md

@@ -19,9 +19,9 @@ Resolve bundled "./scripts" paths relative to SKILL.md.
 
 The skill uses two sentinels with visible footer lines.
 
-**Addressed sentinel**: `<sub>🤖 <code>cb-babysit:addressed v1 core@3.11.0</code></sub>`. Appended on its own line at the end of every reply the skill posts so re-runs know which threads and review-body comments are already handled. Dedupe also recognizes the legacy `babysit-pr:addressed v1` prefix from before this skill was renamed.
+**Addressed sentinel**: `<sub>🤖 <code>cb-babysit:addressed v1 core@3.12.0</code></sub>`. Appended on its own line at the end of every reply the skill posts so re-runs know which threads and review-body comments are already handled. Dedupe also recognizes the legacy `babysit-pr:addressed v1` prefix from before this skill was renamed.
 
-**Follow-up sentinel**: `<sub>🤖 <code>cb-babysit:followup v1 core@3.11.0</code></sub>`. Attached to replies that defer an out-of-scope comment as a tracked follow-up. The sentinel is additive: the post-reply scripts still append the `addressed` sentinel at the end.
+**Follow-up sentinel**: `<sub>🤖 <code>cb-babysit:followup v1 core@3.12.0</code></sub>`. Attached to replies that defer an out-of-scope comment as a tracked follow-up. The sentinel is additive: the post-reply scripts still append the `addressed` sentinel at the end.
 
 **Sentinel recency rules.** The script emits a per-thread `activityState` with three values. Step 6a owns the handling rules for each state.
 
@@ -247,7 +247,7 @@ Body templates (the script appends the `addressed` sentinel if missing):
 - **Agree**: `Addressed in <commit-url>. <one-line what-changed>.`
 - **Disagree**: `Leaving current behavior. <reasoning>.`
 - **Already fixed**: `Already handled by <commit-url-or-file:line>. <brief pointer>.`
-- **Defer**: `Out of scope for this PR; this looks like follow-up work rather than something introduced or required by this change. <one-line rationale or pointer if useful>.\n\n<sub>🤖 <code>cb-babysit:followup v1 core@3.11.0</code></sub>`
+- **Defer**: `Out of scope for this PR; this looks like follow-up work rather than something introduced or required by this change. <one-line rationale or pointer if useful>.\n\n<sub>🤖 <code>cb-babysit:followup v1 core@3.12.0</code></sub>`
 
 For Defer replies, include the follow-up sentinel on its own line as shown. The script will append the `addressed` sentinel after it on its own line, so the final body ends with the follow-up sentinel followed by a blank line followed by the `addressed` sentinel. `grep cb-babysit:followup` finds the deferral and `grep cb-babysit:addressed` still marks the thread handled for dedupe.
 
@@ -263,7 +263,7 @@ The PR-level summary should:
 
 - Group by source. Use `## Review-body findings` for step-7 work and `## Conversation-tab comments` for step-6b work. Omit a section if its list is empty.
 - Inside each section, group verdicts under **Agree / Disagree / Already fixed / Deferred (out of scope)** subheadings. Omit a subheading if its list is empty.
-- Under **Deferred (out of scope)**, list each deferred item as a bullet, followed on its own line by `<sub>🤖 <code>cb-babysit:followup v1 core@3.11.0</code></sub>` so grep catches them individually.
+- Under **Deferred (out of scope)**, list each deferred item as a bullet, followed on its own line by `<sub>🤖 <code>cb-babysit:followup v1 core@3.12.0</code></sub>` so grep catches them individually.
 - Include the commit URL for fixes.
 - End with a fenced fingerprint block listing every current fingerprint (addressed and deferred) one per line. Include both `reviewBodyComments[].fingerprint` (whole-body, one per automated review) and `activeIssueComments[].fingerprint` (per Conversation-tab comment). Future runs dedupe by matching these against `priorBabysitSentinels`.
 

package/skills/cb-babysit/scripts/_sentinel.sh

@@ -10,7 +10,7 @@
 
 SENTINEL_PREFIX='cb-babysit:addressed v1 '
 LEGACY_SENTINEL_PREFIX='babysit-pr:addressed v1 '
-SENTINEL='<sub>🤖 <code>cb-babysit:addressed v1 core@3.11.0</code></sub>'
+SENTINEL='<sub>🤖 <code>cb-babysit:addressed v1 core@3.12.0</code></sub>'
 
 # Bot author allowlist (JSON array literal). Used by unresolvedPrComments.sh
 # as a fallback when GraphQL's `author.__typename == "Bot"` misses a GitHub

package/skills/cb-ship/references/pr-template.md

@@ -17,5 +17,5 @@ Concisely explain the user intent from session history and the meaningful behavi
 
 Optional, don't fabricate: ticket links, rollout plan, residual risk, or specific areas for reviewers to focus.
 
-<sub>🤖 <code>cb-ship:created v1 core@3.11.0</code></sub>
+<sub>🤖 <code>cb-ship:created v1 core@3.12.0</code></sub>
 ```

package/skills/cb-ship/references/simplify.md

@@ -18,15 +18,16 @@ Review each change for hacky patterns:
 
 1. **Redundant state** that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls.
 2. **Parameter sprawl**: Adding new parameters to a function instead of generalizing or restructuring existing ones.
-3. **Copy-paste with slight variation**: near-duplicate code blocks that should be unified with a shared abstraction.
+3. **Copy-paste with slight variation**: near-duplicate code blocks that should be unified with a shared abstraction. Exempt intentional, structurally-parallel repetition that aids readability — test arrange/act/assert blocks are the common case.
 4. **Leaky abstractions**: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries.
-5. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase.
-6. **Unnecessary JSX nesting**: wrapper Boxes/elements that add no layout value. Check if inner component props (flexShrink, alignItems, etc.) already provide the needed behavior.
-7. **Nested conditionals**: ternary chains (`a ? x : b ? y : ...`), nested if/else, or nested switch 3+ levels deep. Flatten with early returns, guard clauses, a lookup table, or an if/else-if cascade.
-8. **Unnecessary comments**: Delete comments explaining WHAT the code does (well-named identifiers already do that), narrating the change, or referencing the task/caller. Keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds).
-9. **Defensive code on trusted inputs**: null/empty/type guards on inputs already guaranteed upstream (a validated DTO, the type system, a controller that already checked), optional chaining where the types guarantee presence, fallbacks that mask bugs (`?? ''`, `|| []`, `?? 0` on values that should never be absent), and try/catch that only logs and rethrows or guards an impossible state. Leave guards at genuine trust boundaries (raw request bodies, webhook payloads, third-party responses) and any error handling around real I/O, network, parsing, or payments — removing those changes behavior.
-10. **Type escapes**: `as any`, `: any`, `as unknown as X`, gratuitous non-null `!`, `@ts-ignore`/`@ts-expect-error` added to dodge a type error — replace with the real type when it is determinable from the call site, the imported type, or the shape in use; if it is not, leave it and flag it rather than deleting it (breaks the build) or swapping in a TODO (more clutter).
-11. **Leftover debug statements**: stray `console.log`/print-style output used to debug; keep intentional logging that goes through the repo's logger.
+5. **Premature abstraction (YAGNI)**: an interface, wrapper, or config object introduced for a single caller — inline it until a second caller justifies it.
+6. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase.
+7. **Unnecessary JSX nesting**: wrapper Boxes/elements that add no layout value. Check if inner component props (flexShrink, alignItems, etc.) already provide the needed behavior.
+8. **Nested conditionals**: ternary chains (`a ? x : b ? y : ...`), nested if/else, or nested switch 3+ levels deep. Flatten with early returns, guard clauses, a lookup table, or an if/else-if cascade.
+9. **Unnecessary comments**: Delete comments explaining WHAT the code does (well-named identifiers already do that), narrating the change, or referencing the task/caller. Keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds).
+10. **Defensive code on trusted inputs**: null/empty/type guards on inputs already guaranteed upstream (a validated DTO, the type system, a controller that already checked), optional chaining where the types guarantee presence, fallbacks that mask bugs (`?? ''`, `|| []`, `?? 0` on values that should never be absent), and try/catch that only logs and rethrows or guards an impossible state. Leave guards at genuine trust boundaries (raw request bodies, webhook payloads, third-party responses) and any error handling around real I/O, network, parsing, or payments — removing those changes behavior.
+11. **Type escapes**: `as any`, `: any`, `as unknown as X`, gratuitous non-null `!`, `@ts-ignore`/`@ts-expect-error` added to dodge a type error — replace with the real type when it is determinable from the call site, the imported type, or the shape in use; if it is not, leave it and flag it rather than deleting it (breaks the build) or swapping in a TODO (more clutter).
+12. **Dead & leftover code**: unreachable branches and stray debug statements (`console.log`/print-style output) — delete outright rather than commenting out; keep intentional logging that goes through the repo's logger. Unused exports/symbols with no remaining references are already covered by `.rules/common/typeScript.md`'s Dead Code Cleanup rule.
 
 ### 3: Efficiency review
 

package/skills/humanize-prose/SKILL.md

@@ -1,26 +1,25 @@
 ---
 name: humanize-prose
-description: Strip AI writing tells from prose you draft or clean: PR descriptions, Slack messages, docs, emails, commit messages. Cuts hedging, throat-clearing, marketing adjectives, bullet bloat, connective filler, and em-dashes. Use whenever the user asks to "humanize" text, "remove the AI slop" from writing, "make this not sound AI-generated", "deslop this PR description", or runs /humanize-prose. Also applies implicitly: any prose you draft for the user must already satisfy these rules.
+description: Strip AI writing tells from prose you draft or clean: PR descriptions, Slack messages, docs, emails, commit messages. Use whenever the user asks to "humanize" or "deslop" text, or runs /humanize-prose. Also applies implicitly: any prose you draft for the user must already satisfy these rules.
 ---
 
-# Humanize prose
+Strip AI writing tells out of prose, whether cleaning existing text or generating it. Edit in place, change as little as possible, preserve meaning. When a change would alter meaning, leave it and flag it.
 
-Strip AI writing tells out of prose, whether cleaning existing text or generating it. Edit in place, change as little as possible, preserve meaning. When a change would alter meaning, or you cannot tell which of two conflicting statements is correct, leave it and flag it.
-
-Applies to PR descriptions, Slack messages, docs, and emails.
-
-Cut:
+Cut, across the whole text, not just the first instance of each:
 
 - Throat-clearing openers: "In this PR, I've...", "This change introduces...", "I wanted to...".
 - Hedging filler: "it's worth noting", "it's important to", "generally speaking", "as you may know".
 - Marketing adjectives and trendy intensifiers: robust, seamless, comprehensive, powerful, leverage, streamline, delve, load-bearing.
 - Rule-of-three padding and restating the obvious.
-- Connective tissue that links sentences without adding content: "That said", "With that in mind", "To that end", "As such", "Moreover", "Furthermore", "Additionally", "It follows that". Drop the phrase or replace it with a full stop.
+- Connective tissue that links sentences without adding content: "That said", "With that in mind", "To that end", "As such", "Moreover", "Furthermore", "Additionally", "It follows that", "What this means is...". Drop the phrase or replace it with a full stop.
 - Duplicated information: a point already made earlier in different words, a closing line that repeats the opening, a sentence that restates its own heading. Keep it once.
 - Contradictory information: two statements in the same text that conflict (a number, a claim, or a recommendation stated one way then another). Keep the version that is correct and flag the contradiction; do not silently pick one if you cannot tell which is right.
 - Bullet bloat where two sentences of prose are tighter; bold-everything formatting.
 - Summary-of-the-summary closers: "In conclusion...", "Overall, this...".
 - Em-dashes and double hyphens (use a comma, colon, or full stop instead).
+- False agency: passive constructions or abstract/inanimate subjects performing human actions ("the complaint becomes a fix", "mistakes were made", "the decision emerges"). Name the actor.
+- Binary-contrast crutch: manufactured "not X, it's Y" framing standing in for a direct claim.
+- Vague declaratives and hollow absolutes: unsupported generalizations ("the implications are significant") and lazy extremes ("always", "never", "every") doing the work a specific claim should.
 
 Keep it concrete: what changed, why, what to check. Match the channel (a PR body is not a Slack one-liner).