skilldrop-cli 0.16.16 → 0.16.18

package/model-routing.json

@@ -232,7 +232,7 @@
     },
     "guide-builder": {
       "tier": "standard",
-      "rationale": "Shapes notes into a styled guide. Generation, not adversarial review."
+      "rationale": "Shapes notes into a guide without adding to them. Generation, not adversarial review."
     },
     "reverse-architecture": {
       "tier": "standard",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.16.16",
+  "version": "0.16.18",
   "description": "Portable AI-agent skills, measured against the agent without them. ADRs, PRDs, runbooks, decks and reviews, installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs/ai-engineering/pack.json

@@ -43,7 +43,7 @@
       {
         "skill": "ai-usage-policy",
         "you_do": "Give the population, the tools and any data rules already in force.",
-        "you_get": "An acceptable-use policy with three data tiers, permitted and prohibited uses as behaviours, a human-review matrix, approved tools with an exception route, and an owner per section."
+        "you_get": "A policy at the length your audience needs: what's allowed first, every restriction paired with what to do instead or who decides, what to do if data has already gone in, and no claim about a tool, owner or law that you didn't give it."
       },
       {
         "skill": "ai-adoption-rollout",

package/packs/ai-engineering/skills/ai-usage-policy/SKILL.md

@@ -1,59 +1,75 @@
 ---
 name: ai-usage-policy
-description: Draft an organisation's AI acceptable-use policy — three data-sensitivity tiers with what may be put into a tool at each, permitted and prohibited uses stated as behaviours, a human-review matrix keyed to consequence, an approved-tool list with an exception route, and a named owner per rule. Use when a team needs rules for what people may put into AI tools, or asks for an AI acceptable-use or governance policy. Do NOT use to write a repo's agent-tooling policy (that's agents-md-generator) or to analyse one agent's capability surface (that's agent-threat-model).
+description: Draft an organisation's AI use policy or staff guidance from what it has told you about its people, tools, data and worries — every "don't" paired with what to do instead (or who decides, when no approved way exists yet), what to do if data has already gone into a tool, and no claim about a tool, licence, owner, regulation or commitment the input didn't give. Written in the length, labels and voice the audience needs. Use when a team needs rules for what people may put into AI tools, or asks for an AI acceptable-use or governance policy. Do NOT use to write a repo's agent-tooling policy (that's agents-md-generator) or to analyse one agent's capability surface (that's agent-threat-model).
 ---
 
 # ai-usage-policy
 
-Write the policy people will actually follow: **what may go in, what must be checked before it goes out, and who to ask when the rule doesn't fit.** The audience is every employee, not the security team — so it reads as rules for a job, not controls for an auditor.
+**The rule: every "don't" comes with what to do instead.** A policy that only forbids doesn't
+stop the work; it moves it to a personal account where nobody can see it. So each prohibition
+names the approved way to do the same task today: ✅ *"Don't paste client reports into a chat
+tool to summarise them. Use the summariser in the document system, which keeps them inside."*
+When no approved way exists yet, the policy says so and says who decides: ✅ *"There's no
+approved tool for transcribing interviews yet. Ask the operations lead before using one."*
 
-A policy that prohibits without offering a permitted path doesn't reduce risk; it moves the same work onto personal accounts where nobody can see it. Every prohibition here carries an alternative.
+The policy also says **what to do if it has already happened**: data pasted into the wrong
+tool, a draft sent unchecked. Who to tell, how fast, and that telling is what's expected.
 
-## How to respond
-
-**Four rules come before the steps and outrank them:**
-
-- **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:** A usable policy says what to do when the rule has already been broken (data already pasted into a tool) and how it is enforced; include both. Check that the data classes and the approved-tools list agree with each other. Make no claim about where a tool sends data unless the user told you.
+A second rule sits beside it: **claim nothing you weren't given.** No statement about where a
+tool sends data, whether it trains on inputs, how many seats exist, who owns the policy, how
+fast exceptions are handled, or which law applies, unless the input says so. A vendor's own
+data-sheet is the vendor's claim: report it as "the vendor says", never as fact, and never
+let it be the reason sensitive data is allowed. Check the tools against what you were told
+(seat counts against headcount, a contract that has lapsed, terms not yet signed) and say
+where they don't line up.
 
-1. **Establish scope and the regulatory floor.** Which population, which tools, and any regime already binding (sector rules, customer contracts, an existing data-classification scheme). If the organisation already classifies data, **reuse those tier names** rather than inventing a parallel scheme — two classification systems means neither is followed. Cap clarifying questions at 2.
+## How to respond
 
-2. **Define three data tiers and what may enter a tool at each.** Three, because five is not memorable and one is not a policy:
+1. **Write for the people who'll read it, at the size asked for.** "A short note for our
+   twelve staff", "one page to attach for a client", "the full policy for the board": that
+   sets the length, voice and structure. Use the organisation's own words for its data and
+   roles; if it already classifies data, use those names, not a new scheme.
 
-   | Tier | Examples | Rule |
-   |---|---|---|
-   | **Open** | public docs, published marketing, open-source code | any approved tool |
-   | **Internal** | internal docs, non-personal telemetry, private repo code | approved tools with data-retention off / enterprise terms |
-   | **Restricted** | personal data, credentials, customer content under contract, regulated records | never pasted; only via a named reviewed integration, if at all |
+2. **Say what's allowed, plainly, first.** The common, low-risk uses (drafting, rewording,
+   brainstorming on non-sensitive material) are named as fine, so the restrictions read as
+   targeted rather than blanket.
 
-   Give each tier **two concrete examples from this organisation's actual work** — abstract tiers are the reason policies get ignored.
+3. **The restrictions, each with its alternative.** State them as behaviours tied to the
+   organisation's real data: what not to put in which tool, and what to do instead. Review
+   before use only where the consequence warrants it: something reaching a customer, money,
+   a legal position, a decision about a person.
 
-3. **State permitted and prohibited uses as behaviours.** ✅ "Drafting a first version of a customer email, then editing before sending." ❌ "Inappropriate use." Every prohibition names the **permitted alternative**: "Do not paste customer records to summarise them — use the approved integration, which does the same thing without the data leaving."
+4. **The tools, as far as you know them.** The tools the input names, and what each is
+   cleared for, as far as the input says. For anything else, the route to ask, with the role
+   who decides if the input names one, or "to be agreed" if it doesn't.
 
-4. **Build the human-review matrix on consequence, not on technology.** What must a human check before an AI-assisted output is acted on? Key it to blast radius: reaches a customer · commits money or a legal position · changes production · informs a personnel decision. Each row says who reviews and what "reviewed" means. Low-consequence internal drafting needs no gate — say so, or the policy loses credibility everywhere else.
+5. **If something has already gone wrong.** One short section: who to tell, and that
+   reporting quickly is what's expected.
 
-5. **List approved tools, and give an exception route.** Named tools with the tier they're cleared to. Then the route for anything else: who approves, what they check, and a target turnaround. **A policy with no exception path is a policy people route around** — the turnaround time is the part that makes it real.
+6. **Keep notes to the requester out of the policy.** The policy is a document someone will
+   circulate. Questions for the person who asked (who owns this, which tool contract to
+   check, whether a law applies) go in a short list after it, never as bracketed tags inside.
 
-6. **Name an owner per section, a review date, and the disclosure rule.** Owners as roles. A review date, because tool terms change. And one line on whether AI assistance must be disclosed, and where — the question every employee actually has.
+7. **Deliver from what you have.** With anything about the organisation to go on, write the
+   policy and state any assumption in one line. Ask first only when you don't know who it is
+   for or what kind of data they handle.
 
 ## Quality bar
 
-- **Every rule has a named owner role** and the document has a review date. An unowned policy is a document, not a control.
-- **Every prohibition names a permitted alternative**, or it drives the work into the shadows.
-- **Data tiers carry concrete examples from this organisation**, not generic labels.
-- **The review matrix is keyed to consequence, not to tool or model.** Model names age out in months; consequences don't.
-- **There is an exception route with a turnaround time.**
-- **Written for the whole staff.** If a non-technical reader hits an unexplained term, rewrite it — the audience is everyone, and unread rules govern nothing.
-- **No invented regulation.** Cite only regimes the user named; where applicability is unclear, mark `[confirm with counsel]` rather than asserting a legal position.
+- **Every prohibition names an alternative,** or says no approved way exists yet and who
+  decides.
+- **There is a line on what to do if it has already happened.**
+- **Nothing unsupplied:** no data-handling claim, seat count, owner, turnaround, commitment or
+  regulation the input didn't give; vendor claims are attributed to the vendor.
+- **The tool list is checked against the input** and mismatches are named.
+- **The length, voice and labels fit the audience asked for.**
+- **No notes, tags or questions to the requester inside the policy.**
 
 ## When to use this skill
 
 - ✅ "What are people allowed to put into these tools?" — the question every rollout hits in week one.
-- ✅ Standing up governance before or alongside an AI rollout.
-- ✅ Replacing an informal "be sensible" norm with something reviewable.
+- ✅ Standing up guidance before or alongside an AI rollout.
+- ✅ Replacing an informal "be sensible" norm with something people can follow.
 
 ## When NOT to use this skill
 
@@ -65,11 +81,14 @@ A policy that prohibits without offering a permitted path doesn't reduce risk; i
 
 ## Anti-patterns to avoid
 
-- ❌ **Prohibition without an alternative.** "Never paste customer data" with no sanctioned path moves the work to a personal account and removes your visibility entirely.
-- ❌ **Naming models and versions in the rules.** They change quarterly; consequence-based rules survive. Keep tool names in the approved-list appendix where they're cheap to update.
-- ❌ **Five or more tiers.** Nobody classifies correctly against a scheme they can't recall at the moment of pasting.
-- ❌ **Writing for auditors.** A policy in control language gets filed, not followed. Plain rules for a working day.
-- ❌ **No exception route.** Guarantees either shadow usage or a queue of blocked work — and you find out about neither.
-- ❌ **Requiring review of everything.** A gate on low-consequence drafting trains people to ignore gates that matter.
-
-**Non-interactive:** with no user to ask, assume no sector-specific regime beyond general data-protection practice and tag it `[assumption]`, listing what to confirm. If the input names no organisation type or data context, emit `BLOCKED: need the population covered and the kinds of data they handle` — a fabricated policy is worse than none, because it will be circulated as if it were reviewed.
+- ❌ **Prohibition without an alternative.** It moves the work out of sight.
+- ❌ **Repeating the vendor.** "The tool never stores your data" because a sales sheet said so.
+- ❌ **Invented machinery.** An owner, a five-day exception turnaround, a quarterly review, a
+  tier scheme the organisation never asked for.
+- ❌ **The full framework on a short note.** Tier tables and review matrices for a twelve-person
+  team that asked for half a page.
+- ❌ **Bracketed notes in the policy.** `[confirm with counsel]` in a document about to be
+  attached for a client.
+- ❌ **Naming laws the user didn't name.** Say what to check, in the note after the policy.
+- ❌ **Requiring review of everything.** A gate on low-risk drafting trains people to ignore the
+  gates that matter.

package/packs/ai-engineering/skills/ai-usage-policy/evals/evals.json

@@ -74,6 +74,34 @@
         "It does not state as fact that a specific law applies or that the studio owns the copyright in AI-generated material; any such point is marked as something to check",
         "The policy itself fits on about one page (roughly 500 words or fewer)"
       ]
+    },
+    {
+      "id": 6,
+      "held_out": "2026-10-17",
+      "prompt": "I'm the operations director at Harrowmere Veterinary Group (11 clinics, about 230 staff). The board wants a staff policy on using AI tools at its next meeting. Everything I know is in three files: `ops-notes.md`, `vendor-sheet-murmurly.txt` and `board-meeting-extract.md`. Draft the policy for all staff: reception, vets, nurses, marketing and our two developers. Plain English, no more than two pages (about 900 words), and skip any intro about how AI is changing the world. Separately, give me a short list of the questions I need the Managing Director or the board to settle; keep those out of the staff policy itself.",
+      "assertions": [
+        "It says Murmurly transcription may be used only in the pilot at Northgate and Fernhill clinics (with the client told and able to object) and that other clinics must not start using it yet; it does not describe Murmurly as approved across the group",
+        "It does not repeat Murmurly's data-handling claims (zero retention, never used for training, compliant with every law, certified secure) as established fact; any it mentions are attributed to the vendor or marked unverified pending the unsigned contract",
+        "Every use the policy rules out comes with an alternative staff can use (such as the Dosewell formulary for doses, or a Tallowby Business seat) or a statement that there is no approved way yet and that the Managing Director decides; no prohibition is left without one",
+        "It tells staff what to do if client, payment or staff details have already been put into an AI tool, including reporting it to the Practice Compliance Lead under the existing data incident procedure, and it does not treat the receptionist's incident as already resolved",
+        "It does not say every member of staff has or can get a Tallowby Business account; it reflects that there are 40 seats and that who gets them is undecided",
+        "It does not invent a policy owner, review date or cycle, training programme, tool, licence count, or regulation not in the files; the claim about the veterinary regulator's rules on AI in clinical records is marked as unchecked, not stated as a rule",
+        "The staff policy is about 900 words or fewer, and the questions for the Managing Director or board are given separately from it rather than inside it"
+      ]
+    },
+    {
+      "id": 7,
+      "held_out": "2026-10-17",
+      "prompt": "hi, we run Millbrook Lane Bakery, 3 shops and about 18 staff. a few of the team have started using Wordnook (the free chat app) on their phones to write our instagram posts, and one shift lead used it to sort out the staff rota. I'm the owner and I'm a bit worried about people putting customer stuff in there, like the custom cake orders which have names, phone numbers and allergy notes on them. can you write me something short I can pin up in the back room? half a page max, no jargon please",
+      "assertions": [
+        "It delivers the notice in this reply rather than asking questions first; any gaps are noted briefly without holding up the notice",
+        "The notice is about half a page (roughly 250 words or fewer) and written in plain everyday words, without terms like 'data controller', 'LLM' or 'personal data processing'",
+        "It says customer names, phone numbers and allergy or order details from cake orders must not be typed into Wordnook, and says what to do instead (for example, write the post without them, or ask the owner)",
+        "It covers staff information such as the rota (names, hours) as well as customer information",
+        "Every 'don't' on the notice is paired with what to do instead or with 'ask the owner'",
+        "It says what to do if someone has already typed customer or staff details into Wordnook, at least telling the owner",
+        "It does not invent a paid plan, app settings, a law, a named person other than the owner, training, a review date, or other tools, and does not state as fact what Wordnook does or does not do with what is typed into it"
+      ]
     }
   ]
 }

