@rubytech/create-siteoffice-code 0.1.256

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

@@ -0,0 +1,318 @@
+---
+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
+
+## 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,105 @@
+---
+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
+
+**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.
+
+## 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.
+
+## 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
+
+Twelve worked examples are kept in [`references/worked-examples.md`](references/worked-examples.md), loaded on demand. The examples cover, in order:
+
+1. Integration: a primitive operation, two-sentence definition.
+2. "S_T is lognormal": a richer concept that uses all four template items.
+3. The Merton model dimensionality question: function-signature notation is itself a formula.
+4. Quadrature, well-framed: density beats scaffolding when the framing is already audience-appropriate.
+5. Quadrature, new reader: precision without bridging fails the new-to-topic test.
+6. Quadrature, in-document phrasing: scope-matching, the operational definition is often enough.
+7. "parameter standard errors fall out of the calibrated Jacobian": one sentence in, one sentence out (transliterate, don't expand).
+8. "V_0 memory has decayed to θ": symbol anchoring (meaning first, symbol parenthetical).
+9. VIX options under regime-switching Heston: Greek letters are jargon, parenthetical clarifications must add substance, watch the register.
+10. "Same closure as the constant-σ path": "same as X" references must define X, not punt to it.
+11. VIX pricing under Heston: when in doubt, go simpler, the audience is less experienced than the writer thinks.
+12. Marketing-pitch format scaffolding: bold-headings-with-em-dashes is itself the AI tell, regardless of how plain the words inside are.
+
+Read the relevant example before producing a polish in a similar register. The principles in this file are the load-bearing rules; the examples are the concrete demonstrations of each one.