@cratis/pi 2.29.0 → 2.30.0

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

@@ -0,0 +1,93 @@
+---
+name: cratis-social-feed-post
+description: Write or review a short post for a social feed such as LinkedIn, where the opening has to survive the feed's truncation, the body is plain text with no markup, and the common formatting tricks cost accessibility and reach. Use when drafting, adapting or reviewing a feed post. Do not use for documentation pages, release notes, long-form articles, or anything rendered as Markdown.
+license: MIT
+---
+
+# Social feed post
+
+A feed post is not a short article. The feed shows a few lines and hides the rest behind a
+"see more" control, so the opening is not an introduction to the point — it is the entire
+advertisement for the post, and the decision to expand is itself a ranking signal.
+
+Everything below assumes a plain-text feed with no markup rendering. The character and line
+figures are unofficial approximations reported by third parties; no platform documents them,
+and they move with interface, font size and device width. Treat them as a target zone and
+re-check them against current official guidance rather than encoding them as durable rules.
+
+## The fold decides what the post is judged on
+
+On LinkedIn the cut is modelled two ways at once and lands on whichever runs out first:
+
+- a character budget of roughly 210 on desktop and 140 on mobile, and
+- a budget of about three rendered lines.
+
+**A blank line spends the line budget without spending characters.** A short opening on its
+own line is therefore cut *earlier* than the same words inside a paragraph. Putting the hook
+on its own line is usually still right, because it is what a scroller reads first, but it is
+a trade rather than a free improvement.
+
+## What the opening must do
+
+- **Finish a complete thought above the cut.** An opening severed mid-sentence has spent the
+  whole advertisement on half an idea.
+- **Stay short on purpose.** A brief opening sentence is a hook doing its job. Do not rewrite
+  one into a longer, smoother sentence for the sake of rhythm; that removes the
+  advertisement. This is the most common way a well-meaning editing pass makes a post worse.
+- **Earn the identifier before using it.** An opening that begins with a framework type or a
+  product name asks a scroller to care about a word they have no reason to recognize yet.
+  Name the friction first, then the mechanism.
+- **Skip the throat-clearing.** The first line is the point, not a preamble to it.
+
+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.
+
+## Never use Unicode pseudo-formatting
+
+Third-party tools offer pseudo-bold and pseudo-italic built from Mathematical Alphanumeric
+Symbols — the characters that look like `𝗕𝗼𝗹𝗱` and `𝘐𝘵𝘢𝘭𝘪𝘤`. Do not use them.
+
+- **Assistive technology cannot read them.** A screen-reader user hears "mathematical bold
+  capital T, mathematical bold small h" through an entire line, or hears nothing at all.
+- **They are not the letters they resemble.** Platform search and ranking index the actual
+  code points, so a styled keyword is no longer that keyword and the term is lost.
+
+Emphasis in a plain-text feed comes from sentence construction, line placement and what is
+said first. A point that needs visual weight belongs in an image with its own alt text.
+
+## Two things that cost reach outright
+
+- **No external link in the body.** Current ranking suppresses posts that carry one; the
+  convention is to put the link in a comment. Verify this at review rather than repeating it
+  as folklore, and never write the convention into the copy itself.
+- **No engagement bait.** "Repost if…", "Tag someone who…", "Agree?" are treated as spam
+  signals rather than as engagement. A genuinely answerable question that follows from the
+  argument is a different thing and is welcome.
+
+## Structure that survives a phone
+
+- One idea per post. A feed reader will not assemble two.
+- 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.
+- Blank lines separate paragraphs and nothing else. Each one costs line budget above the fold.
+- No Markdown. The feed renders none of it, so `**bold**` and `# heading` reach the reader
+  as literal characters.
+- Hashtags on the last line only, never mid-sentence.
+- Every image needs alt text. A post whose point lives only in an unlabeled image has no
+  point for part of its audience.
+
+## Before publishing
+
+- The opening thought is complete above the fold on mobile as well as desktop.
+- No pseudo-formatted characters anywhere, including the hook.
+- No link in the body and no engagement bait in the close.
+- Every image carries alt text, and the post still makes sense with the images removed.
+- Every technical claim is one the underlying source actually supports, and any limitation
+  the post depends on is stated rather than implied.
+
+## Stop conditions
+
+Stop and ask when the account owner, the author's perspective, the evidence behind a claim,
+or an asset's permission is unresolved. Drafting a post is not authorization to publish,
+schedule, tag, mention or upload it.

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

@@ -0,0 +1,14 @@
+{
+  "skill": "cratis-social-feed-post",
+  "input": "Draft a LinkedIn post about a framework feature and format it for the feed.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "A blank line spends the line budget without spending characters" },
+    { "kind": "skill-contains", "value": "Never use Unicode pseudo-formatting" },
+    { "kind": "skill-contains", "value": "Assistive technology cannot read them" },
+    { "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" }
+  ]
+}

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