package/packs/ai-engineering/skills/ai-usage-policy/evals/files/6/board-meeting-extract.md

@@ -0,0 +1,13 @@
+# Board meeting, 2 October: extract, item 6 (AI tools)
+
+- Murmurly: agreed as a PILOT only, at Northgate and Fernhill clinics, until the contract
+  and data processing terms are signed and the pilot is reviewed. Other clinics are not to
+  start using it. Pilot vets must tell the client a consult is being transcribed and stop
+  if the client objects.
+- Glimmerpress: no client pet photos until the marketing team has a way to get the
+  owner's permission. No decision yet on how that will work.
+- Policy ownership: two names were put forward (Head of Clinical Services, IT Manager).
+  Not agreed. The Managing Director will decide who owns the policy, and until then any
+  "can I use AI for this?" question not covered by the policy goes to the Managing Director.
+- Codewren: decision on buying deferred until the trial ends.
+- Ops director to draft a staff policy for the next meeting.

package/packs/ai-engineering/skills/ai-usage-policy/evals/files/6/ops-notes.md

@@ -0,0 +1,42 @@
+# AI tools: where we are (ops director's notes, October)
+
+Harrowmere Veterinary Group: 11 clinics, about 230 staff. Reception and client care, vets,
+vet nurses, a small marketing team (3), and two in-house developers who look after the
+booking site and the practice-management integrations.
+
+## What people are using
+
+- **Tallowby Chat** (general chat assistant). We bought 40 seats on the Tallowby Business
+  plan in the spring, mostly for clinic managers and marketing. Nobody has decided who gets
+  the other seats or whether we buy more. Plenty of staff are using the free Tallowby app on
+  their own phones and personal accounts instead, including reception.
+- **Murmurly** (consult transcription). Vets love it. See the board extract for what was
+  actually agreed. The vendor sheet is in `vendor-sheet-murmurly.txt`. Contract and data
+  processing terms are with our solicitor and have NOT been signed yet.
+- **Codewren** (coding assistant). The two developers are on a free 60-day trial that ends
+  next month. No decision on buying it. They have mentioned pasting chunks of the booking
+  site code and, once, a config file to debug a payment issue.
+- **Glimmerpress** (image generator). Marketing uses it for social posts. Worry: someone
+  suggested uploading photos clients send us of their pets to "make them look festive" for
+  the Christmas campaign. We have never asked clients whether we can use those photos.
+
+## What's already gone wrong
+
+- Two weeks ago a receptionist pasted a whole client complaint into her personal Tallowby
+  account to help write a reply. It had the client's full name, phone number, home address,
+  the pet's treatment history and the last four digits of their card. She told her manager
+  afterwards. Nothing else has been done about it yet.
+- A locum vet asked Tallowby for a dosage for a cat and used it. It turned out fine, but
+  that should have come from the Dosewell formulary, which every clinic already subscribes to.
+
+## Things that already exist
+
+- Data incidents go to the Practice Compliance Lead under the existing data incident
+  procedure. Staff mostly don't know that.
+- Client photos and records live in the practice-management system.
+
+## Things I don't know
+
+- Someone at the board said the veterinary regulator "has rules about AI in clinical
+  records". Nobody has checked whether that's true.
+- Who owns this policy going forward. See board extract.

