@cratis/pi 3.3.1 → 4.0.0

package/package/corpus/skills/cratis-social-feed-post/SKILL.md

@@ -42,6 +42,38 @@ a trade rather than a free improvement.
 Check the opening by reading only the first three lines and asking whether they are worth
 expanding. If the answer depends on the fourth line, the opening is wrong.
 
+## Sound like a person talking
+
+A post that reads as generated gets scrolled past as generated, however accurate it is. The
+fix is not a smoother sentence. It is writing the way someone who built the thing would
+explain it to a colleague over coffee.
+
+- **Open with something that happened.** What shipped, a real number, what you found this
+  week. A concrete, checkable event reads as a person reporting. An aphorism about the domain
+  ("A skill is just text…") reads as a slogan, however clever it is.
+- **Talk, don't announce.** Contractions, a sentence that starts with "So" or "And", a
+  parenthetical aside, a question answered straight away ("Why bother? Because…"). Use them
+  the way speech does, now and then, not as a new pattern on every line.
+- **Show the default, then the better way.** Name what the reader, or their coding agent,
+  writes today in concrete terms, then the shape you are offering, with real identifiers. A
+  before-and-after persuades; adjectives do not.
+- **Sell with specifics.** Enthusiasm is welcome and a list of real capabilities is
+  persuasive. What persuades is the command, the count, and the thing the reader can do
+  tomorrow, not "powerful", "seamless" or "game-changing".
+- **Say why in the words you would use out loud.** A reason with a stake ("we don't want the
+  good version of that to be a paid add-on") beats a principle stated in the abstract.
+- **Put a limit where it applies.** "On macOS and Linux, the installer…" carries the limit
+  inside the claim. A closing paragraph labeled "One honest limit:" reads as a disclaimer a
+  reviewer bolted on.
+- **Keep the review out of the copy.** Evidence, verification and approval language belongs
+  in the review record. A qualifier that protects the writer instead of informing the reader
+  makes the post read as noncommittal. Keep every qualification that is true and would
+  change what the reader does; drop the rest.
+- **Stop when you are done.** A plain next step ("Links in the comments") ends a post better
+  than a tidy closing maxim.
+
+The tells to remove in review are listed in the **cratis-writing-voice-and-cadence** skill.
+
 ## Never use Unicode pseudo-formatting
 
 Third-party tools offer pseudo-bold and pseudo-italic built from Mathematical Alphanumeric
@@ -66,7 +98,9 @@ said first. A point that needs visual weight belongs in an image with its own al
 
 ## Structure that survives a phone
 
-- One idea per post. A feed reader will not assemble two.
+- One thread per post. A feed reader will not assemble two arguments. An announcement may
+  still list what shipped as a plain list of short fragments inside that thread, with no
+  bolded labels and no slogan per item.
 - Short paragraphs, one to three sentences, and visibly different from each other in length.
   A column of identically sized blocks reads as a generated template before it reads as an
   argument.

package/package/corpus/skills/cratis-social-feed-post/verification.json

@@ -9,6 +9,10 @@
     { "kind": "skill-contains", "value": "A brief opening sentence is a hook doing its job" },
     { "kind": "skill-contains", "value": "No external link in the body" },
     { "kind": "skill-contains", "value": "No engagement bait" },
-    { "kind": "skill-contains", "value": "unofficial approximations" }
+    { "kind": "skill-contains", "value": "unofficial approximations" },
+    { "kind": "skill-contains", "value": "Sound like a person talking" },
+    { "kind": "skill-contains", "value": "Open with something that happened" },
+    { "kind": "skill-contains", "value": "Put a limit where it applies" },
+    { "kind": "skill-contains", "value": "Keep the review out of the copy" }
   ]
 }

package/package/corpus/skills/cratis-writing-voice-and-cadence/SKILL.md

@@ -27,6 +27,11 @@ recurrence.
 | **"rather than"** | The same correction carried by a different connective |
 | **Em-dash pivot** | The dash used to swing into a closing clause |
 | **"That is what X is for"** | A pointer sentence standing in for an explanation |
+| **Punchline fragment** | A two- or three-word sentence landing a slogan: "They run." |
+| **Signpost pair** | "That's the X. Here's the Y." Announcing the structure instead of having one |
+| **Labeled caveat** | "One honest limit:" A limitation parked in its own closing paragraph |
+| **Aphoristic close** | A tidy maxim as the last line, restating what the piece already said |
+| **Reflexive triplet** | Three parallel items where the thought had one or two |
 
 To measure rather than guess, count them. Searching for `, not a`, `; ` between two clauses,
 `rather than`, and an em-dash followed by a short closing clause takes a few minutes across a
@@ -48,9 +53,23 @@ Look at ten pieces together, not one at a time:
   assertion — "A screen that needs…", "A registration test can…" — is one move. Alternate it
   with a question, a direct address, a concrete moment, or a number.
 
+## Hedging that protects the writer
+
+The other common complaint is "wishy-washy": copy so qualified that it never commits to
+anything. It usually comes from review language leaking into the material: evidence,
+verification and approval wording that belongs in the review record, and qualifiers that
+protect the writer without informing the reader.
+
+The rule below protects every hedge that is true and would change what the reader does. It
+does not protect review residue. Move the evidence to the review record, state the capability
+plainly, and put a real limit inside the sentence it limits ("on macOS and Linux, …") instead
+of in a separate disclaimer.
+
 ## Address somebody
 
 - **Say "you".** Material that tells a reader what to do should address that reader.
+- **A company account is a team talking.** Write "we", the way the people who built it would
+  say it, not the company name in the third person.
 - **Attributed writing should sound attributed.** Prose published under a person's name and
   written entirely in the impersonal third person reads as documentation wearing a byline.
   Opinion, judgement and preference belong to the named author and are theirs to give.

package/package/corpus/skills/cratis-writing-voice-and-cadence/verification.json

@@ -8,6 +8,10 @@
     { "kind": "skill-contains", "value": "every hedging word" },
     { "kind": "skill-contains", "value": "First person is not a licence to invent" },
     { "kind": "skill-contains", "value": "Structural sameness is the more damaging half" },
-    { "kind": "skill-contains", "value": "Rewrite a tranche, read it, and only then continue" }
+    { "kind": "skill-contains", "value": "Rewrite a tranche, read it, and only then continue" },
+    { "kind": "skill-contains", "value": "Punchline fragment" },
+    { "kind": "skill-contains", "value": "Labeled caveat" },
+    { "kind": "skill-contains", "value": "Hedging that protects the writer" },
+    { "kind": "skill-contains", "value": "A company account is a team talking" }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "3.3.1",
+  "version": "4.0.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [