@rubytech/create-sitedesk-code 0.1.340

package/payload/platform/plugins/admin/skills/investigate/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: investigate
+description: |
+  Systematic debugging with root cause investigation. Iron Laws: no fix
+  without root cause, no diagnosis without evidence, investigation
+  produces a task — not a fix. Use when asked to "debug this", "fix this
+  bug", "why is this broken", "investigate this error", or "root cause".
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+  - WebSearch
+---
+
+# Systematic Debugging
+
+Invoked by the admin agent directly.
+
+## Iron Laws
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
+Fixing symptoms creates whack-a-mole debugging. Every fix that doesn't
+address root cause makes the next bug harder to find.
+
+**NO DIAGNOSIS WITHOUT EVIDENCE. NO GUESSING.**
+100% of the diagnosis must be grounded in observable evidence — log
+output, error messages, stack traces, reproduction results, or code-path
+tracing. Inconclusive evidence is not a mystery; it is an **observability
+failure**. Fix the observability gap first, reproduce with proper
+instrumentation, then resume.
+
+**INVESTIGATION PRODUCES A TASK, NOT A FIX.**
+The default output is a task entry describing the root cause, the fix,
+its verification strategy, and its observability requirements. Do not
+implement fixes directly unless the user explicitly asks.
+
+`Edit` is in `allowed-tools` only for the temporary instrumentation in
+Phase 3 step 1. Investigation does not write source files; the
+deliverable is a task entry, written through the resolved task surface.
+
+---
+
+## Step 0: Evidence First — prerequisites before any reasoning
+
+**Do this before resolving the task surface, searching prior work,
+reading code, or forming any hypothesis.** The failure mode this guards
+against is forming a hypothesis from the conversation context — the
+error text the user pasted, what you assume the code does — and then
+treating evidence retrieval as redundant. By the time you have read the
+rest of this skill you have already started doing it. Stop.
+
+First action in this skill: create a TodoWrite list of the
+prerequisites below. Work through them in order. Do not read code, do
+not search prior tasks, do not propose a cause while any prerequisite
+is still open.
+
+1. **Retrieve the requested evidence.** When the user provides a
+   specific artifact — a session key, log reference, error excerpt, or
+   pointer to a particular event — that artifact is the primary
+   evidence. Retrieve it with the canonical log-retrieval tool for the
+   surface (e.g. `logs-read` for Pi sessions on deployed maxy). If a
+   retrieval hook injects an exact command, execute it as given; do not
+   improvise.
+
+   This todo may not be marked complete until the **actual retrieved
+   output appears in the transcript** — the real log lines, not a
+   summary, not a paraphrase, not "the logs confirm X." If you cannot
+   produce the output, the todo stays open and that itself is the
+   finding: an observability or retrieval gap (see Phase 1 step 6).
+
+2. **If no specific artifact was provided**, mark item 1 N/A and
+   proceed to Phase 1 — but state explicitly that no evidence artifact
+   was supplied, so the investigation starts from code-path tracing.
+
+---
+
+## Task surface (where tasks live in this environment)
+
+Before searching prior work or writing the deliverable, resolve where
+tasks live in the current install. Check in this order; use the first
+one that exists:
+
+1. **Graph tasks (deployed maxy).** If the `work-*` MCP tools are
+   available (`work-list`, `work-get` for prior-work search; `work-create`
+   to write the deliverable — they persist `:Task` nodes in Neo4j), tasks
+   live in the graph. Use those tools. (The plugin is `work`, not `tasks` —
+   renamed to avoid colliding with Claude Code's built-in `Task*` family.)
+2. **Local `.tasks/` directory.** If the repo has a `.tasks/` directory
+   (optionally with `archive/`, `in-progress/`, `parked/`, `backlog/`
+   subdirs and a `LANES.md`), tasks live on disk as
+   `.tasks/NNN-<slug>.md`.
+3. **Neither.** State this explicitly: "No task surface detected — this
+   install has no `work-*` graph tools and no `.tasks/` directory. The
+   deliverable will be a written report only."
+
+Throughout this skill, "search prior tasks", "cite prior work", and
+"write a task" mean: use the resolved surface. Do not invent a new
+location.
+
+## Phase 1: Root Cause Investigation
+
+1. **Check prior work.** Search the task surface (graph or `.tasks/`)
+   for tasks related to the affected area — by component, filename, or
+   symptom keywords. Read any matches. Prior tasks carry root cause
+   analyses, evidence, scope boundaries, and observability findings.
+
+   What to look for:
+   - Same root cause already identified — fix may be in progress or
+     parked. Do not re-investigate.
+   - Related symptoms in the same area — recurring bugs are an
+     architectural smell, not coincidence.
+   - Prior observability findings — earlier gaps may still be open,
+     which explains sparse evidence now.
+   - Scope boundaries from related tasks — what was deferred may be
+     exactly what's failing.
+
+   Cite prior work:
+   ```
+   PRIOR WORK: <task id> — <title>
+   RELEVANCE: [same root cause | same area | related symptom]
+   STATUS: [open | archived | parked — and whether findings still apply]
+   ```
+
+   If no prior work is found, note it explicitly — that itself is
+   context.
+
+2. **Collect symptoms.** Read error messages, stack traces, reproduction
+   steps. If context is missing, ask ONE question at a time via
+   AskUserQuestion.
+
+3. **Read the code.** Trace the code path from symptom back to potential
+   causes. Grep for references, Read to understand logic.
+
+4. **Check recent changes.**
+   ```bash
+   git log --oneline -20 -- <affected-files>
+   ```
+   A regression means the root cause is in the diff.
+
+5. **Reproduce.** Can you trigger the bug deterministically? If not,
+   gather more evidence before proceeding.
+
+6. **Assess observability.** Can the logs, error messages, and metrics
+   answer "what happened and why?" If not, this is the first problem to
+   solve. Flag the gap:
+   ```
+   OBSERVABILITY GAP: [what evidence is missing and why it matters]
+   INSTRUMENTATION NEEDED: [what would make the cause visible]
+   ```
+   If the gap is significant, **stop the investigation** and write a
+   task for the observability fix. Resume after instrumentation is
+   deployed and the issue is reproduced with proper evidence.
+
+   **Test for the no-event blind spot explicitly.** Transition-only
+   logging (a line per action) is structurally blind to any failure that
+   emits *no event and does not reproduce on demand* — a leak, an
+   orphan, a stuck or idle resource, a silently-failed cleanup, slow
+   drift. There is no action to hang a log on, and re-running the code
+   will not surface it. For **every failure mode you can name**, ask the
+   forcing question: *"what signal reveals it, without reproducing the
+   failure and without waiting for unrelated future activity?"* If the
+   answer is "none until something else happens," the missing
+   instrumentation is a **standing check — an independent periodic audit
+   that reconciles expected state against actual** — not another action
+   log, and that gap is itself the finding. Verify post-conditions,
+   never log intentions: "called the cleanup" is not evidence the
+   resource was freed.
+
+Output: **"Root cause hypothesis: ..."** — a specific, testable claim
+supported by cited evidence, plus the narrowest module the fix would
+touch (informational; investigation does not edit source).
+
+---
+
+## Phase 2: Pattern Analysis
+
+| Pattern | Signature | Where to look |
+|---------|-----------|---------------|
+| Race condition | Intermittent, timing-dependent | Concurrent access to shared state |
+| Nil/null propagation | NoMethodError, TypeError | Missing guards on optional values |
+| State corruption | Inconsistent data, partial updates | Transactions, callbacks, hooks |
+| Integration failure | Timeout, unexpected response | External API calls, service boundaries |
+| Configuration drift | Works locally, fails in staging/prod | Env vars, feature flags, DB state |
+| Stale cache | Shows old data, fixes on cache clear | Redis, CDN, browser cache |
+
+Also check:
+- Prior tasks (graph or `.tasks/archive/`) in the same area — recurring
+  bugs in the same files are an architectural smell.
+- `git log` for prior fixes in the same area.
+
+**External pattern search.** If no known pattern matches, WebSearch
+for "{framework} {generic error type}" or "{library} {component} known
+issues". **Sanitize first** — strip hostnames, IPs, file paths, SQL,
+customer data. Search the error category, not the raw message. If
+WebSearch is unavailable, skip and proceed.
+
+---
+
+## Phase 3: Hypothesis Testing
+
+1. **Confirm the hypothesis.** Add a temporary log/assertion/debug
+   output at the suspected root cause (this is the one Edit
+   investigation makes; remove it before delivering findings). Run the
+   reproduction. Does the evidence match?
+
+2. **If the hypothesis is wrong.** Sanitize and search the generic
+   error (or skip if WebSearch unavailable), then return to Phase 1.
+   Gather more evidence. Do not guess.
+
+3. **3-strike rule.** If 3 hypotheses fail, **STOP**. Three failed
+   hypotheses almost always means insufficient observability —
+   guessing, not investigating. Use AskUserQuestion:
+   ```
+   3 hypotheses tested, none confirmed by evidence. This is most likely
+   an observability failure.
+
+   OBSERVABILITY GAP: [what evidence is missing]
+
+   A) Fix observability first — add instrumentation, reproduce, then
+      resume investigation (RECOMMENDED)
+   B) Continue investigating — new hypothesis with supporting
+      evidence: [describe the evidence, not just the guess]
+   C) Escalate for human review — needs domain knowledge I don't have
+   ```
+   Option A is almost always correct. B requires citing specific
+   evidence, not speculation.
+
+**Red flags** — slow down if you see:
+- "Quick fix for now" — there is no "for now."
+- Proposing a fix before tracing data flow — guessing.
+- Each fix reveals a new problem elsewhere — wrong layer.
+- "I think it's probably X" — you have an observability gap.
+- Jumping to implementation without asking — investigation produces
+  findings, not fixes.
+- "The logs don't show anything useful" — that IS the finding.
+
+---
+
+## Phase 4: Deliver Findings
+
+Once root cause is confirmed with evidence, the **default output is a
+task entry on the resolved surface** — not a code fix.
+
+```
+ROOT CAUSE CONFIRMED: [one-line summary with evidence citation]
+Evidence: [log output, reproduction result, code trace]
+
+A) Create a task on the resolved surface (graph: work-create;
+   .tasks/: write .tasks/<N>-<slug>.md) with root cause, fix scope,
+   verification strategy, and observability requirements (RECOMMENDED)
+B) Fix it now — implement the fix in this session
+   (only if the user explicitly asked for a fix)
+C) Just the report — document findings, no task, no fix
+```
+
+A is the default. B requires explicit user approval. If no task surface
+exists, A degenerates into C.
+
+### If the user chooses B
+
+Investigation is over; this is surgery. Scope discipline is the sprint
+skill's problem from here.
+
+1. Fix the root cause, not the symptom — smallest change that
+   eliminates the actual problem.
+2. Minimal diff — fewest files, fewest lines.
+3. Regression test that **fails without** the fix and **passes with**
+   it.
+4. Run the full test suite. Paste the output. No regressions.
+5. If the fix touches >5 files, AskUserQuestion on blast radius:
+   ```
+   Fix touches N files — large blast radius for a bug fix.
+   A) Proceed — root cause genuinely spans these files
+   B) Split — fix critical path now, defer the rest
+   C) Rethink — maybe a more targeted approach exists
+   ```
+
+---
+
+## Phase 5: Verification & Report
+
+Reproduce the original bug scenario and confirm it's fixed. Run the
+test suite. Output:
+
+```
+DEBUG REPORT
+════════════════════════════════════════
+Symptom:           [what the user observed]
+Root cause:        [what was actually wrong — cite the evidence]
+Evidence:          [specific log lines, reproduction output, traces]
+Observability:     [sufficient? if not, what gap was found / added]
+Deliverable:       [task created on <surface> | fix applied | report only]
+Fix (if applied):  [what changed, with file:line refs]
+Regression test:   [file:line of new test, or N/A]
+Related:           [prior tasks, prior bugs, architectural notes]
+Status:            DONE | DONE_WITH_CONCERNS | BLOCKED
+════════════════════════════════════════
+```
+
+---
+
+## Important Rules
+
+- **Inconclusive evidence = observability failure.** Fix the gap first.
+- **Default deliverable is a task, not a fix.** Only implement if the
+  user explicitly said "fix it now."
+- **3+ failed hypotheses → STOP.** Almost certainly observability.
+- **Never apply a fix you cannot verify.**
+- **Never say "this should fix it."** Verify and prove it.
+- **Fix touches >5 files → AskUserQuestion** on blast radius.
+- **Completion status:**
+  - DONE — root cause confirmed with evidence; task created (or fix
+    applied if requested)
+  - DONE_WITH_CONCERNS — root cause identified, evidence partial;
+    observability gap flagged for follow-up
+  - BLOCKED — root cause unclear due to insufficient observability;
+    instrumentation task created

package/payload/platform/plugins/admin/skills/plainly/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: plainly
+description: Use when the user asks for a "plain English" explanation, definition, or summary of a technical concept, or pre-empts one ("explain in plain English", "what does X mean", "define X"). Enforces the recursive plain-English rule: an explanation cannot itself contain terms that need their own explanation.
+---
+
+# plainly
+
+Invoked by the admin agent directly.
+
+**Scope — agent-to-human only.** Plainly applies to prose returned to a human reader (the operator, a customer, the admin agent when admin renders prose to the operator). It does NOT apply to arguments passed to `image-generate`, `memory-write`, `memory-classify`, `memory-ingest`, `cypher-shell`, or any other MCP tool — those are agent-to-machine payloads where technical descriptors and structured tokens are required, not jargon to strip.
+
+Produce an explanation that *teaches* the concept to a reader who is bright and motivated but **new to the topic**. They hold general vocabulary (integrals, polynomials, bell curves, logarithms) but do not own the specialist machinery (quadrature rules, weight functions, exactness orders, regime generators). Every phrase in the explanation must be one such a reader can either already understand or be brought up to speed on within the explanation itself. Plain English is the **spoken register**: a sentence has to parse if you read it aloud, in conversation, without a whiteboard. The goal is working understanding the reader can apply and pass on, not a textbook entry they could find in a glossary. Hit the bar on the first attempt; iteration is a leak.
+
+## Why this matters
+
+Textbook explanations are technically correct and pedagogically poor. They convey content without producing understanding. Motivated readers can spend decades asking textbook authors, professors, and field experts for an explanation of a concept and never get one that lands, because every explanation hits the technically-correct mark while missing the spoken-register one. /plainly exists to break that cycle, so the reader walks away able to teach the concept to someone else and have *them* understand it too. Two tests every output has to pass:
+
+- **The aloud test**: could you say this in spoken conversation, without a whiteboard or paper? Formulas, Greek letters, parenthetical acronyms, and chained sub-clauses fail this test even amongst specialists. "S-zero times exp of mu times T" is what nobody actually says; "today's price grown at the long-run drift" is what everyone says.
+- **The understanding test**: does the reader walk away able to *apply* the concept, not just recite its definition? An etymological definition ("lognormal = log is normal") often fails this test because it leaves the reader knowing the words but not the implications. The cure is to follow the definition with practical consequences, visual intuition, and contextual significance.
+- **The new-to-topic test**: would a reader new to this specialist area understand every phrase used in the explanation? Specialist phrases ("exact for a polynomial family", "weighted by the normal density", "regime-coupling generator") may be technically correct and even concise, but if they require prior fluency with the topic they fail. The cure is either to define the phrase operationally inside the explanation, or to unpack it into the plain statement of what it actually means in this case.
+
+Failing the aloud test produces opacity; failing the understanding test produces parroting; failing the new-to-topic test produces *appearance of clarity*: the answer reads as crisp to the writer but lands as a wall of jargon to the audience. A reader who can teach the concept onward to someone else has cleared all three.
+
+## Match the register to the output
+
+Two registers, and they are not the same thing. Pick by what the output is.
+
+**Explaining a concept** (a definition, a summary, teaching the idea): use the shape-of-natural-writing moves below. A little voice belongs here. You are bringing a reader up to speed, so the dropped-in opening, the one earned turn, the concrete anchor, and the landing close all help the idea land.
+
+**Stating what a thing is** (a document, a deck, a proposal, a memo, a report: anything that goes to a reader as a record of what is): the register is flatter and more exact. State what the thing is and how it works, in a sensible order, and stop. The reader should not be able to tell it was written. It just says what is. The essay moves below are wrong here, and reaching for them is most of what makes a business document read as AI. Specifically:
+
+- **The header names the thing. It does not sell or tease it.** "Using AI to handle insurance rejections", not "Rejections, sorted". A title that performs is doing the wrong job.
+- **No hook, no arc, no earned turn, no landing reframe.** A document is not an essay. Say the point in the order that makes it clear, and stop. Do not build tension and then resolve it.
+- **No stance or relationship-posturing.** "We want to listen first", "we're here to help", "they're good at it, and that's the problem" are stances, not facts. State the facts and let the reader draw the conclusion.
+- **No rhetorical setup or reveal.** "And that's the problem", "here's the thing", "it comes down to four steps". Cut the setup and say the content.
+- **Prefer the precise term to the vivid image.** This is the one place this register reverses the anchor move below. "Manual data transfer and reconciliation", not "copying numbers between screens". In a deliverable the exact word reads as matter-of-fact; the image reads as performed.
+- **Name a thing once, then reuse the name.** Pick the term ("the centralised database") and keep it. Paraphrasing the same thing three ways for variety makes the reader stop to check whether they are the same thing.
+- **Say the one true thing.** If one accurate sentence covers it, stop. Three supporting bullets where one sentence is true is padding. A whole section can be one sentence when one sentence is the truth.
+
+Both registers still obey the recursive rule, the aloud test, and the AI-tells catalogue below. This fork only decides whether you reach for a little voice or stay flat.
+
+## The shape of natural writing
+
+The shape-of-natural-writing moves here are the **explaining-a-concept** register from the fork above; for documents and deliverables, stay flat per the statement register. The AI-tells catalogue below says what to strip. This section says what to reach *for*. The model is the short-essay voice of good pre-GenAI blog writing: plain words, one idea, and a reader who is dropped straight into the middle of it. Read a handful of those posts and the first thing you notice is how *spoken* they are. The sentences are uneven. Nothing warms up. The piece says one true thing and stops. That texture is not decoration; it is what "human" reads as, and it is exactly what AI prose sands off.
+
+These are tools, not a template. Use the ones the content actually calls for. Stamping all of them onto every output is its own tell.
+
+- **Start in the middle.** The first sentence is the first sentence. No runway, no "in order to understand X we first have to," no restating the question back to the reader. Open with the claim itself, a small concrete scene, or the single question the whole piece answers, and let the reader catch up. The test: if you can delete your opening sentence and the piece still stands, it was runway. Delete it.
+  - Runway: "In order to understand caching, we first need to think about how computers store data."
+  - Dropped in: "Your computer keeps a few things close at hand, the way you keep your keys by the door."
+
+- **Let the sentences breathe unevenly.** Natural prose alternates a long, winding sentence with a short flat one, and now and then a fragment standing alone. A three-word sentence after a thirty-word one is a gear change the reader feels in the body. This is the positive form of the uniform-cadence tell catalogued below: don't just avoid the steady 12-to-18-word march, reach for the opposite.
+  - "A cache is a small, fast store of the things you'll probably want again. That's it. The hard part was never keeping them. It's knowing when the copy you kept stopped being true."
+
+- **Anchor every abstraction to something you can see or touch.** Swap the category word for the physical thing. "Latency" becomes "the half-second between asking and getting an answer." "Stakeholders" becomes "the three people who can say no." "Synchronisation overhead" becomes "the time everyone spends waiting for everyone else." The concrete noun is almost always the plain-English one too, so this move and the recursive rule pull in the same direction.
+
+- **Earn one turn.** Most short pieces have a single hinge: the thing the reader already assumes, and then the truer thing. Set up the assumption in plain terms, then turn it. One turn, not three. The turn *is* the point; stacking several buries it, and inventing one where the content has none reads as forced. (The earned turn often carries a negation, "the trick isn't X, it's Y". That is *not* the banned antithetical-parallelism tell below. The tell is the same shape used as reflexive flourish with no new content, especially as an opener; the earned turn delivers the actual point of the piece. Use it once, where the content genuinely hinges.)
+  - "Everyone thinks the trick is finding the data fast. The trick is trusting that what you found is still true."
+
+- **Land, don't summarise.** The last line reframes; it does not recap. A closing that opens with "In summary" or "So to wrap up" is throat-clearing at the wrong end. The endings that work are a quiet observation, a small instruction to the reader, or a turn that recasts everything above it. Say it once, then stop.
+  - Recap (weak): "In summary, caching trades freshness for speed."
+  - Land (strong): "So a cache isn't really about speed. It's a bet that the world won't change before you look again."
+
+**Scope of these moves.** The structural ones (the dropped-in open, the single turn, the landing close) apply when the output is a paragraph or more of explanation. A bare two-sentence definition needs only the register and the cadence: plain words, concrete anchors, uneven sentences. Do not bolt a manufactured hook or a profound-sounding reframe onto a definition that has no genuine turn. A reframe with nothing to reframe is indistinguishable from manufactured profundity, which is itself an AI tell.
+
+## The recursive rule (load-bearing)
+
+A plain-English explanation **cannot itself contain terms that need explanation**. Reject any candidate sentence that contains:
+
+- **Acronyms** (PIDE, SDE, ODE, RNG, etc.), even in parentheses. Either expand or replace with the concept the acronym names.
+- **Metaphors that approximate a precise word**: "stitching" for *adding up*, "rule" for *equation*, "chunking" for *grouping*. The precise word is usually also the plain-English word; pick it.
+- **Words whose everyday connotation distorts the meaning**: "increment" connotes positive (use *change*); "step" connotes discrete (use *infinitesimal change* if continuous); "decay" connotes irreversible (use *decrease* if reversible).
+- **Technical terms with a plain-English substitute**: "stochastic" becomes *random*; "deterministic" becomes *fixed by the inputs*; "monotonic" becomes *always moving in one direction*.
+- **Mathematical notation and formulas**: `E^P[S_T] = S_0·exp(μ·T)`, `Σⱼ λᵢⱼ E[Yᵢⱼ]`, function-signature notation like `V(S, t)`, state-tuple notation like `(S, v)`, set-builder notation like `k ∈ {1..K}`, etc. Plain English is the *spoken* register: a sentence has to parse if you read it aloud. "S-zero times exp of mu times T" fails that test even for a quant audience, and so does "V of S comma t" or "k in one to K". Express every relationship in words: "today's price grown at the long-run drift", "option value as a function of spot price and time", "regime index running from one to K". You may *anchor* a single symbol once for cross-reference to the surrounding document (e.g. "the logarithm of S_T, denoted log(S_T)"), but never reproduce a formula, a function signature, or a tuple of state variables. If a relationship genuinely cannot be put into words, the concept is outside the scope of /plainly; see "When NOT to use".
+
+A compound term whose parts are individually plain survives the rule **only if its meaning is compositional**, i.e. the compound means what its parts mean together. *"Differential equation"*, *"random process"*, *"probability distribution"* all survive: a reader who knows what each individual word means can derive the compound's meaning from the parts. *"Characteristic function"*, *"moment generating function"*, *"principal component"*, *"regular expression"* do *not*: each is made of plain English words, but the technical meaning is not derivable from the parts. The mathematical "characteristic function" is the Fourier transform of a probability density; there is nothing in the words "characteristic" and "function" that tells the reader this. Such non-compositional compounds are jargon even when every individual word is plain, and must be either unpacked into their actual meaning or replaced with a more direct phrase. An acronym or coined metaphor is also jargon. **Technical vocabulary already in active use in the surrounding document is fair game**: readers of a quant doc own "logarithm", "normally distributed", "variance", etc.; refusing to use those words and substituting circumlocutions is its own kind of leak.
+
+## Output contract
+
+Plain English isn't only a vocabulary constraint; it's a completeness requirement. A reader needs the *precise definition* AND enough scaffolding to integrate the concept into the surrounding text. The full template:
+
+1. **Definition with explicit notation**: name the precise concept, anchored to the symbol notation the document uses (e.g. *"the logarithm of S_T, denoted log(S_T), is normally distributed"*).
+2. **Practical consequences**: what follows from the definition that the reader can act on or expect (e.g. *"S_T is always positive; large upward moves are more likely than relative downward moves"*).
+3. **(when applicable) Visual intuition**: let the reader picture the thing (e.g. *"the distribution is skewed to the right, with a long right tail"*).
+4. **(when applicable) Contextual significance**: why does the surrounding document care about this property (e.g. *"this is why Black-Scholes is closed-form"*).
+
+Length is dictated by the concept's richness AND by what the user has already supplied. A primitive operation ("what is integration") may need only items 1 and 2, two sentences total. A richer concept ("what is lognormal") usually needs all four. Three or four sentences is the right size for richer concepts; padding beyond that with filler is failure.
+
+**When the user's question is itself a substantive framing, a paragraph that already establishes the definition, motivation, or informal picture and asks for refinement, the answer's word budget is bounded by what makes the explanation land for a reader new to the topic, *not* by the framing's word count.** If the framing is itself written in researcher shorthand (compressing several specialist concepts into a phrase like "exact for a polynomial family"), the answer needs more words to bridge for a new reader. The framing's compactness is not a contract with the audience. The order of priority is: (1) the new-to-topic test must pass; (2) within that constraint, be as concise as possible; (3) only then is the framing a length cap, and only when the framing was already audience-appropriate. A response that runs longer than the prompt is *not* a failure if the extra words are doing bridging work the framing skipped. A response that runs longer than the prompt while *re-stating* what the framing already had IS a failure. The four-item template is still a *maximum*, not a minimum: items the user has already worked out for the right audience are out of scope; items the user only worked out for themselves still need to be done for the reader.
+
+## Rules
+
+- **One precision pass before output.** Read the candidate. Reject if any acronym, metaphor, connotation-distorting word, or unjustified jargon survives.
+- **Separate operation from output.** The operation is one thing; the character of its output (random vs fixed, scalar vs distribution) is a property of the input. Don't conflate them.
+- **No filler.** No "essentially", "basically", "in some sense", "appears to". The explanation is correct or it isn't.
+- **No follow-up offers.** End on the definition.
+- **Strip AI tells.** See the AI-tells catalogue below. Plain English is the *spoken* register, which rules out patterns that AI writing reaches for but humans rarely use in conversation.
+
+## Second pass
+
+Run this after the precision pass, reading the candidate as a reader rather than as the writer. Two questions, and both must pass before the output ships.
+
+- **Would a person say this out loud?** Read it aloud. A sentence that only works on the page (a formula spoken letter by letter, a clause you have to re-read to parse) fails; rewrite it in the spoken register.
+- **Would a stranger flag this as AI?** If a reader who never saw the draft would point at a sentence and call it machine-written, that sentence carries a tell the precision pass missed. Strip it.
+
+## AI tells to strip
+
+These are patterns common in AI-generated prose but rare in actual human writing, especially in spoken or conversational registers. Strip every one on the precision pass. The list grows as more patterns are surfaced.
+
+- **Em-dashes anywhere.** AI reaches for em-dashes constantly; humans use commas, parentheses, semicolons, colons, or just two sentences. "The variance — which mean-reverts to θ — is …" reads as AI; "The variance, which mean-reverts to θ, is …" reads as human. The previous version of this rule allowed em-dashes for "strong breaks" (true asides interrupting the sentence's flow). That carve-out turned out to be the writer's instinct rationalising past the discipline: every em-dash got justified as a strong break, and the polished output kept reading as AI. There is no exception. Use a comma, a semicolon, a colon, parentheses, or two sentences. Never an em-dash, including for heading-then-description separators in marketing copy (use a colon, a comma, or hyphen-with-spaces). The skill's own historical examples in `references/worked-examples.md` contain em-dashes inside quoted bad-pattern illustrations; those stay as illustrations, but the rule applies to every polished output and to the skill's own instructional prose going forward.
+- **Antithetical parallelism: "it's not X, it's Y" / "this isn't X — it's Y".** AI loves this construction as a rhetorical flourish. Humans usually just say "it's Y" and skip the negation, or use "X is wrong; Y is closer to right" if the contrast genuinely matters. Watch especially for it in opening sentences.
+- **Greek letters as primary referents *and* as back-references.** σ, η, θ, ν, etc. as the leading term in a phrase ("vol-of-VIX η_i", "constant-σ model") OR as a later standalone reference ("only the source of η changes"). The plain-English term should be used **throughout**: lead with the meaning ("vol-of-VIX", "constant-volatility model"), use the symbol parenthetically once for cross-reference to the surrounding doc (e.g. "vol-of-VIX (η_i)"), and never back-reference the bare symbol on its own thereafter. Greek letters carry visual jargon weight even when "established" in the doc's glossary; a reader who doesn't recognise the letter (eta? n? a special character?) has to decode it on every appearance, including after it was anchored, because mapping "η here = vol-of-VIX from a sentence ago" is itself the cognitive cost the parenthetical anchor was meant to remove. The word and the letter's spoken name are roughly the same length, so brevity isn't a trade-off either way.
+- **Parenthetical clarifications that introduce more jargon than they remove.** "(a chain-rule shortcut on the Heston dynamics)" attempts to explain a formula but brings in "chain-rule" (a calculus term the reader may not own) without making the formula itself any plainer. If a clarification would itself need a clarification, drop it. The reader can pick up "this is approximate" from broader context (a surrounding sentence about closed-form approximations, etc.) without that specific aside.
+- **Casual-register words: "recipe", "trick", "vibe", "bake in", "secret sauce".** These borrow tone from cooking or colloquial registers and read as glib in technical writing. Use neutral equivalents (*method*, *technique*, *approach*, *embed*) that match the document's register.
+- **Proper-noun mathematician names used as primary referents.** "Fourier methods", "Carr-Madan technique", "Heston-style closure", "Black-76 lognormal price": the proper noun names the inventor or the canonical paper, not the operation itself. A new-to-topic reader does not need to know who Fourier was to understand a transformation. Drop the proper noun and name the operation directly ("a transformation", "a closed-form pricing approach", "a lognormal-on-forward price"). Keep the proper noun only where it is genuinely load-bearing as a citation the reader might look up.
+- **Placeholder words: "methods", "techniques", "approaches".** Noun-phrase fillers that name the *category* of an operation without naming the operation. "Fourier methods" becomes "a transformation"; "an approximation method" becomes "an approximation"; "a numerical technique" becomes the named technique if you can. They give the appearance of substance without delivering any. The category is the right level of abstraction only rarely; check before using.
+- **Stacked-modifier noun phrases.** "The integrated CIR variance distribution" stacks three modifiers ("integrated", "CIR", "variance") onto one noun ("distribution"). A new-to-topic reader cannot parse three modifiers in sequence reliably. Unstack: "the variance probability distribution", "the distribution of variance over time". Each modifier you keep should earn its place by adding precision the reader needs at that point.
+- **Elaborate phrasing for plain claims.** "Match shape to negligible practical error" is a four-word phrase that says what "are close enough" says in two. When the elaborate version doesn't add precision the reader needs, use the plain version. Watch for the construction in particular: any technical-feeling verb-noun pair ("preserve fidelity", "exhibit convergence", "match topology") deserves a precision-pass check against its plain alternative.
+- **Implicit contrasts the reader has to infer.** A source like "X would require expensive method A; the approximations match shape closely enough" contains an implicit "but": the second clause is offered *instead of* the first. Plain English makes the contrast explicit ("would require A *but* the approximations *we use instead* are close enough"). Don't assume the reader will reconstruct the rhetorical relationship from punctuation.
+- **TED-style or formulaic openers.** "In today's fast-paced world…", "In the ever-evolving landscape of…", "At the heart of…", "In the digital age…", "Imagine a world where…", "As we move forward…", "It's no secret that…". Boilerplate intro scaffolding that warms up the reader without saying anything. The sentence *after* the opener is almost always the real first sentence; delete the opener and start there.
+- **Inflation vocabulary.** Words that imply a magnitude, novelty, or significance the surrounding writing hasn't earned. The verb/adjective list: *leverage* (use), *unlock*/*unleash* (allow, enable), *synergy*, *paradigm shift*, *cutting-edge*, *robust*, *scalable*, *comprehensive* (complete), *myriad*/*plethora* (many), *pivotal* (important), *unwavering*, *multifaceted*, *transformative*, *revolutionary*, *game-changer*/*game-changing*, *next-level*, *must-read*, *impactful*, *powerful*, *meaningful*, *strategic*, *seamless*, *holistic*, *testament*. The metaphor list: *tapestry*, *beacon*, *symphony*, *journey*, *roadmap*, *landscape* used non-literally. The honorific list: *titans*, *architects*, *visionaries*, *thought leaders* used as titles. Replace each with the concrete verb, noun, or property the writing is actually claiming: "cuts query time in half" beats "powerful"; "use" beats "leverage"; "many" beats "myriad".
+- **Filler transitions and hedge openers.** Paragraphs that open with *Furthermore*, *Moreover*, *Additionally*; sentences that open with *It is important to note that…*, *It's worth noting that…*, *Keep in mind that…*, *It should be mentioned that…*. Conversational humans don't open this way; the next clause is always the actual content. Cut the opener; the sentence still works.
+- **Rhetorical lecture banter.** "What does this mean?", "What can we learn from this?", "Why does this matter?", "Let's break this down", "Let's dive in", "Let's unpack this". Borrowed from webinar/TED-talk register, designed to *sound* engaging without being so. State the point directly instead. Especially suspicious in casual or non-instructional text where there is no audience to address.
+- **Parallel-pattern overuse, especially "not only X, but also Y".** Beyond the antithetical "it's not X, it's Y" already listed: matching sentence shapes across multiple consecutive lines ("X does A. Y does B. Z does C."), and *not only … but also …* repeated as a flourish. Vary sentence shape; use plain "and", or just two sentences, when no real contrast is being drawn.
+- **Signposting in narrative prose.** "In this section, we'll explore…", "Next, we'll turn to…", "To wrap up…", "Before we dive in…", and "First … Second … Third …" patterns in passages where the structure isn't naturally enumerated. Headings already signpost; doing it again in prose is meta-narration. Cut the scaffolding and let the content speak.
+- **Conceptual emotion without grounding.** "Success can be fulfilling", "the team felt proud", "it was a rewarding experience": emotions named at the level of category with no sensory, bodily, or situational detail. Either ground the feeling in something concrete (what specifically happened, the small awkward moment, the room) or drop it. Naming an emotion isn't evoking it.
+- **Citation-shaped fillers without sources.** "Studies show…", "Research indicates…", "Experts agree…", and round-number statistics ("90% of users…", "3× more effective") with no named source or link. Either name the study, expert, or source so the reader can verify, or drop the appeal to authority and let the claim stand on its own.
+- **Gratuitous emojis, bold, italics, and exclamation marks.** Outside genuinely commercial or chat-app contexts: emojis sprinkled through technical prose, bold or italic emphasis on every other phrase, exclamation marks added to *sound* enthusiastic. These are AI defaults, not human ones. Reserve bold/italic for places a scanning reader truly needs the visual cue; use exclamation marks only when something is actually exclaimed.
+- **Uniform sentence length and cadence.** AI prose settles into 12-18-word sentences at a steady rhythm; human prose alternates: a 30-word sentence can be followed by a 4-word one. If three consecutive sentences are within ~3 words of each other, vary at least one (split a long one, fuse two short ones). The texture is itself a tell, even when every word is fine on its own.
+- **Format scaffolding (bold headings, em-dash separators, parallel bullet stacks) in marketing copy.** Bold-tag headings followed by em-dash separators followed by stacked one-liners read as AI marketing-page output even when every individual word is plain. In human-facing copy, prose with conversational lead-verbs almost always does the same job better. See worked example 12 for the canonical case.
+- *(Add more as you find them.)*
+
+## When NOT to use
+
+- The user wants a tutorial, derivation, or worked example: that is teaching, not defining.
+- The user wants a formal mathematical definition with notation: that is the opposite of plain English.
+- The concept has no plain-English form that survives precision (some objects only exist in their formal language). Say so in one sentence and stop.
+
+## Worked examples
+
+Five worked examples are kept in [`references/worked-examples.md`](references/worked-examples.md), loaded on demand. Examples 1 to 4 are subtractive (sizing, scope, vocabulary, format); example 5 is additive (the "shape of natural writing" moves applied to a flat-but-correct explanation). They cover, in order:
+
+1. Sizing the explanation: a two-sentence primitive vs. the full four-item template for a richer concept.
+2. Transliterate, don't expand: one jargon sentence in, one plain sentence out, with symbol anchoring (meaning first, symbol parenthetical).
+3. Default to plainer than you think: the audience is newer than the writer assumes; downgrade proper nouns, placeholder nouns, and stacked modifiers.
+4. Format scaffolding is itself the AI tell: bold-headings-with-em-dashes must become prose in human-facing copy.
+5. The shape of natural writing: a flat, correct, jargon-free explanation rewritten with a human voice (start in the middle, uneven cadence, concrete anchors, one earned turn, a landing close).
+
+Read the relevant example before producing a polish in a similar register. When the failing quality is liveliness rather than jargon, read example 5 and the "shape of natural writing" section together. The principles in this file are the load-bearing rules; the examples are the concrete demonstrations of each one.

package/payload/platform/plugins/admin/skills/plainly/references/worked-examples.md

@@ -0,0 +1,114 @@
+# /plainly worked examples
+
+Five examples that demonstrate the rules in SKILL.md. Each shows a source, a polished version, and the failure modes the polish avoids. Examples 1 to 4 are subtractive (sizing, scope, vocabulary, format); example 5 is the positive counterpart, the "shape of natural writing" moves turning a flat-but-correct explanation into prose a human would actually write.
+
+Em-dashes appear only inside quoted bad-pattern illustrations (what to avoid); every polished output is em-dash-free, per the rule in SKILL.md. Examples are presented in generic form; where an earlier draft named a specific codebase or pitch, the reference has been neutralised.
+
+---
+
+## 1. Sizing the explanation: primitive vs. richer concept
+
+A primitive operation needs only the precise definition plus its immediate consequence, two sentences. A richer concept needs the full four-item template from the output contract: definition, consequences, visual, significance. Length is dictated by the concept's richness, not by a fixed template.
+
+> **User:** what is integration, in plain English?
+
+> Integration is the act of adding up all the infinitesimal changes specified by a differential equation over an interval, giving the system's state at the end of that interval. If each change is random, that end state is a distribution of possible values; if each change is deterministic, it is a single value.
+
+> **User:** /plainly "S_T is lognormal"
+
+> "S_T is lognormal" means the logarithm of S_T (denoted log(S_T)) is normally distributed. This means S_T itself is always positive and large upward moves are more likely than relative downward moves. Visually, the distribution is skewed to the right, with a long right tail. This property is exactly why Black-Scholes is closed-form (can be solved analytically rather than numerically).
+
+**Failure modes:**
+
+- *Definition only, no scaffolding.* "...the logarithm follows a bell-curve distribution." Correct terms, but the reader gets a dictionary entry they cannot use. A richer concept needs the consequences, the picture, and why the document cares.
+- *Over-correction that drops the doc's own vocabulary.* Avoiding "logarithm" or "normally distributed" and substituting circumlocutions leaves the reader with no anchor to the rest of the document. Plain English keeps vocabulary the doc has already established.
+- *Padding a primitive to four items.* Integration needs two sentences. Adding a manufactured "visual" or "significance" to a primitive is filler.
+
+**Principle:** two items for a primitive, up to four for a rich concept; never pad past what the reader needs.
+
+---
+
+## 2. Transliterate, don't expand (match the scope of the question)
+
+When the source is a single sentence dense with jargon, the plain version is also a single sentence: keep the syntactic frame, swap each jargon term for its plain equivalent, stop. When the source uses bare symbols, anchor them, putting the meaning first and the symbol in parentheses as a cross-reference back to the surrounding document.
+
+> **User:** /plainly "parameter standard errors fall out of the calibrated Jacobian via the usual covariance formula."
+
+> Since the calibration produces a table of sensitivities as part of its loss-minimisation process, this table is converted to statistics that express the margin of error in the parameters.
+
+> **User:** /plainly "The V₀ memory has decayed to θ by the time of any VX-future expiry, so the V₀ term drops out."
+
+> By the time any VX future expires, the variance has mean-reverted from its starting value (V₀) to its long-run level (θ), so the formula no longer depends on V₀.
+
+The mapping is direct: "the calibrated Jacobian" becomes "a table of sensitivities"; "V₀ memory" becomes "starting value (V₀)" (meaning first, symbol parenthetical); "decayed to θ" becomes "mean-reverted to its long-run level (θ)". Each jargon term lands in the slot it occupied in the source. Nothing is added; nothing is cut.
+
+**Failure modes:**
+
+- *Expanding a one-sentence question into paragraphs.* The reader asked what one sentence means, not for a tutorial. Numeric examples, adjacent context (a connection that lives in neighbouring sentences, not the asked one), or a "the catch is…" paragraph are all scope creep.
+- *Leading with the symbol.* "V₀ is the initial variance…" makes the reader decode the symbol first. Lead with the meaning, anchor the symbol once parenthetically, and never back-reference the bare symbol later: mapping "V₀ here = starting value from a sentence ago" is the cost the anchor was meant to remove.
+
+**Principle:** match the scope of the question, not the depth of the topic. One sentence in, one sentence out.
+
+---
+
+## 3. Default to plainer than you think; the audience is newer than the writer
+
+The writer's audience-model is calibrated to the writer's own background, so the words that feel obvious ("Fourier methods", "characteristic function") are exactly the ones to downgrade. The cost of going one level too plain is mild (an expert feels slightly patronised); the cost of going one level too jargon-heavy is severe (the new reader bounces off entirely). The asymmetry favours plainer.
+
+> **Source:** "Exact VIX pricing under Heston would require Fourier methods on the integrated CIR variance distribution; the closed-form approximations match shape to negligible practical error and are fast enough for repeated pricing."
+
+> **First pass (still too jargon-heavy):** "Exact VIX pricing under Heston would require Fourier methods applied to the distribution of integrated variance; the closed-form approximations match the exact shape to negligible practical error and are fast enough to call repeatedly."
+
+> **Polished:** "Exact VIX pricing under Heston would require a transformation of the variance probability distribution but the closed-form approximations we use here instead are close enough in terms of residual error and fast enough that we can call them repeatedly."
+
+The second pass downgrades each borderline word: "Fourier methods" becomes "a transformation" (drops the proper noun and the placeholder noun "methods"); "integrated CIR variance distribution" becomes "variance probability distribution" (unstacks the modifier chain); "match shape to negligible practical error" becomes "close enough in terms of residual error" (elaborate phrasing collapses to the plain claim); and an explicit "but" is added so the reader does not have to infer the contrast from punctuation. Note the polished version is no shorter than the first pass: plainness is substituting vocabulary downward, not cutting words.
+
+**Failure modes:**
+
+- *Treating proper nouns as low-cost.* A reader need not know who Fourier was to understand a transformation. Keep a proper noun only where it is load-bearing as a citation the reader might look up.
+- *Placeholder nouns and stacked modifiers.* "methods / techniques / approaches" name a category without naming the operation; three modifiers on one noun ("integrated CIR variance distribution") cannot be parsed in sequence by a new reader.
+- *Precision without bridging.* A short answer using three specialist phrases is *longer* in reading time than a longer answer using none, because the reader has to look each one up. If a phrase compresses several specialist ideas ("exact for a polynomial family"), unpack it inside the explanation or expect the new reader to bounce.
+
+**Principle:** default plainer than feels necessary; restore precision only where it would otherwise be lost. If a word feels obvious, that is evidence to drop it, not keep it.
+
+---
+
+## 4. Format scaffolding is itself the AI tell
+
+Some sources arrive in the heading-and-bullet format AI defaults to in marketing copy: bold-tag headings, em-dash separators, stacked one-liners, a signpost line, a closing tricolon. The polish must question the *format*, not just refine the words inside it. In human-facing copy, prose almost always does the same job better, and the heading-and-em-dash format is the visual signature of an AI marketing page regardless of how plain the words are.
+
+> **Source:** A consultancy pitch presenting three offerings as `**Bold Heading** — description` blocks, introduced by a signpost line ("Three ways I work with clients:") and closed with a tricolon of three parallel-shape sentences ("I [verb] the [noun].").
+
+> **Failed polish (kept the format):** Same headings, same em-dash separators, tricolon merged to one sentence with three verbs. Word-level tells were caught; the visual scaffold was preserved, so it still reads as AI marketing copy.
+
+> **Gold standard (prose):** Three offerings folded into running prose, each opened by a verb the writer would actually say. No bold headings. No em-dashes (the separator becomes a comma, or a hyphen with spaces if needed). The signpost line is deleted. The closing tricolon is removed entirely, not collapsed. Any closing sequence becomes a single conditional invitation: "If you have recognised X and understand Y, then I can help you put Z into practice."
+
+**Failure modes:**
+
+- *Treating the heading-and-em-dash format as a feature of the source rather than a constraint to question.* For three short offerings, prose with conversational lead-verbs reads faster than a heading-bulleted list.
+- *Collapsing a rhetorical tricolon instead of removing it.* If a closing adds no new content, only strong-form repetition, cut it; the reader has read the offerings and does not need a chant of the verbs.
+- *Specific-sounding numbers the writer cannot source.* "a 1-2 year head start", "30% faster" read as authoritative; if you cannot defend the bound, "a limited head start", "noticeably faster" express the same shape without false confidence.
+
+**Principle:** the AI-tells catalogue applies to format as much as to vocabulary. When the source is in heading-and-bullet format, the precision pass must ask whether prose would do the same job; in human-facing copy the answer is almost always yes.
+
+---
+
+## 5. The shape of natural writing (the positive counterpart)
+
+The first four examples are subtractive: they remove jargon, notation, and format tells from text that was trying to be a definition. The fifth is additive. The source here is not wrong and has no obvious jargon to strip; it is simply lifeless, technically correct and recognisably machine-made. The job is to make it read like a person wrote it, using the five moves from the "shape of natural writing" section.
+
+> **User:** /plainly "what is a database index?"
+
+> **Flat source (the default machine answer):** "A database index is a data structure that improves the speed of data retrieval operations on a database table at the cost of additional writes and storage space to maintain the index data structure. Indexes are used to quickly locate data without having to scan every row in a table each time the table is queried."
+
+> **Polished:** "Think of the index at the back of a book. Without it, finding every mention of caching means turning all four hundred pages. With it, you read one line and jump straight to page 212. A database index is that back-of-the-book list, kept for a column you search on a lot, so the database can find the rows it wants without reading the whole table. The cost is real. Every time you add a row, the index has to be updated too, and it takes its own space on disk. So you don't index everything. You index the columns you actually look things up by, and let the rest be read the slow way."
+
+Each move did its work: a dropped-in concrete open (the book the reader already pictures), uneven cadence ("The cost is real." between two long sentences), abstractions anchored to things you can see (four hundred pages, page 212, space on disk), one earned turn (the index sounds free, then the write-time cost is the hinge), and a landing close that hands the reader something to do rather than a recap.
+
+**Failure modes:**
+
+- *Restating the same claim twice.* The flat source says "improves the speed of data retrieval" then "quickly locate data without scanning every row": one fact, twice, in category language. The book picture carries it once.
+- *Even cadence and no anchor.* Two ~30-word sentences in a row is the machine march; "data structure" is correct and weightless, leaving the reader picturing nothing.
+- *Manufacturing a turn, or closing with a summary.* This concept has one genuine hinge (the write-time cost); do not stack more, and do not end with "In summary, an index trades write cost for read speed."
+
+**Principle:** plain English is not only the absence of jargon; it is the presence of a human voice. A correct, jargon-free explanation still fails if it is evenly paced, anchored to nothing, and ends by repeating itself.