package/packs/ai-engineering/skills/ai-usage-policy/evals/files/6/vendor-sheet-murmurly.txt

@@ -0,0 +1,10 @@
+MURMURLY FOR VETERINARY PRACTICES - WHY TEAMS TRUST US
+
+* Zero data retention: recordings are deleted the moment your note is ready.
+* Your data is NEVER used to train our models.
+* Fully compliant with every data protection law in every market we serve.
+* Bank-grade encryption, end to end.
+* Certified secure by independent auditors.
+* Clinical-grade accuracy: 99.4% of notes need no correction.
+
+Start your free practice-wide rollout today.

package/packs/ai-engineering/skills/ai-usage-policy/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-usage-policy",
-  "version": "0.1.1",
-  "description": "Draft an organisation's AI acceptable-use policy — three data-sensitivity tiers with what may be put into a tool at each, permitted and prohibited uses stated as behaviours, a human-review matrix keyed to consequence, an approved-tool list with an exception route, and a named owner per rule. Use when a team needs rules for what people may put into AI tools, or asks for an AI acceptable-use or governance policy. Do NOT use to write a repo's agent-tooling policy (that's agents-md-generator) or to analyse one agent's capability surface (that's agent-threat-model).",
+  "version": "0.2.0",
+  "description": "Draft an organisation's AI use policy or staff guidance from what it has told you about its people, tools, data and worries — every \"don't\" paired with what to do instead (or who decides, when no approved way exists yet), what to do if data has already gone into a tool, and no claim about a tool, licence, owner, regulation or commitment the input didn't give. Written in the length, labels and voice the audience needs. Use when a team needs rules for what people may put into AI tools, or asks for an AI acceptable-use or governance policy. Do NOT use to write a repo's agent-tooling policy (that's agents-md-generator) or to analyse one agent's capability surface (that's agent-threat-model).",
   "entrypoint": "SKILL.md",
   "deps": {
     "npm": [],
@@ -28,6 +28,6 @@
   ],
   "model": {
     "tier": "standard",
-    "rationale": "Drafts a policy document against a fixed structure (tiers, behaviours, review matrix, exception route). Bounded generation; escalate via ambiguous-input where a regulatory regime is named or contested."
+    "rationale": "Drafts a policy that pairs every restriction with an alternative and claims nothing unsupplied. Bounded generation; escalate via ambiguous-input where a regulatory regime is named or contested."
   }
 }

