@caddis/cli 0.4.0 → 0.4.2

package/bundles/antigravity-plugin/skills/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/antigravity-plugin/skills/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": []
+    }
+  ]
+}

package/bundles/antigravity-plugin/skills/tech-explainer/references/diagrams.md

@@ -0,0 +1,237 @@
+# Diagram vocabulary for explainers
+
+Four Mermaid patterns cover almost every explainer. Reusing a small set is deliberate: the reader
+learns the visual grammar once, in §3, and reads every later diagram faster because of it. A document
+where each diagram is a different Mermaid type makes the reader re-learn the notation five times.
+
+## Contents
+
+- [Rule zero: does this diagram earn its place?](#rule-zero-does-this-diagram-earn-its-place)
+- [Pattern 1 — the pipeline (`flowchart LR`)](#pattern-1--the-pipeline-flowchart-lr)
+- [Pattern 2 — the layer stack (`flowchart TB` + subgraphs)](#pattern-2--the-layer-stack-flowchart-tb--subgraphs)
+- [Pattern 3 — the ranked-effect diagram (the important one)](#pattern-3--the-ranked-effect-diagram-the-important-one)
+- [Pattern 4 — the check loop](#pattern-4--the-check-loop)
+- [Pattern 5 — proportion (`pie showData`)](#pattern-5--proportion-pie-showdata)
+- [Pattern 6 — the next-steps chain](#pattern-6--the-next-steps-chain)
+- [Syntax notes that bite](#syntax-notes-that-bite)
+
+## Rule zero: does this diagram earn its place?
+
+Delete the diagram if a table says it better. Diagrams carry **shape and relationship**; tables carry
+**detail and comparison**. A diagram listing five options with three attributes each is a table drawn
+badly.
+
+Four to six diagrams across a long document is right. Every one should answer a different question.
+
+## Pattern 1 — the pipeline (`flowchart LR`)
+
+For §3, "what we are building". Left to right, one path, database shapes for stores. Put the size of
+the data on the arrows or in the nodes — the reader's first question about a pipeline is "how big".
+
+````markdown
+```mermaid
+flowchart LR
+    DB[("Customer<br/>database")] --> P["Build the prompt<br/>about 16,400 tokens"]
+    P --> S["LLM server<br/>on the H100 GPU"]
+    S --> J["JSON summary<br/>about 2,400 tokens"]
+    J --> O[("Stored<br/>summary")]
+```
+````
+
+Keep it to five or six nodes. A pipeline diagram with fifteen boxes is an architecture diagram, and
+the reader stops tracing it.
+
+## Pattern 2 — the layer stack (`flowchart TB` + subgraphs)
+
+For §5, "what sits on what". One subgraph per layer, numbered and named. Peers go side by side inside
+their layer with `direction LR`. Mark what you do **not** have — the absence is often the reader's
+actual question.
+
+````markdown
+```mermaid
+flowchart TB
+    subgraph programs["LAYER 1 — Programs (the wrapper you install)"]
+        direction LR
+        A["<b>Ollama</b><br/>installed and used"]
+        B["<b>llama-server</b><br/>installed and used"]
+        C["<b>LM Studio</b><br/>NOT installed"]
+    end
+
+    subgraph engine["LAYER 2 — Engine (this does the real work)"]
+        D["<b>llama.cpp / ggml</b><br/>CUDA calculation code"]
+    end
+
+    subgraph driver["LAYER 3 — Driver"]
+        E["NVIDIA driver, TCC mode"]
+    end
+
+    subgraph hardware["LAYER 4 — Hardware"]
+        F["H100 NVL GPU<br/>94 GB memory"]
+    end
+
+    A --> D
+    B --> D
+    C -.->|"would use the<br/>same engine"| D
+    D --> E
+    E --> F
+```
+````
+
+Two techniques here do real work:
+
+- **The dotted arrow with a label** (`C -.->|"would use the same engine"| D`) shows a hypothetical
+  without asserting it exists. This is how you answer "what if we used X?" inside the diagram.
+- **The parenthetical in each subgraph title** ("the wrapper you install", "this does the real work")
+  tells the reader what the layer *is for*, which is what they actually lack.
+
+Follow the diagram with the one-line consequence: *"Layer 1 is easy to change. Layer 2 decides the
+speed."*
+
+## Pattern 3 — the ranked-effect diagram (the important one)
+
+For §8, "what limits the result". This is the diagram the document exists to deliver. It is the layer
+stack again, but **ordered by size of effect and labelled with the magnitude**.
+
+````markdown
+```mermaid
+flowchart TB
+    subgraph L1["LAYER 1 — The model — LARGEST EFFECT — about 3x"]
+        M["<b>gpt-oss:120b writes 6,000 to 9,000 tokens.</b><br/>gpt-4o writes 2,373 tokens for the same job.<br/>The local model does about 3 times more work."]
+    end
+    subgraph L2["LAYER 2 — The engine — MEDIUM EFFECT — tens of percent"]
+        E["<b>llama.cpp has no Hopper-specific code.</b><br/>It cannot use the H100 FP8 units.<br/>Faster engines (vLLM, TensorRT-LLM) do not run on Windows."]
+    end
+    subgraph L3["LAYER 3 — The program — SMALL EFFECT — under 5%"]
+        W["<b>Ollama or llama-server or LM Studio.</b><br/>All contain the same engine.<br/>Measured difference is small."]
+    end
+    subgraph L4["LAYER 4 — The operating system — NO EFFECT"]
+        O["<b>Windows against Linux.</b><br/>For work held fully in GPU memory,<br/>measured difference is about zero."]
+    end
+    L1 --> L2 --> L3 --> L4
+```
+````
+
+Construction rules:
+
+- **Title format:** `LAYER n — <the thing> — <EFFECT SIZE IN CAPS> — <the number>`. The caps and the
+  number are what the reader takes away; the layer number just keeps the ordering legible.
+- **Node body:** bold first line = the claim. Following lines = the evidence and the comparison. Three
+  lines per node is the ceiling.
+- **The arrows mean rank, not flow.** `L1 --> L2 --> L3 --> L4` reads as descending importance. Say so
+  in the sentence above the diagram so nobody reads it as a data path.
+- **Include the reader's preferred fix even when it ranks last.** Omitting it looks like evasion;
+  ranking it with a measured number is the argument.
+- **A layer you did not measure says so** — "NOT MEASURED" is an honest rank. An invented one is the
+  fastest way to lose the reader who happens to know that layer.
+
+Always follow it with the reading instruction:
+
+> **Read the diagram this way.** If we change the program (Layer 3), we gain a few percent. If we
+> change the model (Layer 1), we can gain about 3 times. Layer 1 is where the work must go.
+
+### The same move outside the "stack" case
+
+Nothing here depends on the causes forming a real stack. When they do not, call them causes and rank
+them by measured share — the diagram does exactly the same job:
+
+````markdown
+```mermaid
+flowchart TB
+    subgraph L1["CAUSE 1 — The Salesforce rate limit — LARGEST EFFECT — 192 of 300 minutes, 64.0%"]
+        A["<b>19,000 accounts at 100 requests per minute needs 190 minutes.</b><br/>The extract took 192 minutes.<br/>It already runs at 99% of the permitted rate."]
+    end
+    subgraph L2["CAUSE 2 — The dbt tests — SECOND EFFECT — 45 of 300 minutes, 15.0%"]
+        B["<b>780 tests run after every load.</b><br/>Not yet split by severity."]
+    end
+    subgraph L3["CAUSE 3 — The load into Snowflake — SMALLEST EFFECT — 22 of 300 minutes, 7.3%"]
+        C["<b>This is the step people call 'copying the data'.</b><br/>It is 7.3% of the run."]
+    end
+    L1 --> L2 --> L3
+```
+````
+
+Note the third node: the reader's own mental model ("it's just copying data") is named and ranked
+rather than dismissed. That is the move, in one box.
+
+## Pattern 4 — the check loop
+
+For §6, "why the work took so long" — the procedure that catches bad results. A decision diamond with
+a failure branch that loops back.
+
+````markdown
+```mermaid
+flowchart LR
+    A["Change one thing"] --> B["Measure it"]
+    B --> C{"Does the number agree<br/>with a second,<br/>independent number?"}
+    C -->|"No"| D["The instrument is wrong.<br/>Repair the test."]
+    D --> B
+    C -->|"Yes"| E["Record the result"]
+```
+````
+
+The loop-back arrow is the content. It shows that the failure path is normal and expected, which is
+what makes the withdrawn-results list read as rigour instead of incompetence.
+
+## Pattern 5 — proportion (`pie showData`)
+
+For §7, "where the time goes". Use it when the reader is about to optimise the small slice.
+
+````markdown
+```mermaid
+pie showData
+    title Time in one call
+    "Decode — write the answer" : 91.6
+    "Prefill — read the prompt" : 8.4
+```
+````
+
+- `showData` prints the values — always use it; an unlabelled pie is a decoration.
+- Up to five slices. Above five, use a table — the labels stop fitting and the small slices become
+  indistinguishable. If the natural breakdown is four or five stages, the pie is still the right
+  visual; do not split it artificially.
+- **Say what the numbers are drawn from**, in the sentence above: a sample count where you have one
+  (*"We measured 223 samples of each stage"*), otherwise the single run and its date (*"From the run
+  of 2026-08-06"*). A one-run pie is honest as long as it says it is one run — a pie with no stated
+  basis is the single easiest thing in the document to misquote.
+- Follow with the consequence: *"Earlier work tried to make prompt reading faster. That work can only
+  improve 8.4% of the time."*
+
+## Pattern 6 — the next-steps chain
+
+For §11. Numbered steps, top to bottom, each with its method and its acceptance in the node.
+
+````markdown
+```mermaid
+flowchart TB
+    A["<b>Step 1 — Test other models</b><br/>Find a model that writes shorter answers.<br/>Measure tokens per call, not tokens per second."] --> B
+    B["<b>Step 2 — Quality gate</b><br/>Check that the local model writes<br/>summaries that are good enough.<br/>15 test cases."] --> C
+    C["<b>Step 3 — Make it a service</b><br/>Run the server with NSSM.<br/>Confirm the GPU works from a service."]
+```
+````
+
+Name the step that matters most immediately below, with the reason: *"Step 1 is the most important
+step. The model decides about 3 times the work. No change to the server software can equal that."*
+
+## Syntax notes that bite
+
+| Need                    | Write                                        | Note                                                                 |
+| ----------------------- | -------------------------------------------- | -------------------------------------------------------------------- |
+| Line break in a node    | `<br/>`                                      | Not `\n`. Renderers differ on `<br>` without the slash.              |
+| Bold inside a node      | `["<b>Claim.</b><br/>Evidence."]`            | Markdown `**` does not render inside Mermaid nodes.                  |
+| Any label with punctuation | Wrap in double quotes: `A["a, b: c"]`     | Unquoted `(`, `,`, `:`, `-` break the parser.                        |
+| Database / store shape  | `DB[("Customer<br/>database")]`              |                                                                      |
+| Decision                | `C{"Does it agree?"}`                        |                                                                      |
+| Hypothetical / optional | `C -.->|"would use"| D`                      | Dotted = does not exist today.                                       |
+| Peers side by side      | `direction LR` inside the `subgraph`         | Without it, subgraph children stack vertically.                      |
+| Subgraph with a title   | `subgraph id["The title text"]`              | The bare form `subgraph The title` mangles punctuation.              |
+
+Check every diagram renders before shipping — a broken Mermaid block shows the reader raw source and
+costs more credibility than the diagram was worth. In order of preference:
+
+1. **Paste into `mermaid.live`** — authoritative, and it points at the failing line.
+2. **VS Code / GitHub / GitLab preview** — all render every pattern above.
+3. **If you are offline**, read each block against the table above. Nearly every failure is one of
+   four things: an unquoted label containing `(`, `,`, `:` or `-`; a `<br>` without the slash;
+   markdown `**bold**` inside a node; or a `subgraph` title that is not bracketed and quoted.
+
+Do not ship a diagram you have not checked by one of these three.