skilldrop-cli 0.16.17 → 0.16.19

package/packs/dev-team/skills/devils-advocate/examples/rate-limiter-review.md

@@ -1,10 +1,9 @@
-# Worked example — adversarial review of a just-written rate limiter
+# Worked example — review of a rate limiter that "passes its tests"
 
-Input → output oracle for `devils-advocate`. Shows the four-lens sweep producing
-severity-calibrated findings with `file:line` evidence and paste-able fixes — not a
-generic "looks good, consider tests" pass.
+Input → output oracle for `devils-advocate`. Shows the answer first, findings that survive a
+trace through the code, and the cited tests judged for what they could and could not catch.
 
-## Input (the "done" implementation)
+## Input
 
 > "Implemented the per-user rate limiter, tests pass, ready for review."
 
@@ -23,24 +22,45 @@ def allow(user_id: str, rate: float, burst: float) -> bool:
     return False
 ```
 
+```python
+# test_ratelimit.py
+def test_burst_then_deny():
+    for _ in range(3):
+        assert allow("u1", rate=1, burst=3)
+    assert not allow("u1", rate=1, burst=3)
+```
+
 ## Output (the review)
 
-**Verdict: not ready — 1 blocker, 1 major.** Four lenses swept; happy path is fine, the concurrency and growth paths are not.
+**Not ready to merge.** Under concurrent requests for one user it admits more than the limit,
+and the test can't see that.
+
+1. **Race on the shared dict** — `ratelimit.py:6-10`. Two requests for the same user both read
+   `tokens=1.0`, both pass, both write back `0.0`, so parallel bursts get through at up to
+   twice the intended rate. Fix: hold a per-user lock around the read-modify-write:
 
-🟥 **Blocker — race on the shared dict (assumptions lens).** `ratelimit.py:6-11` reads then writes `_buckets[user_id]` with no lock. Two concurrent requests for the same user both read `tokens=1.0`, both pass, both write back `0.0` — the limiter leaks one token per race, so a burst of N parallel requests admits ~2× the intended rate. The "tests pass" because they're single-threaded. *Fix:* guard the read-modify-write with a per-user lock, or move to an atomic backend (Redis `INCR`+TTL). A dict-of-locks keyed by `user_id` is the minimal change.
+   ```python
+   _locks = collections.defaultdict(threading.Lock)
 