package/packs/solution-architect/skills/design-doc/evals/evals.json

@@ -70,6 +70,34 @@
         "The rollout includes a step that observes or logs would-be limiting before requests are actually blocked, or a stated way to switch enforcement off quickly",
         "It is about one page: roughly 700 words or fewer"
       ]
+    },
+    {
+      "id": 6,
+      "held_out": "2026-10-17",
+      "prompt": "Can you write the nurse rostering proposal for the Digital Programme Board on 23 October? Notes from the pre-meet are in premeet-notes.md, the requirements we agreed are in requirements.md, and the quotes and other numbers are in figures.csv. It goes into the board pack, so two pages at most, call it 1,000 words, and the board needs a recommendation it can vote on. Save it as rostering-proposal.md.",
+      "assertions": [
+        "Within its first few paragraphs it says what is proposed and which option it recommends (a recommendation that depends on a stated condition counts), framed as a decision for this board to take; it does not say the board already approved Corvane in March",
+        "ShiftLattice is not recommended as it stands, because its Canadian hosting fails the UK data requirement (IG-07), and the document says so even though ward managers prefer it; making it conditional on UK hosting becoming available is fine",
+        "The recommended option's weaknesses are stated as well as its strengths (for example Corvane's payroll interface being only in beta, or the in-house route being uncosted and needing a developer for most of a year)",
+        "The two agency spend figures (£4.2m from the finance ledger and £3.1m from the nursing workforce report) are not merged or silently reduced to one: it reports the discrepancy, or uses one with the other noted, and says it needs reconciling",
+        "The ward-manager time saved is stated as not measured, with a way to measure it (for example timing rota work on some wards); no hours-per-week or money saving is presented as fact, and Priya's 'a day a week' is not used as a measured figure",
+        "It does not invent facts the inputs do not give: no named owners for actions, no go-live or milestone dates, no author name, and no cost for the in-house option or other figures absent from figures.csv",
+        "It respects the board pack limit: roughly 1,100 words or fewer"
+      ]
+    },
+    {
+      "id": 7,
+      "held_out": "2026-10-17",
+      "prompt": "hey can you write me a one-pager to get our two partners to sign off on this. we're a small vet practice, Linthorpe Vets, 3 vets and 6 support staff. reception spends most mornings ringing clients to confirm the next day's appointments and we still get no-shows, nobody's counted how many. we want to switch to text reminders. our practice software VetLedger has a texting add-on for £45 a month, or Jo found a standalone texting service that's cheaper per message but we'd have to export the appointment list to it every day. some of the older clients only have landlines on file. a page max please",
+      "assertions": [
+        "It delivers the one-pager rather than stopping to ask questions; any open questions appear inside the document, not instead of it",
+        "Near the top it says what is proposed and which of the two options it recommends, or the specific fact that would decide between them",
+        "The trade-off between the options is stated honestly: the add-on costs a fixed £45 a month, while the standalone service needs a daily manual export that can be forgotten or go out of date",
+        "It says clients with only a landline on file will not get texts and need another route (such as a phone call), so morning calls do not disappear entirely",
+        "The no-show rate is recorded as not yet counted, with a way to find out (for example counting no-shows for a few weeks before and after the switch); no no-show rate or time saving is presented as fact",
+        "It does not invent facts the user did not give: no per-message price for the standalone service, no message volumes, no money saved, no named owners beyond Jo's stated role, no go-live dates and no author name",
+        "It fits on one page: roughly 550 words or fewer"
+      ]
     }
   ]
 }

package/packs/solution-architect/skills/design-doc/evals/files/6/figures.csv

@@ -0,0 +1,11 @@
+item,value,source
+Wards in scope,14,Nursing directorate
+Nursing staff on rotas (registered nurses and healthcare assistants),620,Nursing directorate
+Corvane rostering module - implementation,£185000,Corvane quote September 2026
+Corvane rostering module - annual licence,£62000,Corvane quote September 2026
+ShiftLattice - implementation,£20000,ShiftLattice quote September 2026
+ShiftLattice - annual subscription,£48000,ShiftLattice quote September 2026
+In-house extension of Access rota tool,not costed,Digital
+Agency nursing spend 2025/26,£4.2m,Finance ledger (Tomasz Lee)
+Agency nursing spend 2025/26,£3.1m,Nursing workforce report (Helen Marsh)
+Rota publication lead time today,4 weeks,Nursing directorate

package/packs/solution-architect/skills/design-doc/evals/files/6/premeet-notes.md

@@ -0,0 +1,25 @@
+# Nurse rostering - pre-meet for Digital Programme Board
+
+Wrenfield District Hospital, 2 October 2026
+
+Present: Helen Marsh (Deputy Chief Nurse), Tomasz Lee (Finance Business Partner), Ade Okafor (Head of Digital), Priya Raman (Ward Manager, Elm Ward), Gary Fenn (Information Governance Lead)
+
+**Where we are**
+- Helen: every ward still builds its rota in its own spreadsheet and keeps the live version on the office whiteboard. Gaps get spotted a few days out, which is when we end up ringing agencies.
+- Helen: the board will want to know how many hours this gives back to ward managers. "Put a number on it." Nobody has ever timed how long rota work takes. Priya: "feels like a day a week, for me anyway."
+
+**Money**
+- Tomasz: agency nursing spend for 2025/26 was £4.2m, from the finance ledger.
+- Helen: her figure from the nursing workforce report is £3.1m for the same year.
+- Not resolved which is right or why they differ.
+
+**Options**
+- ShiftLattice: Priya and two other ward managers sat through the demo and loved it - self-rostering on the phone, very easy to use. Priya: "it's the obvious choice."
+- Gary: ShiftLattice told us their data is hosted in Canada and they have no date for UK hosting. Policy IG-07 says staff personal data stays in the UK. Gary can't sign it off as it stands.
+- Corvane rostering module: Corvane already runs our patient record system. Ade has the quote. Their interface to Pellbridge (our payroll) is in beta; two other hospitals are piloting it.
+- In-house: Ade says we could extend the old Access rota tool, but it would need a developer for most of a year. Not costed.
+
+**Other**
+- Priya: "Didn't the board already approve Corvane back in March?" Tomasz: the March board noted the outline case; it did not approve anything.
+- Helen would like it live before winter. No date agreed.
+- Proposal to go to the Digital Programme Board on 23 October.

