rsc-universal 0.1.1

package/skills/tauri/scripts/verify.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# verify.sh — read-only static lint for a Tauri v2 project (src-tauri/ tree).
+#
+# Mirrors the SKILL.md anti-patterns so the advice is checkable. It scans the
+# target for the failure modes people actually ship. It is a LINT — no build,
+# no network, no Cargo, deterministic, CI-safe. Read-only: never writes anything.
+#
+# Severity model (per the spec — heuristic + advisory):
+#   WARN  — likely-wrong, advisory. Does NOT fail the run.
+#   FAIL  — a hard structural break (v1 allowlist in a v2 config). Fails the run.
+#
+# Checks:
+#   1. FAIL  legacy v1 `"allowlist"` key in tauri.conf.json (v2 uses capabilities).
+#   2. WARN  src-tauri/ present but no capabilities/*.json — default-deny means zero IPC,
+#            usually a mistake unless the app makes no Rust calls.
+#   3. WARN  a capability lists no permissions (empty/absent "permissions").
+#   4. WARN  a command in generate_handler![...] has no matching #[tauri::command] fn.
+#   5. WARN  a fallible-looking command (read/write/fetch/load/save/delete/open) whose
+#            signature returns no `Result` — likely should return Result<T, E>.
+#   6. WARN  no CSP set anywhere in tauri.conf.json (app.security.csp).
+#
+# Exits 0 on a clean OR empty target, and on WARN-only. Exits 1 only on a FAIL.
+# Usage: verify.sh [TARGET_DIR]   (default ".")
+
+set -uo pipefail
+
+TARGET="${1:-.}"
+fail=0
+warned=0
+
+warn() { printf 'WARN [%s] %s — %s\n' "$1" "$2" "$3" >&2; warned=1; }
+hard() { printf 'FAIL [%s] %s — %s\n' "$1" "$2" "$3" >&2; fail=1; }
+note() { printf '%s\n' "$1"; }
+
+if [ ! -e "$TARGET" ]; then
+  note "verify: target does not exist: $TARGET — nothing to check."
+  exit 0
+fi
+
+# Locate the src-tauri dir (the target may be it, contain it, or be a single file).
+srctauri=""
+if [ -d "$TARGET/src-tauri" ]; then
+  srctauri="$TARGET/src-tauri"
+elif [ -d "$TARGET" ] && [ "$(basename "$TARGET")" = "src-tauri" ]; then
+  srctauri="$TARGET"
+else
+  found=$(find "$TARGET" -type d -name src-tauri -not -path '*/.git/*' 2>/dev/null | head -n1)
+  [ -n "$found" ] && srctauri="$found"
+fi
+
+# --- tauri.conf.json checks (run wherever a conf is found) ---------------------
+conf_files=()
+while IFS= read -r f; do conf_files+=("$f"); done < <(
+  find "$TARGET" -type f -name 'tauri.conf.json' -not -path '*/.git/*' 2>/dev/null
+)
+
+if [ "${#conf_files[@]}" -eq 0 ] && [ -z "$srctauri" ]; then
+  note "verify: no Tauri project found under $TARGET (no src-tauri/, no tauri.conf.json) — nothing to check."
+  exit 0
+fi
+
+for conf in "${conf_files[@]}"; do
+  content=$(tr -d '\r' < "$conf")
+
+  # Rule 1 (FAIL): v1 allowlist key.
+  if printf '%s' "$content" | grep -Eq '"allowlist"[[:space:]]*:'; then
+    ln=$(grep -nE '"allowlist"[[:space:]]*:' "$conf" | head -n1 | cut -d: -f1)
+    hard "v1-allowlist" "$conf:${ln:-?}" 'v1 "allowlist" key in a v2 config — replace with capabilities/*.json'
+  fi
+
+  # Rule 6 (WARN): no CSP.
+  if ! printf '%s' "$content" | grep -Eq '"csp"[[:space:]]*:'; then
+    warn "no-csp" "$conf" 'no app.security.csp set — the WebView runs any loaded script; set a CSP for prod'
+  fi
+done
+
+# --- capabilities checks -------------------------------------------------------
+if [ -n "$srctauri" ]; then
+  capdir="$srctauri/capabilities"
+  cap_files=()
+  if [ -d "$capdir" ]; then
+    while IFS= read -r f; do cap_files+=("$f"); done < <(
+      find "$capdir" -type f -name '*.json' 2>/dev/null
+    )
+  fi
+
+  # Rule 2 (WARN): src-tauri present but no capability files.
+  if [ "${#cap_files[@]}" -eq 0 ]; then
+    warn "no-capabilities" "$srctauri" 'no capabilities/*.json — default-deny means zero IPC access; add a scoped capability'
+  fi
+
+  # Rule 3 (WARN): a capability with no permissions.
+  for cap in ${cap_files[@]+"${cap_files[@]}"}; do
+    capc=$(tr -d '\r' < "$cap")
+    if ! printf '%s' "$capc" | grep -Eq '"permissions"[[:space:]]*:[[:space:]]*\['; then
+      warn "cap-no-perms" "$cap" 'capability has no "permissions" array — it grants nothing (or is malformed)'
+    elif printf '%s' "$capc" | grep -Eq '"permissions"[[:space:]]*:[[:space:]]*\[[[:space:]]*\]'; then
+      warn "cap-no-perms" "$cap" 'capability "permissions" is empty — grants nothing'
+    fi
+  done
+fi
+
+# --- command checks (Rust) -----------------------------------------------------
+if [ -n "$srctauri" ]; then
+  rs_files=()
+  while IFS= read -r f; do rs_files+=("$f"); done < <(
+    find "$srctauri" -type f -name '*.rs' -not -path '*/target/*' 2>/dev/null
+  )
+
+  # Gather the set of #[tauri::command] fn names and their (multi-line) signatures.
+  declared_names=""
+  for rs in ${rs_files[@]+"${rs_files[@]}"}; do
+    # Find lines with the command attribute, then the fn name on a following line.
+    # awk: when we see the attribute, capture the next fn <name>.
+    while IFS= read -r name; do
+      [ -n "$name" ] && declared_names="$declared_names $name"
+    done < <(awk '
+      /#\[tauri::command/ { armed=1; next }
+      armed && /fn[ \t]+[A-Za-z_][A-Za-z0-9_]*/ {
+        match($0, /fn[ \t]+[A-Za-z_][A-Za-z0-9_]*/)
+        s=substr($0, RSTART, RLENGTH); sub(/fn[ \t]+/, "", s); print s; armed=0
+      }
+      armed && NF==0 { next }
+    ' "$rs")
+  done
+
+  # Rule 4 (WARN): names inside generate_handler![...] with no declared command.
+  for rs in ${rs_files[@]+"${rs_files[@]}"}; do
+    # Extract the comma list between generate_handler![ and the closing ].
+    handler=$(tr -d '\r' < "$rs" | tr '\n' ' ' | grep -oE 'generate_handler!\[[^]]*\]' || true)
+    [ -z "$handler" ] && continue
+    inner=$(printf '%s' "$handler" | sed -E 's/.*generate_handler!\[//; s/\].*//')
+    # Split on commas, strip module paths (mod::cmd -> cmd) and whitespace.
+    IFS=',' read -ra regs <<< "$inner"
+    for r in "${regs[@]}"; do
+      r=$(printf '%s' "$r" | tr -d ' \t')
+      r="${r##*::}"
+      [ -z "$r" ] && continue
+      case " $declared_names " in
+        *" $r "*) : ;;
+        *) warn "unregistered-cmd" "$rs" "generate_handler! lists '$r' but no #[tauri::command] fn '$r' was found" ;;
+      esac
+    done
+  done
+
+  # Rule 5 (WARN): fallible-looking command without Result in its signature.
+  for rs in ${rs_files[@]+"${rs_files[@]}"}; do
+    while IFS= read -r nm; do
+      [ -n "$nm" ] && warn "no-result" "$rs" "command '$nm' looks fallible but returns no Result<T, E> — Err should become a rejected JS promise"
+    done < <(awk '
+      /#\[tauri::command/ { armed=1; sig=""; next }
+      armed {
+        sig = sig " " $0
+        if (sig ~ /\{/ || sig ~ /;/) {
+          # signature complete (body brace or decl end)
+          if (match(sig, /fn[ \t]+[A-Za-z_][A-Za-z0-9_]*/)) {
+            nm=substr(sig, RSTART, RLENGTH); sub(/fn[ \t]+/, "", nm)
+            if (nm ~ /^(read|write|fetch|load|save|delete|open|get|put|post)_/ && sig !~ /Result[ \t]*</) {
+              print nm
+            }
+          }
+          armed=0
+        }
+      }
+    ' "$rs")
+  done
+fi
+
+if [ "$fail" -ne 0 ]; then
+  note "verify: Tauri lint FAILED — fix the structural issue(s) above."
+  exit 1
+fi
+if [ "$warned" -ne 0 ]; then
+  note "verify: Tauri lint passed with advisory warnings (review above; not fatal)."
+  exit 0
+fi
+note "verify: Tauri project passes the static lint."
+exit 0

package/skills/technical-writing/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: technical-writing
+description: "Use when writing or fixing user-facing technical docs — a README, a getting-started tutorial, a how-to guide, API/CLI/config reference — and the page tries to teach, explain, and list every parameter at once, a tutorial branches into choose-your-own-adventure, a reference is padded with opinions, a README reads like a sales pitch, code samples are stale or untested, or weasel words (simply, just, easy, seamless) crept in. Triggers: 'write a README for my CLI', 'turn these notes into a step-by-step getting-started guide', 'document this REST endpoint's params and error codes', 'my docs page tries to do everything and confuses people', 'split this into tutorial vs how-to', 'this README reads like a sales pitch', 'add a Vale lint to block simply/just in our /docs', 'escriu un README clar per aquesta llibreria', 'documenta esta API con una guía paso a paso'. NOT an SEO blog article (that is article-writing), and NOT the content calendar or pipeline (that is content-engine)."
+tags: [documentation, technical-writing, diataxis, readme, docs-as-code, developer-docs]
+recommends: [article-writing, content-engine, course-storytelling, translation-l10n, brand-voice, accessibility]
+origin: risco
+---
+
+# Technical writing
+
+You write the document a person reads to *use* a product or codebase: a README, a tutorial, a how-to, API/CLI/config reference. Not marketing prose, not an SEO article, not a course. The craft is mostly one decision made early and held: **what kind of doc does this reader actually need**, then writing that one kind in its correct shape.
+
+The backbone is Diátaxis — four documentation modes, each serving a distinct need (diataxis.fr). The sentence-level rules come from the Google developer documentation style guide (developers.google.com/style). The shipping discipline is docs-as-code: docs live with the code and lint in CI.
+
+## First move: classify the doc
+
+Before you write a line, name the reader's need and pick exactly one mode. Mixing modes in one page is the single biggest reason docs fail readers — the learner gets buried in parameters, the expert wades through a beginner tutorial to find one flag.
+
+| Reader is… | They want… | Mode | Shape |
+|---|---|---|---|
+| Learning, new, hands need holding | To *acquire skill* by doing | **Tutorial** | Linear, runnable, guaranteed to work |
+| Competent, has a specific goal | To *get a task done* now | **How-to** | Goal-titled, ordered steps, no teaching |
+| Working, needs a fact | To *look something up* | **Reference** | Dry, complete, mirrors the product |
+| Curious, wants the "why" | To *understand* | **Explanation** | Discursive, trade-offs, no steps |
+
+**Rule: one page, one mode.** Why: a tutorial answers "how do I start?", reference answers "what are the flags?" — a reader arrives with one question, and a page serving two answers neither well.
+
+If a page already mixes modes, do not patch it — split it. See `references/diataxis-modes.md` for a worked split of one bad page into four.
+
+## Tutorial
+
+A lesson a beginner runs end to end and succeeds. You are the instructor; their success is *your* responsibility, not theirs.
+
+- Title it for the learner's gain: "Build your first X", not "X configuration".
+- State prerequisites and exact versions up top before step 1.
+- Number every step. Each step produces a visible result the reader can check against.
+- It must run start-to-finish on a clean machine. Test it on one.
+- **No branching.** No "if you prefer Y…", no "depending on your setup". One path.
+- **No explanation of why.** A learner doing 12 new things cannot also absorb design rationale. Link the "why" to an explanation page.
+
+Bad → Good opening:
+
+```md
+<!-- Bad: assumes context, branches, explains -->
+Depending on your package manager, install the SDK (we use a monorepo
+because it scales better). Configure your environment as needed.
+
+<!-- Good: one path, concrete, checkable -->
+## Build your first report
+
+You need Python 3.12+ and a free API key from example.com/keys.
+
+1. Install the SDK:
+   ```bash
+   pip install acme-sdk==4.2.0
+   ```
+2. Save your key:
+   ```bash
+   export ACME_KEY="your-key-here"
+   ```
+   Run `echo $ACME_KEY` — you should see your key printed back.
+```
+
+## How-to
+
+A recipe for someone who already knows the product and has a real goal right now.
+
+- Title it as the goal: **"How to rotate an API key"**, not "API keys".
+- Assume competence. Do not re-teach concepts; link to reference/explanation instead.
+- Ordered steps, but the reader may adapt — state the goal so they can.
+- Address one real-world task. "How to configure logging" is reference; "How to ship logs to Datadog" is a how-to.
+- No tutorial hand-holding, no narrative.
+
+Bad → Good:
+
+```md
+<!-- Bad: teaches, no clear goal in the title -->
+## Logging
+Logging is important. A logger has levels: DEBUG, INFO… Here is how
+levels work, and then some setup.
+
+<!-- Good: goal title, competent reader, straight to it -->
+## How to send logs to Datadog
+1. Set `LOG_SINK=datadog` and `DD_API_KEY` in the environment.
+2. Restart the worker: `acme worker restart`.
+3. Confirm delivery in Datadog → Logs within ~1 min.
+```
+
+## Reference
+
+The technical facts, structured to mirror the product. The reader is not reading top to bottom — they are scanning for one entry.
+
+- Dry, complete, consistent. Same structure for every entry.
+- Structure follows the code: one section per command, endpoint, or config key.
+- Use tables for parameters, flags, return values, and errors.
+- **No opinions, no recommendations, no "you should".** Reference states what *is*. Move "which one to pick" to a how-to or explanation.
+- Document every parameter, including defaults and required/optional.
+
+```md
+### `GET /reports/{id}`
+
+| Param | In | Type | Required | Description |
+|---|---|---|---|---|
+| `id` | path | string (uuid) | yes | Report identifier. |
+| `fields` | query | string | no | Comma-separated fields to return. Default: all. |
+
+**Responses**
+
+| Status | Meaning |
+|---|---|
+| `200` | Report returned. |
+| `404` | No report with that `id`. |
+| `429` | Rate limit exceeded; retry after `Retry-After` seconds. |
+```
+
+## Explanation
+
+Background and the "why" — context, design decisions, trade-offs, alternatives considered.
+
+- Discursive prose, free to make connections and admit nuance.
+- **Never numbered steps.** If you are writing "1. … 2. …", it is a tutorial or how-to, not an explanation.
+- Free to hold an opinion and explain the reasoning — this is the *only* mode where opinion belongs.
+- Title with "About…", "Why…", or a concept name. Read at leisure, not while doing.
+
+## README recipe
+
+The one doc everyone gets wrong by turning it into a pitch. A README lives in the top-level directory, orients a *new* reader, and at minimum says what the thing is, what it is for, and links to fuller docs (Google docguide).
+
+Skeleton, in order: **what + why (two lines) → install → one minimal runnable example → link to deeper docs → status/license.**
+
+Bad → Good opening lines:
+
+```md
+<!-- Bad: a sales page -->
+# Acme SDK 🚀
+The most powerful, blazing-fast, developer-friendly toolkit to
+effortlessly supercharge your data workflows!
+
+<!-- Good: what it is, what it's for, in two lines -->
+# Acme SDK
+A Python client for the Acme reporting API. Fetch, filter, and export
+reports without writing HTTP by hand.
+
+## Install
+```bash
+pip install acme-sdk==4.2.0
+```
+```
+
+## Sentence-level rules
+
+Apply these to every mode. Each ships clearer prose at no cost.
+
+| Rule | Why | Bad → Good |
+|---|---|---|
+| Second person, imperative steps | The reader is *doing* this | "The user should run…" → "Run…" |
+| Active voice | Names who acts | "The file is created by the script" → "The script creates the file" |
+| Present tense | Docs describe how it works now | "This will return a list" → "This returns a list" |
+| Define before use | No forward references | Spell out a term the first time, then use it |
+| One idea per sentence | Scannable, translatable | Split the 40-word sentence into two |
+| Cut "in order to" | It is always just "to" | "in order to deploy" → "to deploy" |
+| Ban weasel/AI-tell words | They lie about difficulty and add nothing | "simply run X" → "run X" |
+
+Banned words: **simply, just, easy, effortless, seamless, robust, powerful, leverage, utilize, in order to, blazing-fast, supercharge**. If a step is "simple", the reader either already knows it (delete the word) or does not (the word mocks them). Full banlist with replacements is in `references/diataxis-modes.md`.
+
+## Code examples
+
+- Minimal: the fewest lines that work. Cut every line not required to run.
+- Runnable and **tested** — copy-paste it onto a clean machine and confirm. Untested samples rot and misinform.
+- Language-tag every fence (`bash`, `python`, `json`, `yaml`, `ini`).
+- Show expected output so the reader knows they succeeded.
+- No `...` standing in for required lines. Elide only genuinely irrelevant detail, and say so.
+
+```python
+# Good: minimal, runnable, shows what comes back
+from acme import Client
+
+client = Client(api_key="your-key")
+report = client.reports.get("3f9a-...")
+print(report.title)
+# -> "Q2 revenue"
+```
+
+## Docs-as-code
+
+Treat docs like code, or they go stale and mislead.
+
+- **Change docs in the same PR as the code they describe.** Dead docs are worse than no docs — they actively misinform and slow developers (Google docguide best practices).
+- Lint prose in CI. **Vale** is the de-facto open-source prose linter: config in `.vale.ini` at the repo root, custom rules in a styles dir, run as a **blocking check** on every PR touching Markdown. Common rules ban "simply/just/easy" and enforce "sign in" over "log in". Used in production by GitLab, Datadog, and ING.
+- Test samples and check links in CI (writethedocs.org). A broken `pip install` line in a tutorial breaks every reader.
+
+A starter `.vale.ini`, a custom banned-terms style, and a GitHub Actions blocking job are in `references/vale-starter.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| One page teaches + explains + lists params | Serves no reader well; all three are diluted | Split by mode (classify table above) |
+| Tutorial that branches ("if you prefer…") | Beginner cannot judge the choice; loses the path | One guaranteed path; defer choices to a how-to |
+| How-to that teaches concepts | Wastes the competent reader's time | Link to reference/explanation; just give steps |
+| Reference with opinions ("we recommend…") | Pollutes a lookup with judgement | Move recommendations to how-to/explanation |
+| README as a sales page | New reader still does not know what it *is* | What/why in two lines, then install + example |
+| Untested or `...`-gapped code samples | They rot; reader copies a broken command | Test on a clean machine; show expected output |
+| Weasel words (simply, just, seamless) | Lie about difficulty, add zero information | Delete the word; the imperative stands alone |
+| Wall of text, no headings or steps | Unscannable; reader cannot find their answer | Short sentences, one idea each, real headings |
+
+## Before you ship
+
+- [ ] Page is exactly **one** Diátaxis mode (tutorial / how-to / reference / explanation).
+- [ ] Prerequisites and versions are stated before step 1 (tutorial/how-to).
+- [ ] Every code sample runs on a clean machine and shows expected output.
+- [ ] No `...` hides a line the reader needs.
+- [ ] Banlist is clean (`scripts/verify.sh path/to/doc.md`).
+- [ ] All links resolve.
+- [ ] README says what it is + what it's for + links to deeper docs.
+- [ ] Doc changed in the same PR as the code it documents.
+
+## References
+
+- `references/diataxis-modes.md` — per-mode templates, a worked split of one mixed page into four, and the full weasel-word/AI-tell banlist with replacements.
+- `references/vale-starter.md` — starter `.vale.ini`, a custom banned-terms Vale style, and a GitHub Actions job running Vale as a blocking check.
+
+## Siblings
+
+- SEO blog post / long-form article with schema and FAQ → `../article-writing/SKILL.md`.
+- Editorial calendar, pillars, content pipeline → `../content-engine/SKILL.md`.
+- Teaching a syllabus over time with narrative → `../course-storytelling/SKILL.md`.
+- Brand tone and voice rules → `../brand-voice/SKILL.md`.
+- Making docs and samples accessible → `../accessibility/SKILL.md`.
+- Localizing finished docs into another language → translation-l10n.

package/skills/technical-writing/evals/README.md

@@ -0,0 +1,12 @@
+# Evals — technical-writing
+
+`cases.yaml` is read by the repo's skill-eval harness. The `should_trigger` and
+`should_not_trigger` blocks gauge routing: each `should_trigger` prompt must load
+this skill, and each `should_not_trigger` prompt must route to the named sibling
+instead — these catch over- and under-triggering against article-writing,
+content-engine, translation-l10n, course-storytelling, and brand-voice. The
+`capability` block is graded by a model judge against its `must_include` rubric:
+the agent is handed the mixed-page scenario and its output is checked for the
+Diátaxis split, the rewritten reference table, the removed weasel words, runnable
+samples, and the Vale/CI recommendation. Run it with the repo's eval runner over
+this directory; there is no separate setup beyond a checkout of the skill.

package/skills/technical-writing/evals/cases.yaml

@@ -0,0 +1,53 @@
+skill: technical-writing
+
+# Prompts that MUST load technical-writing. The skill owns the user-facing
+# DOCUMENT — README, tutorial, how-to, reference — and the discipline of
+# writing each in its correct Diátaxis mode. Not topic strategy, not the
+# calendar, not localization, not pedagogy.
+should_trigger:
+  - prompt: "Write a README for my Python CLI tool."
+    why: "Core job — the README is the one doc everyone gets wrong; squarely in scope."
+  - prompt: "My docs page teaches, explains, and lists every parameter at once — readers are lost."
+    why: "Non-obvious: no doc-type word, but it is the signature mode-mixing failure the skill exists to fix."
+  - prompt: "Turn these notes into a step-by-step getting-started guide a beginner can run end to end."
+    why: "Tutorial mode — linear, runnable, guaranteed success."
+  - prompt: "Document this REST endpoint's parameters, responses, and error codes."
+    why: "Reference mode — dry, complete, table-structured."
+  - prompt: "Split this page into a tutorial vs a how-to — right now it's one confusing blob."
+    why: "Non-obvious: the request is a Diátaxis split, the core decision this skill makes."
+  - prompt: "Add a Vale lint to block 'simply' and 'just' in our /docs on every PR."
+    why: "Docs-as-code: prose linting in CI is owned here, framed as tooling not writing."
+  - prompt: "escriu un README clar per aquesta llibreria"
+    why: "Catalan trigger for the core README job."
+  - prompt: "documenta esta API con una guía paso a paso"
+    why: "Spanish trigger — documenting an API as a step-by-step guide (tutorial/how-to)."
+
+# Prompts that must NOT load technical-writing — each routes to a real sibling.
+should_not_trigger:
+  - prompt: "Write a 1500-word SEO blog post about vector databases with FAQ schema."
+    route_to: article-writing
+    why: "Search-intent prose plus on-page schema, not a product/codebase doc."
+  - prompt: "Build our content calendar and topic pillars for Q3."
+    route_to: content-engine
+    why: "The system and calendar across many pieces, not one document."
+  - prompt: "Translate our existing English docs into Spanish."
+    route_to: translation-l10n
+    why: "Localization of already-written docs, not authoring the source doc."
+  - prompt: "Design a 6-week course curriculum on Kubernetes with lessons and slides."
+    route_to: course-storytelling
+    why: "Syllabus and pedagogy over time, not one runnable doc."
+  - prompt: "Define our brand tone of voice and a reusable style spec."
+    route_to: brand-voice
+    why: "The voice rules a doc is written in, not the doc itself."
+
+# Capability: can the skill actually restructure a mixed page and clean the prose?
+capability:
+  - scenario: "Given a single docs page that opens with a beginner tutorial intro, then drifts into an opinionated explanation of why the architecture is async, then dumps a parameter list — restructure it correctly."
+    must_include:
+      - "Classifies the page's content into the four Diátaxis modes (tutorial, how-to, reference, explanation)."
+      - "Proposes splitting it into separate pages, one mode per page — not patching one page."
+      - "Rewrites at least one mode in its correct shape (e.g. a dry reference table for the parameters, with required/default columns)."
+      - "Removes weasel/AI-tell words (simply, just, easy, seamless) and explains why."
+      - "Ensures code samples are minimal, runnable, and show expected output, with no hidden '...' lines."
+      - "Recommends a Vale-in-CI blocking gate (or the verify.sh banlist) so docs cannot regress."
+      - "States that the README must say what the thing is and what it's for, and link to the fuller docs."

package/skills/technical-writing/references/diataxis-modes.md

@@ -0,0 +1,131 @@
+# Diátaxis modes — templates, a worked split, and the banlist
+
+The four modes (diataxis.fr/start-here, accessed 2026-06-02) each answer a
+different reader question. Use this file when SKILL.md's classify table is not
+enough — you have a real mixed page to break apart, or you need a full template.
+
+## Per-mode templates
+
+### Tutorial template
+
+```md
+# Build your first <thing>
+
+By the end you will have <concrete outcome>.
+
+## Before you start
+- <tool> <exact version>
+- <account/key> from <url>
+
+## 1. <first action>
+<command>
+You should see: <visible result>
+
+## 2. <next action>
+...
+
+## What you built
+<one paragraph recap>. Next: <link to a how-to or explanation>.
+```
+
+Rules: linear, runnable on a clean machine, no branching, no rationale. If you
+catch yourself writing "you could also", stop — that belongs in a how-to.
+
+### How-to template
+
+```md
+# How to <achieve a specific goal>
+
+Assumes you already <competence assumption>.
+
+1. <step>
+2. <step>
+3. <step>
+
+Done when: <observable success condition>.
+```
+
+Rules: goal in the title, competent reader, no concept teaching. Link out for
+"what is X" rather than explaining inline.
+
+### Reference template
+
+```md
+# <component / endpoint / command>
+
+<one-line factual description>
+
+## Parameters
+| Name | Type | Required | Default | Description |
+|---|---|---|---|---|
+
+## Returns
+| Field | Type | Description |
+|---|---|---|
+
+## Errors
+| Code | Meaning |
+|---|---|
+```
+
+Rules: dry, complete, consistent across entries, structured like the product,
+zero opinions.
+
+### Explanation template
+
+```md
+# About <concept> / Why <decision>
+
+<context: what problem this addresses>
+<the approach and the trade-off>
+<alternatives considered and why this one>
+```
+
+Rules: prose, never numbered steps, opinion allowed *with* reasoning.
+
+## Worked split: one mixed page into four
+
+A page titled "Logging" tries to do everything:
+
+> Logging helps you debug. Logging is asynchronous in Acme because blocking
+> the request path would hurt latency. To set it up, run `acme init logging`,
+> then set `LOG_LEVEL`. The logger accepts levels DEBUG, INFO, WARN, ERROR
+> and a `sink` of `stdout|file|datadog`. We recommend `datadog` in production.
+
+That single page mixes all four modes. Split it:
+
+| Original sentence | Belongs in |
+|---|---|
+| "Logging helps you debug." | Cut — filler. |
+| "Logging is asynchronous because blocking the request path would hurt latency." | **Explanation**: *Why Acme logs asynchronously* |
+| "Run `acme init logging`, then set `LOG_LEVEL`." | **Tutorial** step *or* a **how-to** "How to enable logging" |
+| "Levels: DEBUG…ERROR; `sink`: stdout/file/datadog." | **Reference**: the `logging` config table |
+| "We recommend `datadog` in production." | **How-to** "How to ship logs to Datadog" (the opinion lives in the recipe's intro, not in reference) |
+
+Result: four short pages, each scannable, each answering one question — instead
+of one page answering none well.
+
+## Weasel-word & AI-tell banlist
+
+These words lie about difficulty, inflate, or signal machine-generated filler.
+Delete or replace. This list is the source of truth for `scripts/verify.sh`.
+
+| Banned | Why | Replace with |
+|---|---|---|
+| simply | Mocks the reader who is stuck | (delete) |
+| just | Same — minimizes real effort | (delete) |
+| easy / easily | Difficulty is the reader's to judge | (delete) |
+| effortless / effortlessly | Marketing claim, unverifiable | (delete) |
+| seamless / seamlessly | Means nothing concrete | name the actual behavior |
+| robust | Vague reassurance | state the guarantee (e.g. "retries 3×") |
+| powerful | Empty superlative | show what it does |
+| blazing-fast / lightning-fast | Hype | give a number ("p50 12 ms") |
+| supercharge | Marketing | describe the actual benefit |
+| leverage | Jargon for "use" | use |
+| utilize | Jargon for "use" | use |
+| in order to | Always longer than needed | to |
+| please (in steps) | Steps are imperatives | (delete) |
+| log in / login (verb) | Style-guide preference | sign in |
+
+When a step feels like it needs "simply", that is a signal the step is either
+obvious (delete the word) or genuinely hard (add the missing detail instead).