-🟧 **Major — unbounded memory growth (edge-case lens).** `_buckets` never evicts (`:1`). Every distinct `user_id` ever seen stays forever; a service facing the open internet (or spoofable user ids) OOMs over time. *Fix:* cap with an LRU (`functools.lru_cache` won't fit the mutable value — use `cachetools.TTLCache(maxsize=…, ttl=…)`), evicting idle buckets.
+   def allow(user_id, rate, burst):
+       with _locks[user_id]:
+           ...  # existing body unchanged
+   ```
 
-🟨 **Minor — first call gets a free full burst (edge-case lens).** A never-seen `user_id` starts at `(burst, now)` (`:6`), so a brand-new user can immediately spend the whole burst. If the intent is "warm up", seed at `min(burst, rate*window)` instead — flag for product, don't silently change.
+2. **Memory grows without bound** — `ratelimit.py:2`. Nothing ever leaves `_buckets`, so every
+   distinct `user_id` stays for the life of the process. Fix: a `cachetools.TTLCache` in place
+   of the dict, with a TTL longer than `burst / rate`.
 
-⚪ **Nit — `rate`/`burst` unvalidated (staff-engineer lens).** `rate<=0` freezes every user out; `burst<1` makes `allow` always false. Assert `rate>0 and burst>=1` at the boundary.
+**What the test proves.** `test_burst_then_deny` runs on one thread, so it passes with the
+race in place. It also never waits, so refill is untested. Tests that would fail today:
 
-**Test-coverage gaps (the "tests pass" were happy-path only):**
-- Concurrency: two threads hammering one `user_id` must not exceed `burst + rate*elapsed` admits.
-- Refill: after exhausting tokens, `allow` returns True again only after `1/rate` seconds.
-- Eviction: memory stays bounded under 10k distinct ids.
-- Boundary: `tokens` sitting at exactly `1.0` admits; at `0.999…` denies.
+- Ten threads calling `allow("u1", rate=1, burst=3)` at once; assert at most three return
+  `True`.
+- After draining the bucket, `allow` is false at 0.5 s and true at 1.0 s (with a patched clock).
 
 ## Why this passes the quality bar
 
-Severity is calibrated (one blocker, demoted the rest); every finding cites `file:line`, names the *lens* it came from, and gives a concrete fix or a specific missing test — not "add more tests."
+The merge answer comes first. Each finding names the line, a concrete failure and a fix as
+code. The cited test is judged for what it could catch, and the missing tests are scenarios.
+The free first burst for a new user was left out: it is a product choice, not a bug in this
+change.

package/packs/dev-team/skills/devils-advocate/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "devils-advocate",
-  "version": "0.1.2",
-  "description": "Adversarial review of just-generated code, run *after* an agent (or human) declares a feature done. Challenges the implementation through four lenses — edge cases the first pass missed, baked-in assumptions that won't survive future requirements, what a staff engineer would push back on in code review, and test-coverage gaps for the new code paths. Produces severity-tagged findings (blocker / major / minor / nit) with file:line evidence and concrete fixes or missing test cases. Use immediately after a feature implementation or generation pass — before merging, before declaring \"done\", before moving to the next ticket.",
+  "version": "0.2.0",
+  "description": "Adversarial review of a code change before it merges — the real bugs, most consequential first, each checked against the code before it is reported, with a fix that works. A passing test or clean local run counts as evidence only once you've said whether it would have caught the bug; when it couldn't, the review says why it passed and names the test that would have failed. Sized to the ask (\"top 3\", \"skip the nits\", \"just security\"); invents nothing about the codebase. Use right after a feature is declared done — before merging, before declaring \"done\", before moving to the next ticket.",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
@@ -10,5 +10,5 @@
     { "event": "pre-commit-review", "action": "devils-advocate", "description": "adversarially review staged changes before they land" }
   ],
   "tags": ["review", "code-review", "adversarial", "edge-cases", "future-proofing", "test-coverage", "dev-workflow"],
-  "model": { "tier": "heavy", "rationale": "Adversarial code review across four lenses. Cheaper models miss edge cases and under-call severity. Never downgrade." }
+  "model": { "tier": "heavy", "rationale": "Adversarial code review that must trace each finding and judge what the tests prove. Cheaper models miss edge cases and report false positives. Never downgrade." }
 }

package/packs/stakeholder-comms/skills/guide-builder/SKILL.md

@@ -1,68 +1,65 @@
 ---
 name: guide-builder
-description: Turn raw notes, specs, or design material into an easy-to-follow guide, auto-styled to the content — a setup/quickstart, a design walkthrough, or an API/event-schema reference. Use when the user wants setup or getting-started instructions, an onboarding walkthrough of how a system works, or developer reference docs for an API or event schema — and it is NOT an SRE operational runbook (use runbook-generator) or a design proposal for review (use design-doc).
+description: Turn raw notes, a spec, a thread or a messy procedure into a guide someone else can follow — a setup guide, a how-to, an onboarding walkthrough, or a reference for developers — in the length and voice its reader needs. Holds only what the notes say, marks anything inferred where it appears, orders steps so nothing is used before it is set up, and keeps open questions out of the guide so it can be sent as it stands. Use when the user wants setup or getting-started instructions, a walkthrough of how something works, or reference docs for an API or event schema — and it is NOT an SRE operational runbook (use runbook-generator) or a design proposal for review (use design-doc).
 ---
 
 # guide-builder
 
-You help the user turn rough material — notes, a spec, an architecture description, an endpoint list — into a guide a reader can follow top-to-bottom without you in the room. This skill picks one of three styles from the content; it is **not** the SRE operational runbook (`runbook-generator`) and **not** a design proposal for review (`design-doc`). It explains and instructs; it does not propose or page.
+**The rule: the guide holds only what the notes say.** A guide is followed literally. The
+agent's habit is to make it feel complete: a confirmation message nobody mentioned ("you
+should see *Connected*"), a menu path from a different version, "required" on every field, a
+retry policy that sounds standard. Each invented detail is a step the reader will look for
+and not find. So every fact comes from the material. An inference from it (a unit read off a
+sample value, the likely meaning of a field) is marked as an inference where it appears:
+✅ *"`ts` looks like seconds since 1970, judging by the sample; confirm before relying on
+it."*
+
+A second rule: **the guide can be sent as it stands.** Questions for the person who asked,
+internal notes, "confirm with engineering" and to-do markers go in your reply, never in the
+guide. Where the reader will need something the notes don't settle, the guide tells the
+*reader* who to ask, if the notes say who: ✅ *"Your login for the booking system comes from
+the office manager."*
 
 ## How to respond
 
-**Four rules come before the steps and outrank them:**
+1. **Write for the reader they named, at the size asked for.** A README section, a page for a
+   new starter, a sheet for volunteers, a reference for developers: that sets the voice,
+   length and shape. Short asks get short guides.
 
-- **Answer what was asked, first.** Open with the answer, the decision or the artifact, in plain words. Scores, matrices, frameworks and tags come after it, and anything that doesn't change the answer is cut.
-- **Use only what you were given.** Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
-- **Deliver from what you have.** When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
-- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
-- **For this skill:** Turn the notes into the guide and stop. No endpoints, expected outputs, time estimates, troubleshooting rows or teardown steps that are not in the notes, and no warnings or to-do markers inside the guide.
+2. **Order by dependency, not by the notes.** Nothing is used before the step that sets it
+   up: an account before signing in with it, a password store before the password goes in.
+   Notes are usually written in the order things were remembered; the guide follows the
+   order they have to be done.
 
-1. **Detect the style first, and say which you picked.** Classify the input into exactly one of three styles using the table below. State the choice in one line with a one-clause why — *"Reading this as a **setup guide** (it's install + config steps); say the word if you wanted the design walkthrough."* — so the user can redirect before you draft.
+3. **One action per step, with a way to tell it worked when the notes give one.** Number the
+   steps. Split compound ones. Add a success check only where the notes say what success
+   looks like; don't invent screens, messages or outputs.
 
-   | Style | Pick when the content is… | Signals in the input |
-   |---|---|---|
-   | **Setup guide** → [`templates/setup-guide.md`](templates/setup-guide.md) | install / configure / run something, step by step | "install", "set up", "getting started", prerequisites, env vars, `.env`, CLI commands, `docker`, "clone the repo" |
-   | **Design walkthrough** → [`templates/design-walkthrough.md`](templates/design-walkthrough.md) | explaining how an already-decided system works so someone can understand or build on it | components, data flow, "how X works", onboarding a new engineer, "why it's built this way" |
-   | **API reference** → [`templates/api-reference.md`](templates/api-reference.md) | contracts other developers code against | endpoints, request/response shapes, OpenAPI, event names, payload schemas, status codes, webhooks, Kafka/SNS topics, JSON Schema |
+4. **For developer references, the contract as given.** Each endpoint, event or field with
+   what the notes say about it: type, whether it's required, meaning, an example where the
+   notes have one. Where the notes don't say whether a field is required or what a value
+   means, the reference says that, rather than guessing. Error responses only as documented.
 
-2. **Handle mixed content by picking the dominant style, not blending.** If the input spans two styles (e.g. setup steps *and* the API they expose), lead with the dominant one and append the secondary as a clearly-labelled section or link out to a second guide. Only ask the user which to lead with if it's a genuine 50/50.
+5. **What the notes don't cover stays out.** A feature people have asked about but the notes
+   don't describe, steps for a device or tool the notes never mention, a header name or host
+   nobody wrote down: leave them out of the guide, and name them once in your reply.
 
-3. **Gather only what the chosen style can't do without.** Don't run a generic intake. Cap at 2 questions, pick defaults for the rest:
-   - **Setup guide** needs the *target end state* ("running locally" vs "deployed to staging") and the *prerequisites baseline*. Without an end state, a setup guide has no finish line.
-   - **Design walkthrough** needs *who it's for* (new hire vs adjacent team) and *what they should be able to do after reading*.
-   - **API reference** needs the *transport + auth model* and *versioning scheme*. Without auth, the examples are unrunnable.
-
-   If the source is genuinely too thin, say so once and draft with gaps flagged as `> ⚠️ NEEDS INPUT: …` — don't invent.
-
-4. **Fill the matching template.** Each template is ordered the way a reader actually consumes it. Don't reorder sections to match the input's order; reorder the input to match the reader's path.
-
-5. **Apply the universal easy-to-follow rules** (these are the spine of every style):
-   - **One action per step.** Number them. No compound step hiding three commands behind one number.
-   - **Every step ends in a check.** "You should see `Listening on :3000`." A step with no success signal can't tell the reader whether to continue or stop.
-   - **Commands are complete and paste-able.** Real flags, not pseudocode. Placeholders are unmistakable (`<YOUR_API_KEY>`, never `your-key-here` buried mid-line) and listed once up front.
-   - **Lead each section with the outcome, not the backstory.** "By the end of this section the service answers on localhost." The "why" belongs in a walkthrough, not a quickstart.
-   - **Front-load the happy path.** Push edge cases, troubleshooting, and teardown to the end.
-
-## Useful references in this skill
-
-- [`templates/setup-guide.md`](templates/setup-guide.md) — install/configure/run, prerequisites → verify → troubleshooting.
-- [`templates/design-walkthrough.md`](templates/design-walkthrough.md) — mental model → components → flow → key decisions → where the code lives.
-- [`templates/api-reference.md`](templates/api-reference.md) — conventions → per-endpoint/event contracts → error catalog → changelog.
-- [`examples/local-setup-guide.md`](examples/local-setup-guide.md) — raw notes → a finished setup guide, showing the detection call and the verify-after-every-step discipline.
+6. **Deliver from what you have.** With notes to work from, write the guide and state any
+   assumption about the reader in one line. Ask first only when there is nothing to work from.
 
 ## Quality bar
 
-- **A reader who follows top-to-bottom reaches the stated end state without leaving the doc for missing info.** Unstated prerequisites are the #1 failure — hunt them down.
-- **Every command block has an expected result or a verification step.** A command with no "how do I know it worked" is incomplete.
-- **Placeholders are unmistakable and listed once up front.** `<YOUR_API_KEY>`, not a real-looking string the reader pastes verbatim and wonders why it fails.
-- **No forward references that break linear reading.** "See step 7" before step 7 means the order is wrong, or it needs a link.
-- **API reference: every field has type + required/optional + a one-line meaning; every endpoint has ≥1 full example request and response, including at least one error response.**
-- **The detected style is stated up front with a one-line why,** so the user can redirect in one message instead of getting the wrong artifact.
+- **Every fact in the guide is in the notes;** every inference is marked where it appears.
+- **The guide can be sent as written:** no questions, internal notes or to-do markers in it.
+- **A reader following top to bottom never uses something before it is set up.**
+- **One action per step;** success checks only where the notes give them.
+- **References say "not stated" rather than guessing types, required fields or meanings.**
+- **Length and voice fit the reader asked for.**
 
 ## When to use this skill
 
 - ✅ "Write setup instructions for getting our service running locally."
-- ✅ "Turn this architecture description into an onboarding walkthrough for new engineers."
+- ✅ "Turn this description into an onboarding walkthrough for new staff."
 - ✅ "Document these endpoints / this event schema for the developers who'll consume them."
 - ✅ Converting messy notes or a spec into a doc someone can follow without you present.
 
@@ -75,11 +72,13 @@ You help the user turn rough material — notes, a spec, an architecture descrip
 
 ## Anti-patterns to avoid
 
-- ❌ Compound steps. "Install deps, configure the DB, and run migrations" as one numbered step — split into three.
-- ❌ Commands with no expected output. The reader can't tell success from a silent failure.
-- ❌ Backstory before the first actionable step in a setup guide. Save the "why" for a walkthrough.
-- ❌ Documenting an API in prose ("it returns the user object") instead of a typed schema + example payload.
-- ❌ Blending two styles into one undifferentiated doc. Pick the dominant style; link or append the rest.
-- ❌ Optimistic examples that omit the error/failure responses an API consumer is required to handle.
-- ❌ Reinventing `runbook-generator` (incident playbooks, on-call) or `design-doc` (alternatives, approval) — stay in the explain-and-follow lane.
-- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.
+- ❌ **The plausible detail.** A success message, a default, a menu path or a retry count the
+  notes never mention.
+- ❌ **Notes to the requester inside the guide.** "Internal: confirm with eng before sending."
+- ❌ **Steps for what the notes don't cover,** written from general knowledge because the
+  reader will need them. Tell the reader who to ask instead.
+- ❌ **Template sections on a small ask.** "Mental model", "Data & state", "Where it runs" for a
+  five-line description.
+- ❌ **"Required: yes" on every field** because the column needed filling.
+- ❌ **Compound steps.** Three commands behind one number.
+- ❌ **Announcing your approach.** "Reading this as a setup guide…" — just write it.

package/packs/stakeholder-comms/skills/guide-builder/evals/evals.json

@@ -72,6 +72,33 @@
         "It does not invent a queue or topic name, how often events are sent, delivery guarantees, value ranges stated as fact, or fields that are not in the sample",
         "The reference is about a page or less, with no sections on things that were not supplied such as authentication, retries or versioning"
       ]
+    },
+    {
+      "id": 6,
+      "held_out": "2026-10-17",
+      "prompt": "Can you turn setup-notes.md and thread.txt into a setup guide for Wren? She's a new analyst starting Monday and needs to get Larkspur running on her laptop on day one without pinging anyone. She's fine in a terminal but has never seen our stack. Something she can follow in one sitting, under 600 words.",
+      "assertions": [
+        "The steps run in an order that works: lark-analysts access is requested up front, `lark runtime start` comes before `lark db init`, the database is initialised before `lark seed`, and the config file is created before `lark login`, which comes before `lark sync`, even though the notes put seeding first",
+        "The local database port is given as 6543, the 2.4 default from the thread, and 5433 is not presented as the current port",
+        "`lark deploy --prod` does not appear as a step, and the lunch chat is left out",
+        "If the guide says the login can stop working and need `lark login` again, it is marked as one colleague's experience rather than stated as documented behaviour",
+        "It does not invent a region or workspace value, a VPN requirement either way, or any command, flag, file path, error message or timing not in the two files",
+        "The guide is delivered without stopping to ask first, and the unanswered questions (which region Wren should use, whether sync needs the VPN off-site) are raised to the requester outside the guide rather than answered by guesswork inside it",
+        "The guide is under 600 words"
+      ]
+    },
+    {
+      "id": 7,
+      "held_out": "2026-10-17",
+      "prompt": "hi, I do the welcome stuff for Brackenhill Allotment Association. can you make this into a short welcome guide for new plot holders? half a page max, they're mostly retirees and young families, not techy at all.\n\nshed key is in the lockbox by the gate, code is on the welcome sheet. water troughs get turned on in april by whoever's on the rota. sign the tool book when you borrow anything. bonfires NOT allowed, council letter last yr. compost bays - green bin is for weeds, the wooden ones for everything else? not sure tbh ask Derek. new folk do their induction walk with a committee member before they get a key",
+      "assertions": [
+        "The induction walk with a committee member comes before getting the key or using the lockbox, even though the notes mention the key first",
+        "It does not invent the lockbox code, a date for the water going on, rota names, contact details for Derek or anyone else, rent, opening hours, penalties or any rule not in the notes",
+        "The compost-bay split is not stated as a settled rule in the guide, and the requester is told outside the guide that it needs confirming with Derek",
+        "The bonfire ban and signing the tool book are both included as clear rules",
+        "It is written in plain everyday language a non-technical newcomer can follow, with no jargon or committee shorthand left unexplained",
+        "The guide fits in about half a page (roughly 250 words or fewer) and is delivered without stopping to ask questions first"
+      ]
     }
   ]
 }

package/packs/stakeholder-comms/skills/guide-builder/evals/files/6/setup-notes.md

@@ -0,0 +1,11 @@
+# larkspur local setup - rough notes (Tobin, not tidied)
+
+- `lark seed --sample` loads the sample dataset so you have tables to query. do this first thing so there's something to look at
+- install the CLI from the intranet: Fenmoor Hub > Tools > Larkspur CLI, run the installer. check with `lark --version`, should be 2.4 or later
+- seed writes into your local db, so you need one: `lark db init` (creates it on port 5433)
+- db init only works if the local runtime is up: `lark runtime start`
+- config lives at ~/.lark/config.toml. clone the larkspur-starter repo, copy config.example.toml to ~/.lark/config.toml, fill in `workspace` and `region`
+- `lark login` opens the browser for SSO. it reads workspace from the config file so the config has to exist first or it errors
+- you must be in the lark-analysts group or login fails with "not authorised". Ines on the platform team adds people. can take up to a working day so ideally request before day one
+- after login, `lark sync` pulls the shared dimension tables. first sync takes about 10 min, later ones are quick
+- `lark status` shows runtime, db and login state if something looks off

package/packs/stakeholder-comms/skills/guide-builder/evals/files/6/thread.txt

@@ -0,0 +1,13 @@
+#data-onboarding (export)
+
+Tobin: pinned my setup notes for whoever starts next. local db is on 5433 btw
+Mara: heads up, since 2.4 `lark db init` defaults to 6543. 5433 kept clashing with other stuff on people's machines
+Tobin: ah yes, my notes predate that. 6543 it is
+Pell: what region do new people put in the config? I just copied mine from someone
+Tobin: depends which team they land on. I'll check for Wren and get back to you
+Pell: also does `lark sync` need the VPN on? I think it does when I'm off-site but not 100%
+Mara: no idea, haven't worked from home in ages
+Pell: fwiw my login stopped working after the long weekend, had to run `lark login` again
+Mara: reminder for platform folks only: `lark deploy --prod` is still frozen until the migration is signed off, don't run it
+Tobin: lunch at 12:30 anyone?
+Mara: yes

package/packs/stakeholder-comms/skills/guide-builder/manifest.json

@@ -1,11 +1,11 @@
 {
   "name": "guide-builder",
-  "version": "0.1.2",
-  "description": "Turn raw notes, specs, or design material into an easy-to-follow guide, auto-styled to the content — a setup/quickstart, a design walkthrough, or an API/event-schema reference. Use when the user wants setup or getting-started instructions, an onboarding walkthrough of how a system works, or developer reference docs for an API or event schema — and it is NOT an SRE operational runbook (use runbook-generator) or a design proposal for review (use design-doc).",
+  "version": "0.2.0",
+  "description": "Turn raw notes, a spec, a thread or a messy procedure into a guide someone else can follow — a setup guide, a how-to, an onboarding walkthrough, or a reference for developers — in the length and voice its reader needs. Holds only what the notes say, marks anything inferred where it appears, orders steps so nothing is used before it is set up, and keeps open questions out of the guide so it can be sent as it stands. Use when the user wants setup or getting-started instructions, a walkthrough of how something works, or reference docs for an API or event schema — and it is NOT an SRE operational runbook (use runbook-generator) or a design proposal for review (use design-doc).",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["brief-intake", "design-doc", "exec-summary", "runbook-generator"],
   "tags": ["guide", "setup", "documentation", "api-reference", "onboarding", "walkthrough"],
-  "model": { "tier": "standard", "rationale": "Shapes notes into a styled guide. Generation, not adversarial review." }
+  "model": { "tier": "standard", "rationale": "Shapes notes into a guide without adding to them. Generation, not adversarial review." }
 }

package/packs/dev-team/skills/devils-advocate/templates/challenge.md

@@ -1,118 +0,0 @@
-# Devil's advocate: {feature name or PR title}
-
-_Scope: {N files, M lines changed in the diff under review}_
-_Reviewed: {YYYY-MM-DD}_
-_Code shape(s): {endpoint | async handler | migration | state machine | parser | CLI | UI | background job | library | config}_
-
-## Verdict
-**{SHIP IT | SHIP WITH FIXES | DO NOT MERGE | RECONSIDER APPROACH}** — {N} blocker · {N} major · {N} minor · {N} nit
-
-{3-sentence summary. Lead with the worst finding. Name the lens(es) that surfaced the most issues. If the verdict is `RECONSIDER APPROACH`, say *why* — what's the structural problem the findings point to.}
-
----
-
-## Findings by lens
-
-### 1. 🔍 Edge cases the first pass missed
-
-#### 🟥 Blockers
-1. **Where:** `{file:line}` — *`{≤15 char quoted snippet}`*
-   **What:** {one sentence — which check from the edge-cases lens fired}
-   **Scenario:** {concrete reproducible case, e.g. "POST /checkout with `body = {}` → `applyDiscount(undefined)` → TypeError at line 47"}
-   **Fix:** {one or two sentences, concrete and paste-able where possible}
-
-#### 🟧 Major
-1. **Where:** `{file:line}` — *`{snippet}`*
-   **What:** {…}
-   **Scenario:** {…}
-   **Fix:** {…}
-
-#### 🟨 Minor
-1. {…}
-
-#### ⚪ Nits
-- {…}
-
----
-
-### 2. 🔭 Future-proofing — assumptions baked in
-
-#### 🟥 Blockers
-1. **Where:** `{file:line}` — *`{snippet}`*
-   **What:** {assumption that will break — e.g. "Hard-coded 100ms timeout"}
-   **When it bites:** {realistic timeframe — e.g. "p99 latency from `payments-svc` already at 80ms; one more downstream hop and the deploy fails"}
-   **Fix:** {…}
-
-#### 🟧 Major
-1. {…}
-
-#### 🟨 Minor
-1. {…}
-
----
-
-### 3. ⚔️ Adversarial — what a staff engineer would push back on
-
-#### 🟥 Blockers
-1. **Where:** `{file:line}` — *`{snippet}`*
-   **What:** {category — concurrency / error handling / security / observability / blast radius}
-   **Scenario:** {how it actually fails — "two callers run `incrementBalance` in parallel, both read balance=100, both write balance=101 → $10 lost"}
-   **Fix:** {…}
-
-#### 🟧 Major
-1. {…}
-
-#### 🟨 Minor
-1. {…}
-
-#### ⚪ Nits
-- {…}
-
----
-
-### 4. 🧪 Test-coverage gaps
-
-For each gap: scenario → suggested location → severity.
-
-#### 🟥 Blockers
-1. **Missing test:** {scenario, e.g. "POST /checkout with missing auth header — expect 401"}
-   **Suggested location:** `{path/to/test/file}`
-   **Why blocker:** {e.g. "auth check is the only thing between this endpoint and arbitrary user data; no test guards against future refactors removing it"}
-
-#### 🟧 Major
-1. **Missing test:** {scenario}
-   **Suggested location:** `{path}`
-   **Why major:** {…}
-
-#### 🟨 Minor (additional cases worth adding)
-- {one-liner per case}
-
-#### Test smells (existing tests that don't earn their keep)
-- **`{test file:line}`** — *`{snippet of the test}`* — {smell, e.g. "asserts nothing — calls `applyDiscount(10)` but doesn't check the return value"} — **Fix:** {what it should assert}
-
----
-
-## ✅ What's solid
-
-Things the implementation got right — worth preserving in any rewrite, and worth re-using as patterns elsewhere in the change.
-
-- **{Strength 1}** — `{file:line}` — {why this is a real strength, not flattery}
-- **{Strength 2}** — `{file:line}` — {…}
-- **{Strength 3}** — `{file:line}` — {…}
-
----
-
-## 🛠 Suggested order to address
-
-1. **Fix blockers first.** {Specifically: {finding refs}}
-2. **Add the missing tests in §4.** They double as regression catches for the fixes above.
-3. **Major findings in priority order:** {finding refs, ordered by likelihood-of-biting × cost-to-fix-later}
-4. **Minor + nits:** {batch into a follow-up commit or punt to a separate cleanup PR — don't gate the merge}
-
----
-
-## 🚦 Re-review trigger
-
-After fixes land, the changes most likely to *introduce new findings* are:
-- {e.g. "The retry logic added to address Blocker #2 needs a fresh sweep of Lens 1 (edge cases) for retry storm + idempotency."}
-- {e.g. "The new feature flag added per the 'blast radius' finding needs a Lens 2 check that the flag has an off-switch and an expiry."}

package/packs/stakeholder-comms/skills/guide-builder/examples/local-setup-guide.md

@@ -1,127 +0,0 @@
-# Example: raw notes → setup guide
-
-Shows the two things that make this skill earn its keep: the **style-detection call up front**, and the **verify-after-every-step** discipline that turns notes into something a stranger can follow.
-
----
-
-## Input (what the user pasted)
-
-> need a getting-started doc for `widget-api`. it's a Go service, needs Postgres 15. clone, copy the env file (need a STRIPE_KEY from the dashboard), `make deps`, bring up postgres with docker, `make migrate`, then `make run`. it serves on 8080. there's a `/healthz`. people keep forgetting to start postgres first and then complain migrate hangs.
-
-## The skill's first line back (style detection)
-
-> Reading this as a **setup guide** — it's clone → configure → run with a defined finish line (`/healthz` answering). Two things I'm filling with defaults; correct me if wrong: end state is **running locally** (not deployed), and the prerequisite baseline assumes Go and Docker are already installed. Drafting now.
-
-## Output
-
----
-
-# widget-api — Setup guide
-
-**Goal:** Run `widget-api` locally against a Dockerized Postgres and get a healthy response from `/healthz`.
-**Time:** ~10 minutes
-**You'll have at the end:** the API serving on `localhost:8080` with migrations applied.
-
-## Placeholders used in this guide
-
-| Placeholder | What to put | Where to get it |
-|---|---|---|
-| `<STRIPE_KEY>` | Stripe secret key for the test mode | Stripe Dashboard → Developers → API keys |
-
-## Prerequisites
-
-| Need | Version | Check it | If missing |
-|---|---|---|---|
-| Go | `>= 1.22` | `go version` | https://go.dev/dl |
-| Docker | any recent | `docker --version` | https://docs.docker.com/get-docker |
-| Postgres image | 15 | (pulled in step 3) | — |
-
-## Steps
-
-### 1. Clone the repo and enter it
-
-```bash
-git clone git@github.com:example/widget-api.git && cd widget-api
-```
-
-**You should see:** a `Makefile` in the directory — `ls Makefile`.
-
-### 2. Configure environment
-
-```bash
-cp .env.example .env
-# then set in .env:
-#   STRIPE_KEY=<STRIPE_KEY>
-```
-
-**You should see:** no placeholders left — `grep '<' .env` returns nothing.
-
-### 3. Start Postgres (do this before migrating)
-
-```bash
-docker compose up -d postgres
-```
-
-**You should see:** `docker compose ps` lists `postgres` as `healthy`. Wait for `healthy` before the next step — migrating against a not-yet-ready Postgres is what makes `make migrate` appear to hang.
-
-### 4. Install Go dependencies
-
-```bash
-make deps
-```
-
-**You should see:** `go mod download` completes with no errors.
-
-### 5. Run migrations
-
-```bash
-make migrate
-```
-
-**You should see:** `migrations applied: N` and a return to the prompt within a few seconds.
-
-### 6. Start the service
-
-```bash
-make run
-```
-
-**You should see:** `widget-api listening on :8080`.
-
-## Verify it works
-
-```bash
-curl -s localhost:8080/healthz
-```
-
-**Expected:** `{"status":"ok","db":"connected"}`
-
-## Troubleshooting
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| `make migrate` hangs | Postgres not `healthy` yet | Re-check step 3; wait for `healthy`, then retry |
-| `connection refused :5432` | Postgres container not up | `docker compose up -d postgres` |
-| `/healthz` returns `db:"down"` | migrations not applied | run step 5 |
-
-## Teardown
-
-```bash
-docker compose down -v
-```
-
-Removes the Postgres container and its volume. Your `.env` is left intact.
-
-## Next steps
-
-- Run the tests: `make test`
-- Reference for the endpoints this service exposes: generate one with `/guide-builder` in **API reference** style.
-
----
-
-### Why this passes the quality bar
-
-- **Every step ends in a check** — the reader never guesses whether to continue.
-- **The one gotcha from the notes** ("people forget to start postgres") became step 3's check *and* the first troubleshooting row, instead of buried prose.
-- **The single placeholder is listed once up front**, not left as a surprise mid-command.
-- **One end-to-end verify** (`/healthz`) proves the whole chain, not just the last command.