fdeops 5.1.14 → 5.1.15

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - working in the fdeops repository
 
-This repository **is** FDEOps: skills for Forward Deployed Engineers. The `fde` coordinator selects the relevant instructions for customer work. All 35 task skills also work individually. The local CLI manages customer records in `.fde/` files; users confirm consequential judgments.
+This repository **is** FDEOps: skills that help Forward Deployed Engineers work across strategy, architecture and engineering through AI coding agents. All 35 task skills work individually; `fde` coordinates them for ongoing customer work. Local `.fde/` records support continuity between sessions; users confirm consequential judgments.
 
 ## If you are helping use fdeops in an engagement
 

package/README.md

@@ -1,25 +1,19 @@
 # FDEOps
 
-**Forward deployed engineering skills for your AI coding agent.**
+**Skills for forward deployed engineers, used through your AI coding agent.**
 
 <a name="why-use-it"></a>
 
-The codebase does not tell your agent what the customer agreed to last week, why an approach was rejected or who can approve the next release.
+FDEOps helps you turn a customer problem into a working system: clarify the goal, choose an architecture, build and integrate, then verify the result and prepare for rollout.
 
-FDEOps brings that context into the work, from the first meeting to a system the customer can run. Use a skill for one task, or let `fde` coordinate the project and keep its record.
+Use a task skill on its own, or let `fde` coordinate work across strategy, architecture and engineering. Customer memory keeps decisions, evidence and next steps available between sessions.
 
