@jayofemi/toolbox - npm Package Compare versions

Comparing version 1.4.0 to 1.5.0

package.json

 {
   "name": "@jayofemi/toolbox",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "An open library of reusable Claude Code skills, commands, and scripts, with a one-command installer.",
@@ -5,0 +5,0 @@ "type": "module",

skills/wording/scripts/lint.mjs

@@ -94,8 +94,40 @@ #!/usr/bin/env node
 	{
+		// A sentence that announces the shape of the answer or restates the topic
+		// instead of delivering it: "I've worked with X from both sides.", "I have
+		// also worked the server side.", "let me break this down", "at a high
+		// level". Lead with the substance. A clause opener like "On the server
+		// side," is fine; the standalone announcer is the tell.
+		id: "ai-tell-announce",
+		severity: "review",
+		pattern: /\b(?:(?:from|on)\s+both\s+(?:sides|fronts)|I(?:['’]ve| have)\s+(?:also\s+)?worked\s+(?:with\s+[\w-]+\s+)?(?:on|the)\s+[\w\s-]{0,15}?\bsides?\b|let\s+me\s+break\s+(?:this|it|that)\s+down|at\s+a\s+high\s+level|to\s+answer\s+(?:your|the)\s+question)\b/gi,
+		message: "topic-announcing / throat-clearing framing ('from both sides', 'I have also worked the X side', 'let me break this down'); lead with the substance, not the structure",
+	},
+	{
+		// A vague connective bolted onto the next clause as filler: "Around that",
+		// "On top of that", "That said", "At the end of the day". Cut it and state
+		// the point. Anchored sentence-initial so a literal mid-clause use ("built
+		// around that constraint") does not match.
+		id: "ai-tell-glue",
+		severity: "review",
+		pattern: /(?:^|[.!?]\s+)(?:Around that|On top of that|Beyond that|With that said|That said|All in all|All told|Needless to say|Suffice (?:it )?to say|At the end of the day|When all is said and done)\b/g,
+		message: "gluey filler transition ('Around that', 'On top of that', 'That said'); cut it and state the next point directly",
+	},
+	{
+		// Stacked relative clauses padding a noun: "Claude Code, the command-line
+		// tool, which I have used daily and which is my primary client". Keep the
+		// one essential detail or split the sentence.
+		id: "ai-tell-over-qualify",
+		severity: "review",
+		pattern: /\bwhich\s+[^,.;:!?\n]{5,80}?\s+and\s+which\b/gi,
+		message: "stacked 'which ... and which' clauses over-qualify the noun; keep the essential detail or split the sentence",
+	},
+	{
 		// A colon swapped in where an em dash would go (an elaboration that should
-		// just be a direct sentence). Advisory; legitimate in times, ratios, code.
+		// just be a direct sentence). Advisory; legitimate in times, ratios, code,
+		// a genuine label, or a list introduced by a word like "include" / "as
+		// follows" (those introducers are carved out below to cut false positives).
 		id: "colon-elaboration",
 		severity: "review",
-		pattern: /\b[a-z]+\s+[^.!?:\n]{0,50}[a-z]:\s+[a-z]/gi,
-		message: "colon may be standing in for an em dash; if it just elaborates, restructure into a direct sentence (fine for times, ratios, code, labels)",
+		pattern: /\b[a-z]+\s+[^.!?:\n]{0,50}?\b(?!(?:include|includes|including|included|follow|follows|following|namely|below)\b)[a-z]{2,}:\s+[a-z]/gi,
+		message: "colon may be standing in for an em dash; if it just elaborates, restructure into a direct sentence (fine for times, ratios, code, labels, and 'include'-style lists)",
 	},
@@ -102,0 +134,0 @@ ];

skills/wording/SKILL.md

@@ -19,3 +19,3 @@ ---
 1. **No em (U+2014) or en (U+2013) dash, anywhere.** Use a hyphen, comma, period, semicolon, parens, or a rewrite.
-2. **No colon standing in for an em dash.** A colon that just introduces an elaboration or list should be restructured into a direct sentence, even if slightly less formal. For example, "production software: web apps, mobile apps, and automations" becomes "production software including web apps, mobile apps, and automations". Still fine in clock times, ratios, code, and genuine labels.
+2. **No colon standing in for an em dash.** A colon that just introduces an elaboration or a bare list should be restructured into a direct sentence, even if slightly less formal. For example, "production software: web apps, mobile apps, and automations" becomes "production software including web apps, mobile apps, and automations". Still fine in clock times, ratios, code, genuine labels, and a real list introduced by a word like "include" or "as follows".
 3. **No AI-tell constructions:**
@@ -25,3 +25,6 @@ - the "No X, just Y" punch ("No run arounds, just results"),
    - the dismissive close ("that's the whole product / pitch / point"),
-   - the trailing "thinking out loud" hedge, a bound or qualifier tacked onto the end of a finished claim ("a dozen, if that", "a handshake, if you will"). State the point once instead.
+   - the trailing "thinking out loud" hedge, a bound or qualifier tacked onto the end of a finished claim ("a dozen, if that", "a handshake, if you will"),
+   - the topic-announcing opener that previews the answer instead of giving it ("from both sides", "let me break this down"),
+   - the gluey filler transition ("Around that", "On top of that", "That said"),
+   - the over-qualified noun that stacks "which ... and which" clauses. State the point once instead.
    Flat, informational contrast is fine: "fixed prices, not open ended hourly" tells the reader the pricing model. The same shape used as rhetoric is not.
@@ -60,3 +63,3 @@ 4. **Do not use "copy" to mean site text.** Prefer "wording" or "site text". ("Copy the file" is fine; "refresh the marketing copy" is the misuse.)
 
-For the contrast patterns, the test is whether the contrast carries information or is just drama (rule 3). For the colon (rule 2), restructure when it just introduces an elaboration or list, and leave it for clock times, ratios, code, or a genuine label. For "copy", confirm it means site text. The surface-jargon rule flags common offenders, but it cannot catch every phrasing, so judge plain language yourself on anything public-facing; a clean detector run is not proof the wording is intuitive.
+For the contrast patterns, the test is whether the contrast carries information or is just drama (rule 3). For the colon (rule 2), restructure when it just introduces an elaboration or a bare list, and leave it for clock times, ratios, code, a genuine label, or a list introduced by a word like "include" (the detector skips those). For the announcing, gluey-transition, and over-qualifying flags, cut the framing and lead with the substance. For "copy", confirm it means site text. The surface-jargon rule flags common offenders, but it cannot catch every phrasing, so judge plain language yourself on anything public-facing; a clean detector run is not proof the wording is intuitive.
 
@@ -63,0 +66,0 @@ ### 4. Fix

skills/wording/test/lint.test.mjs

@@ -124,1 +124,28 @@ import { test } from "node:test";
 });
+
+test("leaves an 'include' list-introducer colon clean", () => {
+	assert.equal(scanText("Skills I have strengthened include: prompt engineering, evals, and guardrails.").length, 0);
+});
+
+test("flags the announced-structure opener", () => {
+	assert.ok(ruleIds("I've worked with MCP from both sides.").includes("ai-tell-announce"));
+	assert.ok(ruleIds("I have also worked the server side.").includes("ai-tell-announce"));
+});
+
+test("leaves a plain 'on the X side' clause opener clean", () => {
+	assert.equal(scanText("On the server side, I built and shipped the API.").length, 0);
+});
+
+test("flags the gluey filler transition", () => {
+	assert.ok(ruleIds("Around that, I use a handful of tools.").includes("ai-tell-glue"));
+	assert.ok(ruleIds("The core works. On top of that, it is fast.").includes("ai-tell-glue"));
+});
+
+test("leaves a literal mid-clause 'around that' clean", () => {
+	assert.equal(scanText("We built the whole flow around that constraint.").length, 0);
+});
+
+test("flags the over-qualified which-and-which noun", () => {
+	const text = "Claude Code, the tool which I run daily and which is my primary client.";
+	assert.ok(ruleIds(text).includes("ai-tell-over-qualify"));
+});

No alert changes

Improved metrics

Total package byte prevSize

50944

8.6%

Lines of code

805

7.19%

No dependency changes