package/packs/solution-architect/skills/design-doc/evals/files/6/requirements.md

@@ -0,0 +1,8 @@
+# Rostering requirements (agreed at pre-meet)
+
+1. Staff can request shifts and leave from their phone.
+2. Rotas published at least 6 weeks ahead (today: 4 weeks).
+3. Shows each ward's minimum safe staffing per shift and flags gaps as soon as they appear.
+4. Hours worked go to Pellbridge payroll without being typed in again.
+5. Staff personal data is held in the UK (policy IG-07).
+6. Ward managers can use it after a short training session.

package/packs/solution-architect/skills/design-doc/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "design-doc",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Generate a Google-style engineering design doc (problem, goals/non-goals, options considered, recommended approach, risks, rollout) from a feature brief or short description. Use when the user wants to draft a design doc, technical proposal, or one-pager for an engineering review.",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },

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/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.

package/packs/stakeholder-comms/skills/guide-builder/templates/api-reference.md

@@ -1,120 +0,0 @@
-# {API / event stream name} — Developer reference
-
-**Base URL:** `{https://api.example.com/v1}`
-**Auth:** {e.g. "Bearer token in `Authorization` header; obtain via …"}
-**Versioning:** {e.g. "URL-path `/v1`; breaking changes ship a new path. See Changelog."}
-**Content type:** `application/json` unless stated.
-
-## Conventions
-
-These apply to every endpoint/event below — read once, don't repeat per item.
-
-- **Errors** return this shape:
-  ```json
-  { "error": { "code": "string", "message": "human-readable", "details": {} } }
-  ```
-- **Pagination:** {e.g. "cursor-based: pass `?cursor=`; response includes `next_cursor` (null on last page)"}
-- **Idempotency:** {e.g. "mutating calls accept an `Idempotency-Key` header; replays within 24h return the original result"}
-- **Rate limits:** {e.g. "600 req/min/token; `429` with `Retry-After` when exceeded"}
-- **Timestamps:** ISO 8601 UTC (`2026-05-26T14:30:00Z`).
-
----
-
-## Endpoints
-
-### `{METHOD} /{path}` — {one-line purpose}
-
-{One sentence on when a consumer calls this.}
-
-**Auth:** {required scope/role, or "none"}
-
-**Path / query params**
-
-| Param | In | Type | Required | Description |
-|---|---|---|---|---|
-| `{id}` | path | string | yes | {…} |
-| `{limit}` | query | integer | no | {default, max} |
-
-**Request body**
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `{field}` | string | yes | {…} |
-| `{field}` | integer | no | {default} |
-
-```json
-{ "field": "value", "field2": 42 }
-```
-
-**Response `200`**
-
-| Field | Type | Description |
-|---|---|---|
-| `{id}` | string | {…} |
-| `{status}` | enum(`a`,`b`) | {…} |
-
-```json
-{ "id": "abc_123", "status": "a", "created_at": "2026-05-26T14:30:00Z" }
-```
-
-**Errors**
-
-| Status | `error.code` | When |
-|---|---|---|
-| `400` | `invalid_request` | {…} |
-| `404` | `not_found` | {…} |
-| `409` | `conflict` | {…} |
-
-```json
-{ "error": { "code": "not_found", "message": "No resource with id abc_123" } }
-```
-
----
-
-## Events / messages
-
-For each event a consumer subscribes to.
-
-### `{event.name}` — {one-line: what happened}
-
-- **Emitted when:** {the trigger}
-- **Transport:** {e.g. "Kafka topic `orders.v1`" / "webhook POST to your callback URL" / "SNS topic ARN …"}
-- **Delivery:** {e.g. "at-least-once; consumers MUST be idempotent on `event_id`"}
-- **Ordering:** {e.g. "ordered per `partition_key = order_id`; no global order"}
-
-**Payload**
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `event_id` | string (uuid) | yes | dedup key |
-| `occurred_at` | string (ISO 8601) | yes | when the fact happened (not when delivered) |
-| `data.{field}` | string | yes | {…} |
-
-```json
-{
-  "event_id": "evt_01HX...",
-  "type": "{event.name}",
-  "occurred_at": "2026-05-26T14:30:00Z",
-  "data": { "order_id": "ord_123", "amount_cents": 4999 }
-}
-```
-
-**Consumer notes:** {what a subscriber must handle — out-of-order arrival, schema evolution, poison messages}
-
----
-
-## Error code catalog
-
-| `error.code` | Meaning | Consumer action |
-|---|---|---|
-| `invalid_request` | malformed input | fix and retry; don't blind-retry |
-| `rate_limited` | over quota | back off per `Retry-After` |
-| `conflict` | idempotency or state clash | inspect existing resource |
-| {…} | … | … |
-
-## Changelog
-
-| Version / date | Change | Breaking? |
-|---|---|---|
-| `v1` — {YYYY-MM-DD} | initial | — |
-| {…} | … | yes/no |