-**35 task skills + one coordinator, `fde`**. Use your existing tools and processes. You and the customer keep control of the decisions.
+I built FDEOps around design thinking, first-principles thinking and systems thinking: understand the people doing the work, question assumptions, and examine how a change affects the whole system. I turned that approach into skills that help your AI coding agent investigate, build and verify, with customer memory to carry the work forward.
 
 [Get started](#quick-start) · [What it helps with](#three-things-it-helps-with) · [Choose a skill](#task-skills) · [Data boundaries](#your-records-your-control) · [Docs](docs/README.md)
 
-![FDEOps terminal: insurance KYC workshop, build, healthcare client switch, tests and handover](media/chat-demo.gif)
-
-*Fictional customers. Illustrative enterprise conversation with real local review-logic tests. Synthetic data; no live model or customer deployment. [Read the conversation](media/chat-demo.md) · [View a still](media/chat-demo.png).*
-
 ## Quick start
 
-**Use your customer’s approved AI tools and data.** FDEOps runs locally; your AI agent’s settings determine what reaches its provider. Start with synthetic data until customer access is approved. [Safe setup](SECURITY.md#before-customer-work).
-
 ### Let `fde` coordinate a customer project
 
 Install in the terminal where your AI coding agent runs, then select your agent:
@@ -36,23 +30,22 @@ checks internal documents, then assigns each request to another team.
 Help me prepare for the first meeting. Here is the brief: ...
 ```
 
-The coordinator selects the right skill as the work changes. For an ongoing project, it keeps decisions, evidence and next actions in a local customer record. You bring the context and make the decisions.
+The coordinator selects the relevant method as the work changes. Customer context guides the plan, code changes and verification; the record carries it between sessions. You do not need to learn CLI commands.
 
 ### Use one skill for one task
 
 ```bash
-npx skills add suboss87/fdeops --skill debrief
+npx skills add suboss87/fdeops --skill build
 ```
 
 Then ask your agent:
 
 ```text
-Use FDEOps debrief to review these meeting notes.
-Separate decisions, requests and open questions. Return a draft only.
-[Paste notes you are permitted to share.]
+Use FDEOps build to add a manual-review fallback to this routing service.
+Here are the agreed behavior, repository and checks: ...
 ```
 
-Each task skill includes the instructions it needs. Use `debrief` on supplied notes without creating a customer record or installing the coordinator.
+Each task skill includes the instructions it needs. Use `build` with supplied project context without creating a customer record or installing the coordinator.
 
 <details>
 <summary>Installation requirements and alternatives</summary>
@@ -65,69 +58,35 @@ These installation commands use Node.js and Git; the optional record CLI require
 
 ## Three things it helps with
 
-### 1. Starting the next session without starting over
-
-A repository tells you where the code lives. It may not tell you why the customer rejected an approach, which access is still blocked or what the team promised on Tuesday.
-
-<a name="keep-a-customer-record"></a>
-<a name="how-skills-work"></a>
-
-For ongoing engagements, each customer gets a plain-Markdown record at `~/fde-engagements/<customer>/.fde/`. The coordinator loads a short summary and looks up details as needed. Before resuming implementation, it checks the saved next action against the current task and code. Saved lessons are searchable within that customer’s record. Meeting preparation brings back recorded open questions and commitments; sharing a lesson with another customer requires explicit approval.
-
-From the fictional demo’s `fde resume` output:
-
-```text
-next: get the reconciliation runbook from Tom before touching anything. [source: meeting 2026-09-10]
-do first: Ask the acceptance owner to review the reported result and its evidence (delivery.md: 1 reported result awaiting acceptance)
-```
-
-The next session can pick up the work while keeping acceptance pending.
+### 1. Strategy: decide what is worth building
 
-Use [debrief](skills/debrief/SKILL.md) after a meeting and [switch-clients](skills/switch-clients/SKILL.md) when changing customers. [How records work](docs/USAGE.md).
+Turn the customer’s request into a problem to investigate, a measure of success and a bounded scope. Identify who decides and what evidence would change the plan.
 
-### 2. Keeping a request from becoming an agreement
+Use [discover](skills/discover/SKILL.md), [who-decides](skills/who-decides/SKILL.md) and [scope](skills/scope/SKILL.md).
 
-A stakeholder asks for more scope. A demo looks promising. Neither establishes a new commitment or an accepted result.
+### 2. Architecture: choose an approach that fits
 
-FDEOps keeps requests, confirmed decisions, reported results and open questions distinct. You review proposed record changes before saving them. Dates and sources keep claims traceable; customer approval still comes from the agreed owner.
+Inspect the existing system, compare options against customer constraints and plan a small slice that tests the design. Make dependencies, tradeoffs and failure paths explicit.
 
-For example, these fictional notes:
+Use [options](skills/options/SKILL.md), [plan](skills/plan/SKILL.md) and [integrate](skills/integrate/SKILL.md).
 
-> Mara agreed to keep CSV upload this phase. Devon asked for real-time sync; Mara has not answered. Two staging runs took 12 minutes. Production has not been measured.
+### 3. Engineering: build, verify and hand over
 
-The review separates them:
+Implement the change, debug failures and test the agreed behavior. Report what passed on which revision and environment, what remains unproven and what the operating team needs before rollout.
 
-| Record | What the notes support |
-|---|---|
-| Decision | Keep CSV upload this phase; attributed to Mara in the supplied notes |
-| Request | Real-time sync remains unapproved |
-| Evidence | Two staging runs took 12 minutes; production benefit is unmeasured |
-| Next step | Resolve the scope request with Mara before changing the commitment |
-
-This is a draft, not a saved agreement. Use [who-decides](skills/who-decides/SKILL.md), [scope](skills/scope/SKILL.md) or [readout](skills/readout/SKILL.md) for the decision in front of you.
-
-### 3. Knowing what is actually ready
-
-A local test, a deployed change and a customer-accepted result answer different questions.
-
-| Claim | Evidence it needs |
-|---|---|
-| Implemented | The change exists in the identified revision |
-| Verified | Applicable checks passed under stated conditions |
-| Deployed | The intended environment is running the change |
-| Measured | A result was observed against the agreed measure |
-| Accepted | The agreed owner or mechanism accepted the outcome |
-
-The skills use these distinctions when reporting progress; they are not automatic dashboard states.
+Use [build](skills/build/SKILL.md), [debug](skills/debug/SKILL.md), [review](skills/review/SKILL.md), [ship](skills/ship/SKILL.md) and [handoff](skills/handoff/SKILL.md). A passing local test does not establish deployment or customer acceptance. [Verification and its limits](docs/verification.md).
 
-FDEOps carries agreed checks into implementation and ties test results to the revision and environment checked. Before rollout, it asks for operating limits, recovery evidence and an owner. You can see what is ready, what is blocked and what still needs verification.
+<a name="keep-a-customer-record"></a>
+<a name="how-skills-work"></a>
 
-Use [build](skills/build/SKILL.md), [integrate](skills/integrate/SKILL.md), [review](skills/review/SKILL.md), [ship](skills/ship/SKILL.md) and [handoff](skills/handoff/SKILL.md) as needed. [See the tests and their limits](docs/verification.md).
+For ongoing work, a local Markdown record at `~/fde-engagements/<customer>/.fde/` carries decisions, evidence and next steps between sessions. The coordinator retrieves relevant context and prepares consequential updates for your review. Use [debrief](skills/debrief/SKILL.md) after meetings and [switch-clients](skills/switch-clients/SKILL.md) when changing customers. [How records work](docs/USAGE.md).
 
 ## Choose a skill
 
 <a name="task-skills"></a>
 
+**35 task skills + one coordinator, `fde`**. Each task skill works on its own; the coordinator includes all underlying methods.
+
 | Work in front of you | Start with |
 |---|---|
 | An unclear customer request | `brief`, `discover` |
@@ -160,13 +119,12 @@ Copy an action into your agent to continue. Regenerate the view after record upd
 <a name="your-records-your-control"></a>
 <a name="your-data-stays-yours"></a>
 
-## Local records, explicit data boundaries
-
-The CLI reads local files and Git without network calls or telemetry. Installation may download packages. Your AI host controls model connections and may transmit what it reads.
-
-CLI and hook outputs mask common identifier patterns. `<private>` blocks are redacted from those outputs and the dashboard. Local reports retain unmarked identifiers by default. These filters cover FDEOps output, not raw files or text you paste into an agent. Use only approved material, including when anonymised.
-
-You review consequential record updates. Enabled hooks can save mechanical session progress; direct CLI write commands update records when run. [Privacy](PRIVACY.md) · [Security](SECURITY.md) · [Local-model results](docs/verification.md#local-model-results).
+> [!NOTE]
+> **Use FDEOps with the setup that fits your work.** Try individual skills with sample data, or use a customer-approved local model or LLM provider for customer projects, including regulated and production work.
+>
+> Customer records stay in local files. The FDEOps CLI makes no network calls; your AI coding agent’s settings determine what it sends to a model provider. Use data approved for that setup.
+>
+> [Setup guidance](SECURITY.md#before-customer-work) · [Privacy and masking](PRIVACY.md) · [Local-model results](docs/verification.md#local-model-results)
 
 ## Who this is for
 

package/bin/check.js

@@ -194,11 +194,13 @@ if (read('package.json').includes('postinstall')) {
 }
 
 const readme = read('README.md')
-if (!readme.includes('media/chat-demo.gif') || !readme.includes('media/chat-demo.md') || !readme.includes('Fictional customers')) {
-  fail('README must include the chat walkthrough, text alternative and fictional-record disclosure')
-} else if (['chat-demo.gif', 'chat-demo.png', 'chat-demo.json', 'chat-demo.md', 'render-chat-demo.py'].some(name => !fs.existsSync(path.join(root, 'media', name)))) {
-  fail('chat walkthrough must include rendered assets, text, source and renderer')
-} else ok('README chat walkthrough has accessible text and reproducible source')
+if (readme.includes('media/chat-demo.gif')) {
+  if (!readme.includes('media/chat-demo.md') || !/fictional/i.test(readme)) {
+    fail('README animation must include a text alternative and fictional-data disclosure')
+  } else if (['chat-demo.gif', 'chat-demo.png', 'chat-demo.json', 'chat-demo.md', 'render-chat-demo.py'].some(name => !fs.existsSync(path.join(root, 'media', name)))) {
+    fail('chat walkthrough must include rendered assets, text, source and renderer')
+  } else ok('README animation has accessible text and reproducible source')
+}
 
 const usage = read('docs/USAGE.md')
 if (!usage.includes('media/session.gif') || !usage.includes('media/record-session.sh')) {

package/mcp/fdeops-ingest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops-ingest-mcp",
-  "version": "5.1.14",
+  "version": "5.1.15",
   "private": true,
   "description": "Thin stdio MCP sink for FDEOps ingest (stage \u2192 propose \u2192 apply). Zero runtime dependencies.",
   "bin": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fdeops",
-  "version": "5.1.14",
-  "description": "Forward deployed engineering skills for AI coding agents. Use focused task skills or @fde for discovery, implementation, verification and handoff, with local engagement records.",
+  "version": "5.1.15",
+  "description": "Skills for forward deployed engineers across strategy, architecture and engineering. Use individual tasks or @fde coordination; local customer memory supports continuity.",
   "bin": {
     "fdeops": "bin/install.js",
     "fde": "bin/fde.js"

package/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "fdeops",
-  "version": "5.1.14",
-  "description": "Forward deployed engineering skills for AI coding agents. Use focused task skills or @fde for discovery, implementation, verification and handoff, with local engagement records.",
+  "version": "5.1.15",
+  "description": "Skills for forward deployed engineers across strategy, architecture and engineering. Use individual tasks or @fde coordination; local customer memory supports continuity.",
   "author": {
     "name": "Subash Natarajan",
     "url": "https://github.com/suboss87"

package/skills/fde/references/poc.md

@@ -16,7 +16,9 @@ A green check on synthetic data is not a validated solution. The person who can
 
 **1. Pick by score when several use cases compete.** Use the scoring model from `discover.md` - (Value × Data readiness) / Complexity. If discover or score-use-cases already produced a ranking, reuse it; never invent a third ranking.
 
-**2. Build the minimum that tests the assumption.** Timebox the experiment with the FDE; aim for a same-day result when access and evidence permit it. Skip cosmetic polish, but keep the input validation, access controls, and failure handling needed to protect the test environment and data. Label shortcuts and simulated inputs. The POC is done when the person who can say no has seen the evidence and reacted, not when the code looks finished.
+**2. Build the minimum that tests the assumption.** Timebox the experiment with the FDE; aim for a same-day result when access and evidence permit it. Skip cosmetic polish, but keep the input validation, access controls, and failure handling needed to protect the test environment and data. Label shortcuts and simulated inputs. Complete the POC when the agreed assumption test has a recorded result and the responsible decision-maker has reviewed it; distinguish evidence from permission to proceed.
+
+**2b. Observe use when the assumption concerns people.** For a workflow or usability claim, ask an affected user to attempt a representative task in a permitted environment. Record completion, errors, help needed and their feedback against the agreed pass/fail check. A sponsor liking the demo is not evidence that users can complete the task. If user access is unavailable, report that validation as pending and continue independent technical checks. A successful task trial supports usability under those conditions; sustained adoption needs evidence from actual use over an appropriate period. Carry findings into the next prototype or plan rather than treating feedback as automatic acceptance.
 
 **3. AI directions - test these before anything else:**
 - Data: available, clean, sufficient volume? Synthetic data can test mechanics, but does not establish production quality or real-world coverage.

package/skills/fde/references/test-assumptions.md

@@ -47,7 +47,7 @@ CONVENIENCE - if wrong, a task changes but the approach holds
 | Assumption | Validation method | Effort | Evidence threshold |
 |-----------|-------------------|--------|-------------------|
 | "The API is the bottleneck" | Instrument the three slowest endpoints, measure p95 over 24h | 2h | Latency data shows >80% of wait time in API layer |
-| "The team will adopt the new tool" | Ask three team members individually: "Show me how you'd use this" | 1h | 2 of 3 can describe a use case without prompting |
+| "Users can complete the target task with the prototype" | Observe affected users attempting a representative task in a permitted environment | Timebox agreed for the task | Pre-agreed completion, error and assistance criteria; report sample and limits, not adoption |
 | "The data is clean enough for ML" | Sample 200 records, count nulls/duplicates/format errors | 1h | <5% error rate on the fields the model needs |
 
 **4. Run the killer test first.** The assumption with the highest blast radius AND the cheapest validation gets tested immediately. This single principle saves more engagement time than any other: if the killer assumption is wrong, you've saved weeks; if it holds, you've bought confidence. Write the kill observation in `How we test` as the result that would **stop** the plan - plan copies that line onto each Now PR as `Kill if`.
@@ -68,7 +68,7 @@ Evidence first, then the question. Let them reach the conclusion.
 | # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
 |---|------------|------|--------------|-------------|--------|----------|
 | 1 | API is the bottleneck | CONVENTION | CRITICAL | p95 instrumentation 24h | DISPROVED | 80% wait in DB layer (Day N) |
-| 2 | Team will adopt new tool | UNKNOWN | LOAD-BEARING | 3 individual interviews | CONFIRMED | 2/3 describe a use case unprompted |
+| 2 | Team will adopt new tool | UNKNOWN | LOAD-BEARING | Observe task use, then assess sustained use over an agreed period | OPEN | 2/3 describe a use case unprompted; interest reported, use not yet observed |
 | 3 | Data clean enough for ML | UNKNOWN | CRITICAL | 200-record sample | PARTIAL → OPEN follow-up | 12% nulls on key field; cleaning task added |
 ```
 
@@ -98,5 +98,5 @@ Result: acked in 40 minutes, by Marco, not finance. Assumption DISPROVED, and th
 - Kind before blast radius. A FACT with no receipt is UNKNOWN.
 - Kill the riskiest, cheapest-to-test assumption first.
 - Evidence first, then the question. Let the customer reach the conclusion.
-- A brief with zero disproved assumptions wasn't audited - it was accepted.
+- Design tests that could disprove consequential assumptions, and report what the evidence shows. All assumptions may survive a rigorous audit; never invent a contradiction to demonstrate skepticism.
 - Two weeks of building on a wrong assumption costs more than two hours of testing.

package/skills/fde/references/what-breaks.md

@@ -68,6 +68,8 @@ Time to detect: <5 minutes via error rate alert
 
 **Ask the team:** "Is anything outside this repo reading from or writing to <the thing you're changing>?" The answer is almost always "yes, and here's one we forgot about."
 
+**5b. Check the consequences of success.** When a change alters throughput, workload or decision-making, trace what happens if it works as intended. Does faster intake move the queue to another team, increase review or recovery work, or reward a local metric while the overall outcome worsens? Use known capacity and observed behavior; label missing evidence rather than inventing downstream harm. Name the affected owner and an end-to-end outcome signal alongside the local improvement. Carry a relevant check into the existing plan and ship pulse. Skip this expansion when the change has no material workflow effect.
+
 **6. The 2am test.** For any SYSTEMIC or IRREVERSIBLE change, ask: "If this fails at 2am on Saturday, who gets woken up, what do they see, and what can they do?" If the answer is "they see nothing until Monday" - the monitoring plan needs work before the change ships.
 
 ## Artifact

package/skills/options/.fde-generated.json

@@ -6,7 +6,7 @@
     "agents/openai.yaml": "ff5da2d5215943e5c4e2a1339c11101035ed2741ded38e443af5180239e2a24b",
     "references/business-case.md": "32e000e8351cd59f9eaad8be40babb276df69948ea4f81e01a4672e47f48cb25",
     "references/task-context.md": "9066514a50043f3ad888d133d4e8b89b7132551e098cf2c80203c458a80126e5",
-    "references/test-assumptions.md": "bf60d8bb4c0701fcffb196d78f7f6c8b1c472fc877fb2caf41058fbf8e2415a1",
+    "references/test-assumptions.md": "b3349a5f82e741e34fb0d17e16712a070b31d87f413e554be40374dd79152086",
     "references/three-options.md": "168fab9fb8ac8de85b0d1fa58e1db17deaa244cdef8c99623a04a0a6c70fe52c"
   }
 }

