@caddis/cli 0.4.0 → 0.4.2

package/bundles/codex/.codex/skills/docs/tech-explainer/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: tech-explainer
+context: fork
+description: >-
+  Write a plain-language technical explainer for a smart reader who did NOT do the investigation — a
+  manager, an infra colleague, a stakeholder, the person whose recommendation you are answering.
+  Layered Mermaid diagrams that rank causes by SIZE OF EFFECT, a controlled-vocabulary table,
+  Simplified Technical English, published withdrawn results, and questions back to the reader. Use
+  this skill whenever the user says "explain this to X", "explainer", "write this up for someone
+  non-technical", "plain English", "simplified technical english", "STE", "explain our findings",
+  "write up the benchmark results", "answer my manager's recommendations", "why is it slow — document
+  it", "make a doc with diagrams explaining the stack", or is about to summarise an investigation, a
+  benchmark, a postmortem, an architecture, or a disagreement for a reader who will not read the raw
+  data. NOT for handing off work to be BUILT by a vendor or another team (use explainer-doc for that —
+  it produces an actionable spec); NOT for READMEs or API docs (use technical-writing). This one
+  produces UNDERSTANDING: the reader must finish able to argue with you on the merits.
+---
+
+# tech-explainer — make a stranger understand, and able to push back
+
+The reader is intelligent but was not in the room. They did not watch the tests, they will not read
+the raw report, and they have their own opinion about what you should do. If you hand them the
+findings compressed, every conclusion looks like an assertion, and the conversation becomes
+credentials against credentials.
+
+**The job is not to summarise. The job is to transfer enough of the reasoning that the reader can
+disagree with you correctly.** A reader who finishes and says "I still think it's the wrapper, and
+here's why your 3x number is wrong" is a success. A reader who nods and remembers nothing is a
+failure, even if they agreed.
+
+## What this skill gives you
+
+| File                        | Use it for                                                                  |
+| --------------------------- | --------------------------------------------------------------------------- |
+| `assets/skeleton.md`        | **Start here.** The fill-in document. Copy it, then delete what has nothing to say. |
+| `references/diagrams.md`    | Copy-paste Mermaid for all six patterns, plus the syntax that bites.        |
+| `references/language.md`    | Full STE rules, the rewrite table, and the mechanical rewrite pass.         |
+
+## When this is NOT the right skill
+
+- The reader must **build** something from the document → `explainer-doc`. That skill produces an
+  actionable spec (DDL, queries, acceptance criteria). This one produces understanding.
+- The reader already lived through the investigation → `technical-writing` or a plain summary. The
+  vocabulary table and STE discipline are overhead they don't need.
+- It's a README, API reference, or runbook → `technical-writing`.
+
+The tell for *this* skill: **the reader will form or change an opinion**, and you need that opinion
+to be based on the numbers rather than on trust.
+
+## The central move — rank the layers by size of effect
+
+This is the single technique that makes the document work, and it is what most explainers get wrong.
+
+An architecture diagram shows **what exists**. It is the natural thing to draw and it is nearly
+useless here, because the reader's real question is not "what is the shape of this system" — it is
+**"what should we change?"** So draw the same stack, but label every layer with **the magnitude of
+its effect on the outcome**:
+
+```
+LAYER 1 — The model — LARGEST EFFECT — about 3x
+LAYER 2 — The engine — MEDIUM EFFECT — tens of percent
+LAYER 3 — The program — SMALL EFFECT — under 5%
+LAYER 4 — The operating system — NO EFFECT
+```
+
+Now the reader who came in convinced that swapping the program would fix everything can see, without
+being contradicted, that they were aiming at the 5% layer. **The disagreement becomes arithmetic.**
+That is worth more than any paragraph of argument, because arithmetic is something they can check
+and you cannot fake.
+
+Rules for this diagram:
+
+- **Order the layers by effect size, largest first** — not by where they sit in the stack, and not by
+  the order you investigated them.
+- **Every layer carries a number or an honest "no effect"**, plus the one-line reason. A layer with no
+  measurement is a layer you are guessing about; say "not measured" rather than inventing a rank.
+- **Include the layer the reader is about to optimise, even if it ranks last.** Leaving it out looks
+  evasive. Ranking it last with a measured number is the whole argument.
+- **Say how to read it.** One line under the diagram: *"If we change the program, we gain a few
+  percent. If we change the model, we gain about 3 times. Layer 1 is where the work must go."*
+
+If your subject has no natural layers, the same move still applies: rank the candidate causes by
+their measured contribution, and call them causes rather than layers. The stack is a convenience; the
+ranking is the point. It transfers to any "why is it slow / expensive / wrong" question — the causes
+of an ETL's runtime, the sources of a cloud bill, the contributors to a defect rate.
+
+**An attribution number must carry its method.** "The N+1 query is 85% of the p99" is the sentence
+the whole document rests on, and share-of-total figures are where this kind of analysis rots: they
+get produced by one tool, quoted onward, and nobody remembers whether it was mean or p99, warm or
+cold, one endpoint or all of them. Say how the share was obtained, in the same breath — *"85% of p99,
+from 12,000 spans over 24 hours, attributed by span duration"*. If you cannot say how, rank it
+qualitatively and mark it unmeasured rather than putting a false number on the diagram.
+
+## Simplified Technical English — the language discipline
+
+STE is not dumbing down. It is removing every sentence that can be read two ways, so a reader who is
+expert in a *different* field never has to guess. Announce it in the header so the terseness reads as
+courtesy rather than curtness:
+
+> **Written in Simplified Technical English.** Short sentences. One idea per sentence.
+
+Six rules cover most of it. Full rules and before/after rewrites: `references/language.md`.
+
+1. **One idea per sentence.** Aim under 20 words. Split on "and", "but", "which", ";".
+2. **One word, one meaning.** Fix the term in the vocabulary table (§2), then never use a synonym for
+   it. "Engine" stays "engine" — never "backend", "runtime", or "inference layer".
+3. **Active voice, and name the actor.** "We withdrew the result", not "the result was withdrawn".
+4. **No idiom, no metaphor, no hedging.** Not "the low-hanging fruit", not "it seems likely that".
+   If you are unsure, say the size of your uncertainty: "we measured this once, on a test prompt".
+5. **Every number carries its unit and its basis.** "2,373 output tokens per summary, measured from
+   `gpt-4o`" — not "about 2.4k tokens".
+6. **Never open a paragraph with a pronoun standing in for the previous paragraph.** The reader
+   skims and lands mid-document; name the subject again. ("This is the most important diagram in
+   this document" is fine — "this" points at the thing directly below it, not at prose above.)
+
+## The shape — sections in this order
+
+The order is load-bearing: the reader must be able to stop at any section and have gained something
+complete. Not every document needs all fifteen. The **bold** slots are the ones that make it *this*
+kind of document; drop the others when they have nothing to say.
+
+| §   | Slot                              | What it does                                                                                                                    |
+| --- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| —   | **Header**                        | Title, `**Audience:**` by name, and the STE announcement. Naming the reader changes how the whole document reads.                |
+| 1   | **Why this document exists**      | Numbered list of the questions this answers. Then route the reader's own question: *"Section 5 answers the LM Studio question."* |
+| 2   | **Words used in this document**   | Controlled vocabulary table. One meaning only. This is what lets the rest be short.                                             |
+| 3   | What we are building              | One left-to-right flowchart of the real pipeline, plus the physical facts (hardware, OS, versions).                              |
+| 4   | **The goal, in numbers**          | Target / measured / gap, in a table, with the three key rows in bold. If there is no gap, say what "good" is.                    |
+| 5   | The layer stack                   | What sits on what, and which layers are cheap to change. Answer the reader's specific question here if they asked one.           |
+| 6   | Why the work took so long         | The results you **withdrew**, and what caught each one. See below — this section buys more credibility than any other.           |
+| 7   | Where the time (or cost) goes     | A proportion chart with the sample count. Redirects effort before anyone argues about it.                                        |
+| 8   | **What limits the result**        | The ranked-layer diagram. The most important diagram in the document. Say so, and say how to read it.                            |
+| 9   | The recommendations we checked    | One row per claim: recommendation / verdict / evidence. Then a **"Where the advice is right"** subsection.                       |
+| 10  | What the constraint costs         | The forced choice (a platform, a vendor, a deadline) — what it costs, and what it genuinely gives back.                          |
+| 11  | **What we do next**               | Ordered steps as a flowchart. Name which step matters most. Then list the measurement gaps still open.                           |
+| 12  | Questions for \<reader\>          | Real questions only. This converts a verdict into a conversation.                                                                |
+| 13  | **Summary in five lines**         | Five numbered sentences. Someone will read only this. Make it survivable alone.                                                  |
+| —   | **Related documents**             | Table: document → what it holds. This is what lets §1–13 stay short without hiding anything.                                     |
+
+Rename the slots to fit the domain — a security review, a cost analysis, and a latency investigation
+will all name §3–§10 differently. Keep the order and the intent.
+
+### When a slot does not fit
+
+Most explainers hit two or three of these. Substituting is right; padding the slot with invented
+content is not, and forcing a section you have nothing for is how the document starts sounding
+false.
+
+| Situation                                            | What to do                                                                                                                                                                                            |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **§4 — no target exists**                            | Retitle it "The result, in numbers" and make the missing target the finding: *"We have no agreed p99 target. That is the first thing to fix."* A gap you cannot size is still worth naming.            |
+| **§5 duplicates §8** (few causes, one stack)         | Collapse. Make §5 a table with a column §8 lacks — usually **cost to change** or **who owns it** — and let §8 carry the only stack diagram. Two near-identical diagrams teach the reader nothing twice. |
+| **§6 — nothing was withdrawn**                       | Do not invent a retraction. Substitute the assumptions the argument rests on, plus what would falsify each. Same function: it shows the reader where to attack.                                        |
+| **§9 — no formal list of recommendations**           | The reader still has a belief. Turn it into a claims-checked table: *the claim as they would state it* / verdict / evidence. "It's just copying data" is a claim; check it like one.                    |
+| **No independent external number to anchor against** | Say so once and move on. A stated absence costs nothing; a fabricated comparison costs the document.                                                                                                   |
+| **The reader has no name** ("my manager")            | Use their role in the audience line — *"Audience: the engineering manager"* — and leave a visible placeholder. Never invent a name.                                                                     |
+| **The prompt is the only source**                    | Say so in §1 and label every number by origin: measured / calculated / assumed. See process step 2.                                                                                                    |
+
+### When to stop
+
+Section count follows the evidence, not the template. Four numbers and one conclusion is a six-section
+document; a three-week investigation with retractions is a fifteen-section document. If a section
+would exist only because the table lists it, cut it — a short explainer that a manager finishes beats
+a complete one they abandon at §7.
+
+The load-bearing minimum is: the audience line, §2, §8, §13, and the related-documents table.
+
+## The moves that carry the document
+
+**Lead every section with the bolded short answer.** The reader is looking for the answer to one
+question. Give it in the first line, in bold, then spend the section earning it:
+
+> **Short answer: we do not have LM Studio installed. But we already run the engine that is inside
+> LM Studio.**
+
+**Publish what you withdrew.** List the results you reported and later retracted, each with the cause
+and how it was caught. This feels like confessing and it is actually the strongest section in the
+document: it explains why the work took three weeks, it proves the surviving numbers were checked the
+same way, and it inoculates you against the next person who finds an error. End with the lesson in
+one line — *"a benchmark that gives a believable number is not therefore correct."*
+
+**Steelman the person you are answering.** Before refuting a recommendation, write the subsection
+where they are right, and mean it. *"The review is correct that the GPU is not fully used. We confirmed
+this with arithmetic."* Then: *"The instinct behind the advice is right. The cause is different from
+the cause given."* Nobody accepts a correction from someone who did not first understand them.
+
+**Route each wrong assumption to its real cause, and it is usually not the reader.** When someone
+recommends a fix you have already applied, the honest framing is almost never "they were wrong" — it
+is that nobody told them. Write it that way: *"The database has been on NVMe since March. That is not
+recorded anywhere the infra team can see, which is our gap to close, not a wrong call."* This is the
+same instinct as the steelman, applied to facts rather than judgement, and it does real work in a
+document that answers someone senior: it separates **the recommendation was reasonable given what
+they knew** from **the recommendation is what we should do**, which is the only distinction that
+lets a senior reader change position without losing anything. Look for it every time a verdict comes
+out "already done" or "does not apply here".
+
+**Show the arithmetic in a bare code block.** When a conclusion rests on a calculation, print it so
+the reader can redo it in their head:
+
+```
+GPU memory speed                 3,900 GB per second
+Data read per token              2.65 GB
+Theoretical maximum              1,470 tokens per second
+Measured                         114 to 316 tokens per second   (8% to 21%)
+```
+
+A number the reader can re-derive is a number they own. A number they must accept is one they will
+challenge later, at a worse time.
+
+**Anchor against an independent external result, when one exists.** "Are we misconfigured?" is
+answerable only by comparison. Find someone else's published number on comparable kit, put it in a
+two-row table beside yours, and state the conclusion plainly. This turns a defensive claim into a
+measurement. If no comparable number exists, say that in one line and move on — never assemble a
+lookalike from a different workload to fill the slot.
+
+**Admit the gaps you did not close.** Name what you never measured directly and what you would need
+to do it. Two or three lines. A document with no admitted gaps reads as marketing.
+
+**Diagrams for shape, tables for detail, prose only for judgement.** If a table says it better, delete
+the diagram. The count is not the test — the test is that each diagram answers a question no other
+one answers. The source explainer carries eight across thirteen sections and none is redundant; a
+six-section explainer with four near-identical stack diagrams is over-drawn.
+
+## Diagram vocabulary
+
+Keep to a small, repeated set of Mermaid shapes — the document reads as one voice because the same
+four patterns recur. Copy-paste versions with the syntax details (bold inside nodes, dotted
+"hypothetical" arrows, line breaks, pie charts): `references/diagrams.md`.
+
+| Pattern                            | Use for                                        |
+| ---------------------------------- | ---------------------------------------------- |
+| `flowchart LR`                     | The pipeline. Input → work → output.           |
+| `flowchart TB` with `subgraph`s    | The layer stack — §5, and the ranked §8.       |
+| `flowchart LR` with a decision node | A loop or a check procedure.                    |
+| `pie showData`                     | Where the time/cost goes. Give the run or N.   |
+
+Check every diagram before shipping: paste it into `mermaid.live`, or read it against the syntax
+table at the end of `references/diagrams.md`. A broken Mermaid block renders as raw source and costs
+more credibility than the diagram was worth.
+
+## Process
+
+1. **Name the reader and their question.** Ask if it is not obvious. "Explain the benchmark" is not
+   enough — you need *who* and *what they currently believe*, because §8's ranking exists to meet a
+   specific wrong (or right) belief. If they already have full context, stop and use a plain summary.
+2. **Read the source material yourself.** The raw report, the measurement logs, the plan, the thread
+   you are answering. Do not write an explainer from a summary — the explainer is the place where
+   soft numbers get caught, and you cannot catch them at second hand. **If no source exists and the
+   request itself is all you have**, that is workable but must be visible: say in §1 that the numbers
+   come from the requester, and tag every figure in the document `(measured)`, `(calculated)` — with
+   the arithmetic shown — or `(assumed)`. The tags cost a few words and they are what stop your
+   inference being quoted back later as someone's measurement.
+3. **Build §8 first.** List every candidate cause, attach its measured effect size, and sort. If you
+   cannot rank them, you do not yet understand the system well enough to explain it — go measure, or
+   say explicitly which layers are unranked and why.
+4. **Write §2, the vocabulary, second.** Every term you fix here makes the following sections shorter.
+5. **Copy `assets/skeleton.md` and fill it top to bottom**, deleting the slots that have nothing to
+   say (see "When a slot does not fit"). Keep evidence beside each claim rather than in an appendix.
+6. **Rewrite in STE last, as its own pass.** Split long sentences, hunt synonyms for defined terms,
+   convert passive to active, attach units to bare numbers. It is a mechanical pass; do it
+   mechanically. `references/language.md` has the rewrite table.
+7. **Run the exit gate.**
+
+## The exit gate
+
+Ask all four before shipping. Each one has caught a real defect in this document type.
+
+- **"Can the reader disagree with me on the merits?"** If every conclusion rests on "we measured it"
+  with no visible number or method, they can only agree or distrust. Neither is useful.
+- **"Does §8 rank the layer the reader cares about?"** If their favoured fix is missing from the
+  ranked diagram, the document dodges instead of answering.
+- **"Would the five-line summary survive alone?"** Someone will forward only that. Read it cold.
+- **"What did I state without a basis?"** Every number needs a unit, a sample size or a measurement
+  date, and a way to reproduce it. Bare numbers are where explainers rot first — they get quoted
+  onward, and six weeks later nobody knows what they measured.
+- **"Which section is here only because the template listed it?"** Cut it. Padding reads as padding,
+  and it spends the attention you need for §8.
+
+If the repository has a document-frontmatter convention, apply it (`type: analysis` fits this
+document kind). Then add the document to the doc index if one exists.

package/bundles/codex/.codex/skills/docs/tech-explainer/assets/skeleton.md

@@ -0,0 +1,255 @@
+<!--
+  tech-explainer skeleton. Copy, fill, delete what has nothing to say.
+  Slots marked [KEEP] are what make this an explainer rather than a summary.
+  Rename any section to fit the domain — keep the order.
+  If the repo requires document frontmatter, add it above the title (type: analysis).
+-->
+
+# \<The subject\> — a plain explainer
+
+<!-- No name given? Use the role — "the engineering manager" — and leave this placeholder visible.
+     Never invent a name. -->
+**Audience:** \<name or role of the reader\>, and anyone who did not do the \<testing / investigation / migration\>.
+**Written in Simplified Technical English.** Short sentences. One idea per sentence.
+
+---
+
+## 1. Why this document exists  [KEEP]
+
+This document explains \<n\> things:
+
+1. \<question 1\>
+2. \<question 2\>
+3. \<question 3\>
+
+Section \<n\> answers the \<the reader's own question\> directly.
+
+---
+
+## 2. Words used in this document  [KEEP]
+
+Use these words with one meaning only.
+
+| Word       | Meaning                                          |
+| ---------- | ------------------------------------------------ |
+| **\<term\>** | \<one meaning, in plain words, no new jargon\>  |
+
+<!-- 8-12 rows. Highest value: terms two people in the thread have used differently. -->
+
+---
+
+## 3. What we are building
+
+\<Two or three sentences. What the system does and why it exists.\>
+
+```mermaid
+flowchart LR
+    A[("Source")] --> B["Work<br/>size"] --> C[("Result")]
+```
+
+\<The physical facts: hardware, operating system, versions, scale.\>
+
+---
+
+## 4. The goal, in numbers  [KEEP]
+
+<!-- No agreed target? Retitle "The result, in numbers" and make the missing target the finding. -->
+
+\<One sentence stating the target.\>
+
+| Item                    | Value       |
+| ----------------------- | ----------- |
+| \<basis\>               | \<value\>   |
+| **\<what we need\>**    | **\<n\>**   |
+| **\<what we measure\>** | **\<n\>**   |
+| **Gap**                 | **\<n x\>** |
+
+<!-- If an earlier target has changed, say so and say why. -->
+
+---
+
+## 5. The layers — and \<the reader's specific question\>
+
+**Short answer: \<the answer, in one or two sentences\>.**
+
+\<Then earn it.\>
+
+```mermaid
+flowchart TB
+    subgraph l1["LAYER 1 — <name> (<what this layer is for>)"]
+        direction LR
+        A["<b>Thing</b><br/>status"]
+    end
+    subgraph l2["LAYER 2 — <name> (<what this layer is for>)"]
+        B["<b>Thing</b>"]
+    end
+    A --> B
+```
+
+\<One line: which layer is easy to change, which layer decides the outcome.\>
+
+### \<The options compared\>
+
+| Option | What it adds | What is inside | Do we use it? |
+| ------ | ------------ | -------------- | ------------- |
+|        |              |                |               |
+
+---
+
+## 6. Why the work took so long — what we withdrew
+
+<!-- Nothing withdrawn? Do NOT invent a retraction. Substitute "What this rests on": the assumptions
+     the argument depends on, each with what would falsify it. Same function — it shows the reader
+     where to attack. -->
+
+\<n\> wrong results were found. **Every one was found by comparing a number against a second,
+independent number.**
+
+```mermaid
+flowchart LR
+    A["Change one thing"] --> B["Measure it"]
+    B --> C{"Does it agree with a<br/>second, independent number?"}
+    C -->|"No"| D["The instrument is wrong.<br/>Repair the test."]
+    D --> B
+    C -->|"Yes"| E["Record the result"]
+```
+
+- We reported \<claim\>. **This was wrong.** \<Cause, and what caught it.\>
+- We reported \<claim\>. **This was wrong.** \<Cause, and what caught it.\>
+
+**Lesson:** \<one line\>.
+
+---
+
+## 7. Where the \<time / cost / data\> goes
+
+We measured \<n\> samples.
+
+```mermaid
+pie showData
+    title <what is being divided>
+    "<slice A>" : 0
+    "<slice B>" : 0
+```
+
+\<The consequence: what this means for where effort should go.\>
+
+---
+
+## 8. What limits the result — \<n\> layers  [KEEP — the most important diagram]
+
+This is the most important diagram in this document. The layers are in order of size of effect.
+
+```mermaid
+flowchart TB
+    subgraph L1["LAYER 1 — <cause> — LARGEST EFFECT — <magnitude>"]
+        M["<b>The claim.</b><br/>The comparison.<br/>The consequence."]
+    end
+    subgraph L2["LAYER 2 — <cause> — MEDIUM EFFECT — <magnitude>"]
+        E["<b>The claim.</b><br/>The evidence."]
+    end
+    subgraph L3["LAYER 3 — <cause> — SMALL EFFECT — <magnitude>"]
+        W["<b>The claim.</b><br/>The evidence."]
+    end
+    subgraph L4["LAYER 4 — <cause> — NO EFFECT"]
+        O["<b>The claim.</b><br/>The evidence."]
+    end
+    L1 --> L2 --> L3 --> L4
+```
+
+**Read the diagram this way.** If we change \<the small layer\>, we gain \<small\>. If we change
+\<the big layer\>, we gain \<big\>. \<Layer n\> is where the work must go.
+
+---
+
+## 9. \<n\> recommendations — what we checked
+
+<!-- No formal list of recommendations? The reader still holds a belief. State it as they would
+     state it, then check it: claim / verdict / evidence. -->
+
+We checked all \<n\> against our own measurements and against public evidence.
+
+| #   | Recommendation | Result | Evidence |
+| --- | -------------- | ------ | -------- |
+| 1   |                |        |          |
+
+### Where the advice is right
+
+\<Steelman. Concede what is genuinely true, with the arithmetic.\>
+
+```
+<quantity>            <value>
+<quantity>            <value>
+Theoretical maximum   <value>
+Measured              <value>   (<percent>)
+```
+
+### Why \<the alarming number\> is not as bad as it looks
+
+| System                  | Result |
+| ----------------------- | ------ |
+| \<independent source\>  |        |
+| **\<ours\>**            |        |
+
+**Conclusion: \<one sentence\>.**
+
+---
+
+## 10. What \<the constraint\> costs us, and what it gives us
+
+### The cost
+
+| Option | Supported? | Note |
+| ------ | ---------- | ---- |
+|        |            |      |
+
+### What it does not cost us
+
+\<The belief people hold, checked. State plainly whether the evidence supports it.\>
+
+### What it gives us
+
+\<The genuine benefit. Every constraint has one; naming it proves you are not just complaining.\>
+
+---
+
+## 11. What we do next  [KEEP]
+
+```mermaid
+flowchart TB
+    A["<b>Step 1 — <name></b><br/>What. How it is measured."] --> B
+    B["<b>Step 2 — <name></b><br/>What. What counts as passing."] --> C
+    C["<b>Step 3 — <name></b><br/>What."]
+```
+
+**Step \<n\> is the most important step.** \<Why, with the number.\>
+
+We also have \<n\> measurement gaps to close:
+
+1. \<What we never measured directly, and how long the direct check would take.\>
+
+---
+
+## 12. Questions for \<the reader\>
+
+These would help us. \<Reader\> has more experience with \<the area\>.
+
+1. **\<Question?\>** \<Why the answer would change what we do.\>
+
+---
+
+## 13. Summary in five lines  [KEEP]
+
+1. \<target vs measured vs gap\>
+2. \<the main cause\>
+3. \<the thing the reader thought was the cause, with its measured size\>
+4. \<the constraint, and what it really costs\>
+5. \<the next step\>
+
+---
+
+## Related documents
+
+| Document | What it holds |
+| -------- | ------------- |
+| [`path`](path) | \<the detail this explainer deliberately leaves out\> |

package/bundles/codex/.codex/skills/docs/tech-explainer/evals/evals.json

@@ -0,0 +1,50 @@
+{
+  "skill_name": "tech-explainer",
+  "evals": [
+    {
+      "id": 0,
+      "name": "answer-a-senior-colleagues-recommendations",
+      "prompt": "Our infra lead Priya sent three recommendations after our Postgres slowdown: (1) move the DB to NVMe, (2) bump shared_buffers to 32GB, (3) switch the connection pooler from pgbouncer to pgcat. I spent two weeks benchmarking. What I actually found: the p99 is dominated by one N+1 query in the orders service that fires ~340 round trips per page load — that's ~85% of the latency. Disk is already NVMe (she didn't know). shared_buffers helped 4% at 32GB. pgcat vs pgbouncer measured within 2%. I also had two results I had to retract along the way — my first benchmark used a warm cache so it showed a fake 3x win from shared_buffers, and I misread a pooler metric that made pgcat look 40% faster. Write this up for Priya. She's more senior than me and I need her to not feel dismissed.",
+      "expected_output": "A markdown explainer, STE, with: audience line naming Priya; vocabulary table; a ranked-effect Mermaid diagram putting the N+1 query at LAYER 1 ~85% and the pooler at the bottom with the measured 2%; a withdrawn-results section listing both retractions with what caught them; a 'where the advice is right' steelman; questions back to Priya; five-line summary.",
+      "assertions": [
+        "Contains a Mermaid flowchart TB whose subgraph titles carry effect magnitudes (e.g. LARGEST EFFECT / NO EFFECT plus a number or percentage), ordered largest effect first",
+        "The N+1 query is ranked as the largest effect and the connection pooler is ranked with its measured ~2%",
+        "All three of Priya's recommendations appear, each with a verdict and an evidence column",
+        "Contains a section that concedes where Priya is right before refuting anything",
+        "Contains a withdrawn/retracted-results section naming both wrong results and what caught each one",
+        "Contains a controlled-vocabulary table defining terms with one meaning each",
+        "Contains an audience line naming Priya and an explicit Simplified Technical English declaration",
+        "Contains a summary of about five numbered lines",
+        "No sentence exceeds 30 words in the body prose",
+        "Every headline number carries a unit and a basis (sample, date, or method)"
+      ],
+      "files": []
+    },
+    {
+      "id": 1,
+      "name": "explain-an-architecture-to-a-non-specialist",
+      "prompt": "My manager keeps asking why our nightly ETL takes 5 hours when 'it's just copying data'. Can you write something plain-English with diagrams that explains what the pipeline actually does end to end and where the 5 hours goes? Breakdown from last night's run: extract from Salesforce API 3h12m (rate limited to 100 req/min, 19k accounts), transform in dbt 41m, load to Snowflake 22m, dbt tests 45m. He's not technical but he's sharp and he'll ask good questions.",
+      "expected_output": "An explainer with a left-to-right pipeline flowchart, a pie chart of where the time goes with the run date, a vocabulary table defining rate limit / extract / transform / load / dbt, a ranked view showing the API rate limit dominates, and next steps. Should NOT invent numbers beyond those given.",
+      "assertions": [
+        "Contains a Mermaid flowchart LR showing extract -> transform -> load with the sizes on the nodes",
+        "Contains a Mermaid pie chart with showData whose slices match the given timings",
+        "Identifies the Salesforce API rate limit as the dominant cost with its share of the 5 hours",
+        "Contains a vocabulary table defining at least extract, transform, load, and rate limit",
+        "Invents no measurement not present in the prompt, or marks any inferred number as calculated",
+        "Contains a next-steps section that names which step matters most and why"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "name": "negative-should-defer-to-explainer-doc",
+      "prompt": "Write the implementation spec for the Genesys-to-warehouse ETL that we're handing to the Infosys contractor team next week. They need the DDL, the extract queries, the load procedure, the schedule, and the acceptance criteria.",
+      "expected_output": "This is a build-handoff, not an understanding document. The correct behaviour is to route to the explainer-doc skill rather than produce a tech-explainer with a vocabulary table and ranked-layer diagram.",
+      "assertions": [
+        "Does not produce a tech-explainer-shaped document (no ranked-effect layer diagram, no five-line summary)",
+        "Routes to explainer-doc or otherwise produces an actionable build spec"
+      ],
+      "files": []
+    }
+  ]
+}