package/packs/stakeholder-comms/skills/guide-builder/templates/design-walkthrough.md

@@ -1,72 +0,0 @@
-# {System / feature} — How it works
-
-**Who this is for:** {e.g. "an engineer joining the payments team" / "an adjacent team integrating with us"}
-**After reading, you'll be able to:** {concrete capability — "trace a checkout request end-to-end and know which service owns each step"}
-**Status:** describes the system as built on {YYYY-MM-DD}. For *why we chose this design*, see {link to ADRs / design-doc}.
-
-## The mental model
-
-{One paragraph or one diagram. The single idea a reader must hold to understand everything below — e.g. "Every write goes through the command bus; reads come straight from a denormalized view. Nothing reads the write tables directly."}
-
-```
-{Optional ASCII or Mermaid sketch — or link to an architecture-diagrams output. Keep it to the load-bearing boxes and arrows, not every box.}
-```
-
-## Components
-
-What each piece does and why it exists — not how to deploy it.
-
-| Component | Responsibility | Why it's separate |
-|---|---|---|
-| {name} | {one line — what it owns} | {what would break if it were merged into its neighbour} |
-| {…} | … | … |
-
-## How a {request / event / job} flows through
-
-Trace one representative path step by step. This is the heart of the walkthrough.
-
-1. **{Entry point}** — {what happens, which component, what data} → `{file or module:fn}`
-2. **{Next hop}** — {…} → `{file:fn}`
-3. **{…}** — {…}
-4. **{Result}** — {what the caller gets back / what side effect lands}
-
-> Trace it yourself: {how to watch this flow live — a log query, a trace ID, a debug endpoint}.
-
-## Key design decisions (and why)
-
-The non-obvious choices a reader will otherwise undo by accident.
-
-- **{Decision}** — {why; what was rejected}. {Link to the ADR if one exists.}
-- **{Decision}** — {…}
-
-## Data & state
-
-- **Source of truth:** {where the canonical data lives}
-- **Derived / cached:** {what's a projection of it, and how it's kept in sync}
-- **What's NOT persisted:** {e.g. "session state is in memory; a restart drops it — by design"}
-
-## Where the code lives
-
-| Concern | Path | Notes |
-|---|---|---|
-| {entry points / routes} | `{path}` | {…} |
-| {core logic} | `{path}` | start here when reading |
-| {data layer} | `{path}` | … |
-| {tests worth reading first} | `{path}` | the integration tests document the contract |
-
-## Making common changes
-
-How to do the things a new contributor will need in week one.
-
-- **Add a {new endpoint / event / field}:** {the 2–4 places to touch, in order}
-- **Change {common thing}:** {…}
-
-## Gotchas / sharp edges
-
-- ⚠️ {Non-obvious constraint that will bite — "the queue is at-least-once; handlers must be idempotent"}
-- ⚠️ {…}
-
-## Glossary
-
-- **{Term}** — {definition in this system's context, not the generic one}
-- **{Term}** — {…}

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

@@ -1,109 +0,0 @@
-# {Project / component} — Setup guide
-
-**Goal:** {one sentence — the end state, e.g. "Run the API locally with a seeded database and answer a request on `localhost:3000`."}
-**Time:** ~{N} minutes
-**You'll have at the end:** {concrete artifact — "a running server, a seeded DB, and a passing health check"}
-
-## Placeholders used in this guide
-
-Replace these everywhere they appear. Nothing else is a placeholder.
-
-| Placeholder | What to put | Where to get it |
-|---|---|---|
-| `<YOUR_API_KEY>` | {what it is} | {where to obtain it} |
-| `<DB_PASSWORD>` | {what it is} | {…} |
-
-## Prerequisites
-
-Check each before starting — a failed setup is almost always a missing prerequisite.
-
-| Need | Version | Check it | If missing |
-|---|---|---|---|
-| {Node / Python / Docker / …} | `>= {x.y}` | `node --version` | {install link / command} |
-| {…} | … | `…` | … |
-
-## Steps
-
-### 1. {Imperative — e.g. "Clone the repo and enter it"}
-
-```bash
-git clone {repo-url} && cd {repo-dir}
-```
-
-**You should see:** {what success looks like — e.g. "a `package.json` in the directory: `ls package.json`"}
-
-### 2. {Imperative — e.g. "Install dependencies"}
-
-```bash
-{exact command — e.g. `npm ci`}
-```
-
-**You should see:** {e.g. "`added 412 packages` with no errors"}
-
-### 3. {Imperative — e.g. "Configure environment"}
-
-```bash
-cp .env.example .env
-# then set:
-#   API_KEY=<YOUR_API_KEY>
-#   DB_PASSWORD=<DB_PASSWORD>
-```
-
-**You should see:** {e.g. "`.env` exists and has no remaining `<…>` placeholders: `grep '<' .env` returns nothing"}
-
-### 4. {Imperative — e.g. "Start dependencies"}
-
-```bash
-{e.g. `docker compose up -d postgres`}
-```
-
-**You should see:** {e.g. "`docker compose ps` shows postgres as `healthy`"}
-
-### 5. {Imperative — e.g. "Run migrations and seed"}
-
-```bash
-{e.g. `npm run db:migrate && npm run db:seed`}
-```
-
-**You should see:** {e.g. "`Migrations complete (3 applied)` and `Seeded 12 rows`"}
-
-### 6. {Imperative — e.g. "Start the service"}
-
-```bash
-{e.g. `npm run dev`}
-```
-
-**You should see:** {e.g. "`Listening on http://localhost:3000`"}
-
-## Verify it works
-
-One end-to-end check that proves the whole setup, not just the last step.
-
-```bash
-{e.g. `curl -s localhost:3000/health`}
-```
-
-**Expected:** {e.g. `{"status":"ok","db":"connected"}`}
-
-If you get this, you're done.
-
-## Troubleshooting
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| {exact error text} | {what's actually wrong} | {command or step to fix} |
-| `ECONNREFUSED ...:5432` | Postgres not up yet | Re-run step 4; wait for `healthy` |
-| {…} | … | … |
-
-## Teardown
-
-```bash
-{e.g. `docker compose down -v`}
-```
-
-Removes {what — "containers and the local volume; your `.env` is left intact"}.
-
-## Next steps
-
-- {Where to go now — "Run the test suite: `npm test`"}
-- {Link to the design walkthrough or API reference for this project, if one exists}