package/skills/options/references/test-assumptions.md

@@ -47,7 +47,7 @@ CONVENIENCE - if wrong, a task changes but the approach holds
 | Assumption | Validation method | Effort | Evidence threshold |
 |-----------|-------------------|--------|-------------------|
 | "The API is the bottleneck" | Instrument the three slowest endpoints, measure p95 over 24h | 2h | Latency data shows >80% of wait time in API layer |
-| "The team will adopt the new tool" | Ask three team members individually: "Show me how you'd use this" | 1h | 2 of 3 can describe a use case without prompting |
+| "Users can complete the target task with the prototype" | Observe affected users attempting a representative task in a permitted environment | Timebox agreed for the task | Pre-agreed completion, error and assistance criteria; report sample and limits, not adoption |
 | "The data is clean enough for ML" | Sample 200 records, count nulls/duplicates/format errors | 1h | <5% error rate on the fields the model needs |
 
 **4. Run the killer test first.** The assumption with the highest blast radius AND the cheapest validation gets tested immediately. This single principle saves more engagement time than any other: if the killer assumption is wrong, you've saved weeks; if it holds, you've bought confidence. Write the kill observation in `How we test` as the result that would **stop** the plan - plan copies that line onto each Now PR as `Kill if`.
@@ -68,7 +68,7 @@ Evidence first, then the question. Let them reach the conclusion.
 | # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
 |---|------------|------|--------------|-------------|--------|----------|
 | 1 | API is the bottleneck | CONVENTION | CRITICAL | p95 instrumentation 24h | DISPROVED | 80% wait in DB layer (Day N) |
-| 2 | Team will adopt new tool | UNKNOWN | LOAD-BEARING | 3 individual interviews | CONFIRMED | 2/3 describe a use case unprompted |
+| 2 | Team will adopt new tool | UNKNOWN | LOAD-BEARING | Observe task use, then assess sustained use over an agreed period | OPEN | 2/3 describe a use case unprompted; interest reported, use not yet observed |
 | 3 | Data clean enough for ML | UNKNOWN | CRITICAL | 200-record sample | PARTIAL → OPEN follow-up | 12% nulls on key field; cleaning task added |
 ```
 
@@ -98,5 +98,5 @@ Result: acked in 40 minutes, by Marco, not finance. Assumption DISPROVED, and th
 - Kind before blast radius. A FACT with no receipt is UNKNOWN.
 - Kill the riskiest, cheapest-to-test assumption first.
 - Evidence first, then the question. Let the customer reach the conclusion.
-- A brief with zero disproved assumptions wasn't audited - it was accepted.
+- Design tests that could disprove consequential assumptions, and report what the evidence shows. All assumptions may survive a rigorous audit; never invent a contradiction to demonstrate skepticism.
 - Two weeks of building on a wrong assumption costs more than two hours of testing.

package/skills/poc/.fde-generated.json

@@ -12,12 +12,12 @@
     "references/eval-pack.md": "0590b85d3cae0903c6b1274540c92eaa2a4373047e8a0548d6942516ef0bb9e1",
     "references/integrate.md": "1cb7a60d7545b0bf224fce678a04ce6ccdf368c47877d9c8e4dc4272bb0d5b0c",
     "references/plan.md": "6c37976169723f93d3554092979569a9640bcf02bd179bad52b17815c1c30f86",
-    "references/poc.md": "818dc90c2d401819735233ab9d69df171675d75abf8644c403dab7dd1dcf9199",
+    "references/poc.md": "65c91866037dc034a64484683ad9a329896786f1487265c9fddecd19b09a3039",
     "references/qa.md": "41de4d70827c83291efa217e97d777f62ec2849827687fbba7e4b1d17484b87e",
     "references/review.md": "55733ca868c00fb22110bc7b3ec7bb6c6451366c795073b19a2bccd30d2764c8",
     "references/ship.md": "95f51772b29de6f7d174f1f7678f15d46a3a5327dcb8facb94288e27907ae92c",
     "references/task-context.md": "9066514a50043f3ad888d133d4e8b89b7132551e098cf2c80203c458a80126e5",
-    "references/test-assumptions.md": "bf60d8bb4c0701fcffb196d78f7f6c8b1c472fc877fb2caf41058fbf8e2415a1",
+    "references/test-assumptions.md": "b3349a5f82e741e34fb0d17e16712a070b31d87f413e554be40374dd79152086",
     "references/three-options.md": "168fab9fb8ac8de85b0d1fa58e1db17deaa244cdef8c99623a04a0a6c70fe52c",
     "references/verification.md": "8ee2502112a37eedfdacf929041e7b91e9e6fabb007408a1ee2e2992e3af6ff6"
   }

package/skills/poc/references/poc.md

@@ -16,7 +16,9 @@ A green check on synthetic data is not a validated solution. The person who can
 
 **1. Pick by score when several use cases compete.** Use the scoring model from `discover.md` - (Value × Data readiness) / Complexity. If discover or score-use-cases already produced a ranking, reuse it; never invent a third ranking.
 
-**2. Build the minimum that tests the assumption.** Timebox the experiment with the FDE; aim for a same-day result when access and evidence permit it. Skip cosmetic polish, but keep the input validation, access controls, and failure handling needed to protect the test environment and data. Label shortcuts and simulated inputs. The POC is done when the person who can say no has seen the evidence and reacted, not when the code looks finished.
+**2. Build the minimum that tests the assumption.** Timebox the experiment with the FDE; aim for a same-day result when access and evidence permit it. Skip cosmetic polish, but keep the input validation, access controls, and failure handling needed to protect the test environment and data. Label shortcuts and simulated inputs. Complete the POC when the agreed assumption test has a recorded result and the responsible decision-maker has reviewed it; distinguish evidence from permission to proceed.
+
+**2b. Observe use when the assumption concerns people.** For a workflow or usability claim, ask an affected user to attempt a representative task in a permitted environment. Record completion, errors, help needed and their feedback against the agreed pass/fail check. A sponsor liking the demo is not evidence that users can complete the task. If user access is unavailable, report that validation as pending and continue independent technical checks. A successful task trial supports usability under those conditions; sustained adoption needs evidence from actual use over an appropriate period. Carry findings into the next prototype or plan rather than treating feedback as automatic acceptance.
 
 **3. AI directions - test these before anything else:**
 - Data: available, clean, sufficient volume? Synthetic data can test mechanics, but does not establish production quality or real-world coverage.

package/skills/poc/references/test-assumptions.md

@@ -47,7 +47,7 @@ CONVENIENCE - if wrong, a task changes but the approach holds
 | Assumption | Validation method | Effort | Evidence threshold |
 |-----------|-------------------|--------|-------------------|
 | "The API is the bottleneck" | Instrument the three slowest endpoints, measure p95 over 24h | 2h | Latency data shows >80% of wait time in API layer |
-| "The team will adopt the new tool" | Ask three team members individually: "Show me how you'd use this" | 1h | 2 of 3 can describe a use case without prompting |
+| "Users can complete the target task with the prototype" | Observe affected users attempting a representative task in a permitted environment | Timebox agreed for the task | Pre-agreed completion, error and assistance criteria; report sample and limits, not adoption |
 | "The data is clean enough for ML" | Sample 200 records, count nulls/duplicates/format errors | 1h | <5% error rate on the fields the model needs |
 
 **4. Run the killer test first.** The assumption with the highest blast radius AND the cheapest validation gets tested immediately. This single principle saves more engagement time than any other: if the killer assumption is wrong, you've saved weeks; if it holds, you've bought confidence. Write the kill observation in `How we test` as the result that would **stop** the plan - plan copies that line onto each Now PR as `Kill if`.
@@ -68,7 +68,7 @@ Evidence first, then the question. Let them reach the conclusion.
 | # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
 |---|------------|------|--------------|-------------|--------|----------|
 | 1 | API is the bottleneck | CONVENTION | CRITICAL | p95 instrumentation 24h | DISPROVED | 80% wait in DB layer (Day N) |
-| 2 | Team will adopt new tool | UNKNOWN | LOAD-BEARING | 3 individual interviews | CONFIRMED | 2/3 describe a use case unprompted |
+| 2 | Team will adopt new tool | UNKNOWN | LOAD-BEARING | Observe task use, then assess sustained use over an agreed period | OPEN | 2/3 describe a use case unprompted; interest reported, use not yet observed |
 | 3 | Data clean enough for ML | UNKNOWN | CRITICAL | 200-record sample | PARTIAL → OPEN follow-up | 12% nulls on key field; cleaning task added |
 ```
 
@@ -98,5 +98,5 @@ Result: acked in 40 minutes, by Marco, not finance. Assumption DISPROVED, and th
 - Kind before blast radius. A FACT with no receipt is UNKNOWN.
 - Kill the riskiest, cheapest-to-test assumption first.
 - Evidence first, then the question. Let the customer reach the conclusion.
-- A brief with zero disproved assumptions wasn't audited - it was accepted.
+- Design tests that could disprove consequential assumptions, and report what the evidence shows. All assumptions may survive a rigorous audit; never invent a contradiction to demonstrate skepticism.
 - Two weeks of building on a wrong assumption costs more than two hours of testing.

package/skills/test-assumptions/.fde-generated.json

@@ -5,6 +5,6 @@
     "SKILL.md": "acba10ec77763f1840c3cda95b26e13150683f6a7557a84a93611f2d96cdd389",
     "agents/openai.yaml": "c67e0342caba79241b1872cdfda8341f4949c2bd7672b8d288b529d8e94342b8",
     "references/task-context.md": "9066514a50043f3ad888d133d4e8b89b7132551e098cf2c80203c458a80126e5",
-    "references/test-assumptions.md": "bf60d8bb4c0701fcffb196d78f7f6c8b1c472fc877fb2caf41058fbf8e2415a1"
+    "references/test-assumptions.md": "b3349a5f82e741e34fb0d17e16712a070b31d87f413e554be40374dd79152086"
   }
 }

package/skills/test-assumptions/references/test-assumptions.md

@@ -47,7 +47,7 @@ CONVENIENCE - if wrong, a task changes but the approach holds
 | Assumption | Validation method | Effort | Evidence threshold |
 |-----------|-------------------|--------|-------------------|
 | "The API is the bottleneck" | Instrument the three slowest endpoints, measure p95 over 24h | 2h | Latency data shows >80% of wait time in API layer |
-| "The team will adopt the new tool" | Ask three team members individually: "Show me how you'd use this" | 1h | 2 of 3 can describe a use case without prompting |
+| "Users can complete the target task with the prototype" | Observe affected users attempting a representative task in a permitted environment | Timebox agreed for the task | Pre-agreed completion, error and assistance criteria; report sample and limits, not adoption |
 | "The data is clean enough for ML" | Sample 200 records, count nulls/duplicates/format errors | 1h | <5% error rate on the fields the model needs |
 
 **4. Run the killer test first.** The assumption with the highest blast radius AND the cheapest validation gets tested immediately. This single principle saves more engagement time than any other: if the killer assumption is wrong, you've saved weeks; if it holds, you've bought confidence. Write the kill observation in `How we test` as the result that would **stop** the plan - plan copies that line onto each Now PR as `Kill if`.
@@ -68,7 +68,7 @@ Evidence first, then the question. Let them reach the conclusion.
 | # | Assumption | Kind | Blast radius | How we test | Status | Evidence |
 |---|------------|------|--------------|-------------|--------|----------|
 | 1 | API is the bottleneck | CONVENTION | CRITICAL | p95 instrumentation 24h | DISPROVED | 80% wait in DB layer (Day N) |
-| 2 | Team will adopt new tool | UNKNOWN | LOAD-BEARING | 3 individual interviews | CONFIRMED | 2/3 describe a use case unprompted |
+| 2 | Team will adopt new tool | UNKNOWN | LOAD-BEARING | Observe task use, then assess sustained use over an agreed period | OPEN | 2/3 describe a use case unprompted; interest reported, use not yet observed |
 | 3 | Data clean enough for ML | UNKNOWN | CRITICAL | 200-record sample | PARTIAL → OPEN follow-up | 12% nulls on key field; cleaning task added |
 ```
 
@@ -98,5 +98,5 @@ Result: acked in 40 minutes, by Marco, not finance. Assumption DISPROVED, and th
 - Kind before blast radius. A FACT with no receipt is UNKNOWN.
 - Kill the riskiest, cheapest-to-test assumption first.
 - Evidence first, then the question. Let the customer reach the conclusion.
-- A brief with zero disproved assumptions wasn't audited - it was accepted.
+- Design tests that could disprove consequential assumptions, and report what the evidence shows. All assumptions may survive a rigorous audit; never invent a contradiction to demonstrate skepticism.
 - Two weeks of building on a wrong assumption costs more than two hours of testing.

package/skills/what-breaks/.fde-generated.json

@@ -5,6 +5,6 @@
     "SKILL.md": "cacffe6b01d36cde634be5e7f8a2127d701d3dac90b3000c414a648956839c5e",
     "agents/openai.yaml": "6c4b97d3268698d1eed0b628f9872351f29b91dd47c9de371a12c584983cb0fe",
     "references/task-context.md": "9066514a50043f3ad888d133d4e8b89b7132551e098cf2c80203c458a80126e5",
-    "references/what-breaks.md": "bc7f7b0d0dbaa4df520b263f0877474722ab223aac4cd6fd84b5112d9868715d"
+    "references/what-breaks.md": "fbf85539fe9c762d713c5772dbef731e96783d369610ba61b66fc220d9e50abf"
   }
 }

package/skills/what-breaks/references/what-breaks.md

@@ -68,6 +68,8 @@ Time to detect: <5 minutes via error rate alert
 
 **Ask the team:** "Is anything outside this repo reading from or writing to <the thing you're changing>?" The answer is almost always "yes, and here's one we forgot about."
 
+**5b. Check the consequences of success.** When a change alters throughput, workload or decision-making, trace what happens if it works as intended. Does faster intake move the queue to another team, increase review or recovery work, or reward a local metric while the overall outcome worsens? Use known capacity and observed behavior; label missing evidence rather than inventing downstream harm. Name the affected owner and an end-to-end outcome signal alongside the local improvement. Carry a relevant check into the existing plan and ship pulse. Skip this expansion when the change has no material workflow effect.
+
 **6. The 2am test.** For any SYSTEMIC or IRREVERSIBLE change, ask: "If this fails at 2am on Saturday, who gets woken up, what do they see, and what can they do?" If the answer is "they see nothing until Monday" - the monitoring plan needs work before the change ships.
 
 ## Artifact