@@ -0,0 +1,99 @@
+---
+name: cratis-writing-voice-and-cadence
+description: Find and remove the sentence constructions and structural sameness that make written material read as machine-generated, across documentation, release notes, pull request descriptions, posts and reviews, without changing any technical claim. Use when reviewing or rewriting existing prose for voice. Do not use for technical accuracy review, for original drafting, or as a reason to touch approved copy without authorization.
+license: MIT
+---
+
+# Writing voice and cadence
+
+Material that is factually correct can still be unreadable in a way nobody can name. The
+usual diagnosis is "it sounds like AI wrote it", and the usual response is to rewrite by feel,
+which produces a second machine voice rather than a human one.
+
+The failure is measurable, and it has two halves. The smaller half is a set of sentence
+constructions used far past the density a person would use them. The larger half is
+structural sameness across a whole body of material: a reader meeting the second piece
+recognizes the format before reading a word of it.
+
+## The constructions
+
+None of these is wrong. One of any of them is a good sentence. What turns them into a tell is
+recurrence.
+
+| Construction | What it looks like |
+| --- | --- |
+| **Corrective tail** | "…, not a fresh count." The sentence ends by correcting itself |
+| **Balanced semicolon** | Two clauses of equal weight either side of a semicolon |
+| **"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 |
+
+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
+directory and turns an argument about taste into a number. Reading a draft aloud catches all
+of them faster than any tool.
+
+## Structural sameness is the more damaging half
+
+Look at ten pieces together, not one at a time:
+
+- **Every piece the same length and shape.** If most of them are three or four paragraphs
+  with the same paragraph weights, that is a template.
+  The fix for a template is not a better template.
+  Do not adopt a target shape: vary the paragraph count, and let paragraphs differ visibly
+  in weight.
+- **Every sentence the same length.** When sentence length barely varies within a piece, the
+  result is a monotone regardless of the words. Let it swing between four words and twenty-five.
+- **Every piece opening the same way.** An abstract noun phrase making a declarative
+  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.
+
+## Address somebody
+
+- **Say "you".** Material that tells a reader what to do should address that reader.
+- **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.
+- **First person is not a licence to invent.** Opinion is allowed; invented experience,
+  anecdotes that did not happen, and claimed observations the author did not make are not.
+  Where a named author owns the material, it stays blocked until that author reviews it.
+- **A question is allowed when the piece has earned it.** A question that follows from the
+  argument is not bait; one bolted on to harvest a response is.
+
+## Never trade a claim for a smoother sentence
+
+This is the part that makes a voice pass dangerous, and it is the reason to do one carefully
+rather than quickly.
+
+The risk is not an obvious rewrite. It is a hedge dissolving into nicer phrasing. "There is
+no need to" becomes "without needing to", and a limit quietly widens. "Not its meaning"
+becomes "and leaves its meaning alone", and a distinction softens. Both read better. Both
+changed what the text asserts.
+
+Before accepting any rewrite, confirm that:
+
+- every identifier and every number present before is still present, and none was invented;
+- every hedging word — not, never, only, may, unless, until — survives in substance;
+- every stated limitation survives, including one that reads as an awkward caveat, because it
+  is a caveat and it is deliberate;
+- the closing limitation or evidence statement is not thinned, relocated into a subordinate
+  clause, or dropped because it spoiled the ending.
+
+A mechanical check over identifiers, numbers and hedge counts catches most of this before a
+human reads a word, and is worth writing once for any corpus large enough to need a pass.
+
+## Work in tranches that can be read
+
+Rewriting is not a batch operation. Any body of material large enough to have a detectable
+voice is too large to rewrite in one pass with judgement, and a fast pass replaces one
+detectable format with another. Rewrite a tranche, read it, and only then continue.
+
+Where material carries a recorded approval, a rewrite invalidates it. Recording a fresh
+approval over copy nobody has read makes the record assert something false, after which every
+downstream check agrees with it. Size the tranche to what its owner will actually read.
+
+## Stop conditions
+
+Stop when a rewrite would change what the material claims, when the named author has not
+accepted a perspective being introduced on their behalf, or when the material is under an
+approval that the rewrite would invalidate without authorization to refresh it.

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

@@ -0,0 +1,13 @@
+{
+  "skill": "cratis-writing-voice-and-cadence",
+  "input": "This documentation reads like it was generated. Make it sound human without changing what it says.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "Never trade a claim for a smoother sentence" },
+    { "kind": "skill-contains", "value": "The fix for a template is not a better template" },
+    { "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" }
+  ]
+}

package/package/profile-catalog.json

@@ -43,6 +43,7 @@
         "cratis/cli",
         "cratis/cli/terminal-workbench",
         "cratis/components",
+        "cratis/content",
         "cratis/documentation",
         "cratis/full",
         "cratis/full/csharp",
@@ -559,10 +560,22 @@
         "typescript"
       ]
     },
+    {
+      "id": "cratis/content",
+      "availableTargets": [
+        "cratis-social-feed-post",
+        "cratis-writing-voice-and-cadence"
+      ],
+      "languages": [
+        "markdown",
+        "language-agnostic"
+      ]
+    },
     {
       "id": "cratis/documentation",
       "availableTargets": [
-        "cratis-documentation-writing"
+        "cratis-documentation-writing",
+        "cratis-writing-voice-and-cadence"
       ],
       "languages": [
         "markdown",

package/package.json

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