fdeops 3.15.2 → 3.17.0

package/skills/fde/references/discover.md

@@ -31,15 +31,28 @@ Q: <one question that changes where you dig>
 GUESS: <your answer, so they can correct it>
 ```
 
-Stop when you can write the decision sentence under **Frame the decision first**. If a name, quote, or metric is still missing, write `unknown - ask:` - never invent ops folklore to make the map look complete.
+Stop when you can write the four lines under **Frame the decision first**. If a name, quote, or metric is still missing, write `unknown - ask:` - never invent ops folklore to make the map look complete.
 
 ## Frame the decision first
 
-Before any scanning, write one sentence at the top of your working notes:
+Same SCQA spine as readout (`S → C → Q → A`), aimed at the floor, not a deck. Write it **before** any scan. Confirm with the FDE, then dig.
 
-> "What will the sponsor do differently because of this discovery?"
+| Line | What it is | Fail if |
+|------|------------|---------|
+| **Situation** | What they already treat as true - the workaround, the sheet, the owner who left | It could be copied from the RFP |
+| **Complication** | What broke, so they cannot stay here | No tension, or three problems joined by "and" |
+| **Question** | One decision the named signer must make | It smuggles the solution ("how do we add alerting") |
+| **Answer-space** | Shape of a satisfying answer: confirm brief / descope / rescope / pause | A novel, or "insights" |
 
-If you can't name the decision this informs (descope? rescope? pick use case A over B? touch module X first?), you're collecting trivia, not discovering. Every output of this phase is aimed at that decision.
+Tests on **Question** - rewrite until all five hold:
+
+1. **Decision-shaped** - answering it changes what someone does.
+2. **Single** - one thing, not three.
+3. **Scoped** - who, where, by when.
+4. **Answerable** - evidence could settle it in this engagement.
+5. **Neutral** - does not assume the fix.
+
+Cannot write the Question → keep interrogating. Do not `fde scan`. Every later output of this phase aims at that Question. Sub-questions go to the operating map or `assumptions.md`, not into the Question.
 
 ## Method - part 1: the codebase (you do this work)
 
@@ -143,17 +156,22 @@ Score every candidate use case before anything gets prototyped:
 | Complexity | How hard to build safely? (5 = hardest) | |
 | Data readiness | Available, clean, sufficient volume today? | |
 
-**Score = (Value × Data readiness) / Complexity.** Highest score gets prototyped first (hand to `sketch`). A 5-value/1-complexity/5-readiness case scores 25; a 5-value/5-complexity/2-readiness case scores 2 - they look identical on a whiteboard. Never let a technically interesting use case override the score.
+**Score = (Value × Data readiness) / Complexity.** Highest score gets prototyped first (hand to `poc`). A 5-value/1-complexity/5-readiness case scores 25; a 5-value/5-complexity/2-readiness case scores 2 - they look identical on a whiteboard. Never let a technically interesting use case override the score.
 
 ## Artifact (this IS the memory - write it as you work)
 
-**`reality.md`** - the readout the FDE takes into the sponsor meeting:
+**`reality.md`** - the readout the FDE takes into the sponsor meeting. Keep the three schema lines the dashboard reads (`Working theory` / `Evidence` / `Differs from brief how`). Then the decision frame:
+
 ```markdown
 # Reality (actual problem)
-**Decision this informs:** <one line>
-**Confirmed:** <real problem> (evidence: <workaround/data/quote, source, day>)
-**Stated brief was wrong/right because:** <delta, with evidence>
-**Implication for build:** <thin-slice direction>
+**Working theory:** <the real problem, one sentence>
+**Evidence:** <workaround/data/quote, source, day>
+**Differs from brief how:** <delta, with evidence>
+**Situation:** <what the floor already treats as true>
+**Complication:** <what forces a decision now>
+**Question:** <one decision-shaped sentence>
+**Answer-space:** confirm brief / descope / rescope / pause - and what a yes looks like
+**Implication for build:** <first small PR>
 **Validated with:** <who, when>
 ```
 
@@ -180,11 +198,11 @@ Every line carries its evidence. `(churn: 47/90d)` `(ops lead, Day 5)` `(stated,
 ## Checkpoint (before any build)
 
 Present to the FDE, five things, one paragraph each - no padding:
-1. The real problem, with the two strongest pieces of evidence.
+1. The Question, then the real problem, with the two strongest pieces of evidence.
 2. The top 3 risk areas of the codebase, one line of why each.
 3. What must not be touched without characterisation tests.
 4. The exception-led operating map: the two breaks that matter most, who owns the workaround, and where shadow systems live.
-5. The recommendation: confirm brief / descope / rescope - and the decision it puts in front of the sponsor.
+5. The Answer-space: confirm brief / descope / rescope - and the decision it puts in front of the sponsor.
 
 If discovery revealed the problem is 3× the brief: the FDE tells the customer **before** telling themselves it's manageable. Lead with evidence, offer three paths (descope / rescope / pause-and-plan), confirm any reset in writing - update `success.md` and `brief.md` before continuing.
 
@@ -198,13 +216,14 @@ Acme's brief blamed missing monitoring. Discovery goes to the workaround first.
 
 `git log` shows the reconciliation module at 47 commits/90d with no tests, all from one author who left in February. Marco (ops lead) turns out to keep a spreadsheet: every morning he re-runs the job manually and eyeballs the totals - a habit nobody mentioned because to him it is just the job. That spreadsheet is the system of record when the job fails, which is the actual finding.
 
-`reality.md`: **Confirmed:** the job has no owner, and the manual re-run masks failures for a day (evidence: Marco's sheet, Day 5; two silent failures since March, finance escalation Mar 14). **Stated brief was wrong because:** alerting existed last year and was disabled - adding it again without an owner reproduces the same outcome. `terrain.md` gets the hotspot row and an operating-map row: `job fails silently → Marco notices next morning → re-runs by hand → spreadsheet is truth → LOAD-BEARING (Marco, Day 5)`.
+`reality.md` keeps the schema, then the frame. **Working theory:** the job has no owner, and the manual re-run masks failures for a day. **Evidence:** Marco's sheet, Day 5; two silent failures since March, finance escalation Mar 14. **Differs from brief how:** alerting existed last year and was disabled - adding it again without an owner reproduces the same outcome. **Situation:** Marco re-runs the job every morning and the spreadsheet is truth when it fails. **Complication:** two silent failures since March already hit finance, and the author of the module left in February. **Question:** should Priya fund a named owner on the failure path, or fund alerting and accept the same miss in six months? **Answer-space:** fund ownership / fund alerting-as-theatre / pause until she names who acks. `terrain.md` gets the hotspot row and an operating-map row: `job fails silently → Marco notices next morning → re-runs by hand → spreadsheet is truth → LOAD-BEARING (Marco, Day 5)`.
 
-Checkpoint to the FDE names the sponsor decision this creates: fund ownership, or fund alerting and accept the same failure in six months.
+Checkpoint to the FDE leads with that Question, not a tour of the repo.
 
 ## Principles
 
 - The brief is a hypothesis until evidence confirms it.
+- No scan until the Question is one decision the signer must make.
 - The workaround is more honest than the requirements document.
 - Churn data + the human's "don't touch that" pointing at the same module = the map is true.
 - Never modify code before the terrain map exists.

package/skills/fde/references/{trust-engineering.md → earn-trust.md}

@@ -1,4 +1,4 @@
-# trust-engineering - earning commit access one move at a time
+# earn-trust - earning commit access one move at a time
 
 **Enter when:** new engagement where you don't have full access yet, trust is thin, the customer said "let's start small," or you need to navigate "we don't trust AI-generated code."
 

package/skills/fde/references/{pattern-extract.md → encode-pattern.md}

@@ -1,4 +1,4 @@
-# pattern-extract - if you did it twice, encode it
+# encode-pattern - if you did it twice, encode it
 
 **Enter when:** the engagement is closing and reusable patterns exist, a technique worked well and will apply to future clients, the FDE notices themselves doing the same thing on a second engagement, or close identified a pattern worth preserving.
 

package/skills/fde/references/eval-pack.md

@@ -1,6 +1,6 @@
 # eval-pack - prove the system before it acts
 
-**Enter when:** the work touches AI/LLM/agents/RAG, or they need to POC a model, or ship/close is blocked because there is no evidence the non-deterministic path is safe. Activate alongside `ai.md`, `sketch`, `incremental-build`, or `ship` - not instead of them.
+**Enter when:** the work touches AI/LLM/agents/RAG, or they need to POC a model, or ship/close is blocked because there is no evidence the non-deterministic path is safe. Activate alongside `ai.md`, `poc`, or `ship` - not instead of them.
 
 **Read first:** `trust-profile.md` (AI policy + HITL), `terrain.md` (operating map), `delivery.md`. Create or extend `evals.md`.
 

package/skills/fde/references/{scope-defense.md → hold-scope.md}

@@ -1,4 +1,4 @@
-# scope-defense - holding the line without losing the relationship
+# hold-scope - holding the line without losing the relationship
 
 **Enter when:** "also can you…" mid-build, a stakeholder adds requirements without adjusting timeline, the FDE feels scope creeping but can't name it, or `success.md` no longer matches what's being asked.
 
@@ -67,7 +67,7 @@ Acme, week 5. Nothing has been formally added, and the slice is a week late.
 
 The pattern shows in three receipts, not one argument: a "quick" finance CSV export (Jun 20, half a day, from Denise directly), retry-logic cleanup asked for mid-build (Jun 24, one day, Tom), and a dashboard tile "while you're in there" (Jun 27, half a day). Each was individually reasonable; together they are the slip.
 
-Three-bucket response, applied at the moment of the third ask rather than in a retrospective: the CSV export goes to Next with an accepted trade (it displaces the runbook polish), the retry cleanup goes to the kill list in `decisions.md` with the blast-radius reason, and the tile is absorbed because it is genuinely twenty minutes - logged anyway, since an unlogged absorption is the one that gets forgotten in the accumulation conversation.
+Three-bucket response, applied at the moment of the third ask rather than in a retrospective: the CSV export goes to Next with an accepted trade (it displaces the runbook polish), the retry cleanup goes to the kill list in `decisions.md` with the what-breaks reason, and the tile is absorbed because it is genuinely twenty minutes - logged anyway, since an unlogged absorption is the one that gets forgotten in the accumulation conversation.
 
 That conversation happens with Priya at three receipts, with the dates on screen: "these are the four asks, here is the two days, here is what moved." Not a complaint - a decision she gets to make, with evidence, before the deadline makes it for her.
 

package/skills/fde/references/ingest.md

@@ -2,7 +2,7 @@
 
 **Enter when:** the FDE wants to catch the engagement up from external sources - "make sure Acme is up to date," "pull what's relevant," "grab today's Granola and Denise's last email." Raw transcripts and long emails that are too big to paste usefully.
 
-**Connect / capability (different entry):** "connect a new MCP", "connect Granola/Slack/Notion", "what can you pull?" → `references/ingest-connect.md` first. Recipes: `mcp/recipes/` (file, granola, slack, notion).
+**Connect / capability (different entry):** "connect a new MCP", "connect Granola/Slack/Notion", "what can you pull?" → `references/connect.md` first. Recipes: `mcp/recipes/` (file, granola, slack, notion).
 
 **Read first:** `context.md` (what's already logged, what's stale). Bind the engagement before staging anything.
 
@@ -22,7 +22,7 @@ List what you can actually call **this session**:
 
 1. **Sink** - `ingest_stage` / `fde ingest` available?
 2. **Sources** - which fetch tools exist (Granola-shaped, Slack, Notion, Drive, file-only)?
-3. Tell the FDE in one line: *I can pull from X; Y is not connected.* If they asked to pull Y and it is missing → switch to `ingest-connect.md`. Never pretend a source exists.
+3. Tell the FDE in one line: *I can pull from X; Y is not connected.* If they asked to pull Y and it is missing → switch to `connect.md`. Never pretend a source exists.
 
 ## Ground loop (you do this work)
 
@@ -60,7 +60,7 @@ When a staged fact came from a named source, carry `via:<source>` on the applied
 
 ## MCP sink + recipes
 
-Optional `mcp/fdeops-ingest` wraps the same verbs over stdio. Source MCPs remain separate - the FDE adds whichever fetch tools they trust. Setup coach: `ingest-connect.md`. Copy-paste recipes: `mcp/recipes/`.
+Optional `mcp/fdeops-ingest` wraps the same verbs over stdio. Source MCPs remain separate - the FDE adds whichever fetch tools they trust. Setup coach: `connect.md`. Copy-paste recipes: `mcp/recipes/`.
 
 ## Checkpoint
 

package/skills/fde/references/land.md

@@ -99,7 +99,7 @@ If `stakeholders.md` already has a `## Signal history` section (it does from the
 
 **`trust-profile.md`** - sacred data (`<private>` tagged), fears heard, AI policy, approval chain. Sensitive: skip for status reads; use CLI/redacted surfaces; never paste raw `<private>` into prompts or subagents.
 
-**`assumptions.md`** - seed every unverified claim from the brief (and the day-1 hypothesis) as rows with blast radius CRITICAL / LOAD-BEARING / CONVENIENCE and status `OPEN`. Do not wait for assumption-audit - land makes the register exist. Example:
+**`assumptions.md`** - seed every unverified claim from the brief (and the day-1 hypothesis) as rows with blast radius CRITICAL / LOAD-BEARING / CONVENIENCE and status `OPEN`. Do not wait for test-assumptions - land makes the register exist. Example:
 
 ```markdown
 | # | Assumption | Blast radius | How we test | Status | Evidence |
@@ -107,7 +107,7 @@ If `stakeholders.md` already has a `## Signal history` section (it does from the
 | 1 | <claim from brief> | CRITICAL | <cheapest falsifying test> | OPEN | (stated, unverified) |
 ```
 
-One falsifiable hypothesis about the real problem also goes at the bottom of `brief.md` - discover / assumption-audit will test it.
+One falsifiable hypothesis about the real problem also goes at the bottom of `brief.md` - discover / test-assumptions will test it.
 
 ## Checkpoint
 

package/skills/fde/references/{initiative-triage.md → pick-three.md}

@@ -1,4 +1,4 @@
-# initiative-triage - when 20 things are "urgent," pick the 3 that matter
+# pick-three - when 20 things are "urgent," pick the 3 that matter
 
 **Enter when:** a transformation engagement with a long list of initiatives, the customer's roadmap has more items than weeks, competing teams want different things, or the FDE needs to recommend what to do *first* across a complex programme.
 

package/skills/fde/references/plan.md

@@ -2,7 +2,7 @@
 
 **Enter when:** scope is understood and the work needs breaking down - a slice, a phase, or the whole delivery.
 
-**Read first:** `reality.md`, `success.md`, `terrain.md`, `stakeholders.md`. Load `business-case.md` if sketch produced one. Not the full folder.
+**Read first:** `reality.md`, `success.md`, `terrain.md`, `stakeholders.md`. Load `business-case.md` if poc produced one. Not the full folder.
 
 ## Validation gate (confirm understanding, clarify where it elevates)
 
@@ -22,13 +22,13 @@ An FDE plan is not a sprint backlog. The technical sequence is the easy part. Th
 
 ## Method (you do this work)
 
-**0. Lock scope first.** Read `success.md` and `assumptions.md`. If out-of-scope is undefined, define it now with the FDE - a plan on undefined scope accumulates silent commitments. If any CRITICAL assumption is still `OPEN`, stop and run assumption-audit / discover before sequencing work.
+**0. Lock scope first.** Read `success.md`, `assumptions.md`, and the **Question** on `reality.md`. If out-of-scope is undefined, define it now with the FDE - a plan on undefined scope accumulates silent commitments. If any CRITICAL assumption is still `OPEN`, stop and run test-assumptions / discover before sequencing work. If `reality.md` has no Question, stop and finish discover - you are sequencing trivia.
 
 **1. Work backwards from success.** What's the last thing that must be true before done? And before that? That's the dependency chain - not a wish list.
 
 **2. Front-load the fragile.** Check `terrain.md` hotspots. Risky modules go early - fail fast, not in week three.
 
-**3. Slice vertically.** Each task delivers something visible and testable end to end ("user submits form, sees it saved"), never a horizontal layer ("build the database layer").
+**3. One user action per change.** Each task delivers something visible and testable ("user submits form, sees it saved"), never a layer ("build the database layer"). See `ship`.
 
 **4. Size to 30-90 minutes, PR-sized.** Longer = two tasks. Each task implementable, testable, reviewable without a thousand-line diff.
 
@@ -36,7 +36,7 @@ An FDE plan is not a sprint backlog. The technical sequence is the easy part. Th
 
 **6. Stakeholder touchpoints every 2-3 tasks.** "Show progress to <name from stakeholders.md>." Not ceremony: a customer who sees small wins stays bought in; silence gets filled with doubt.
 
-**7. End with a kill list.** Every plan names what you will **not** do this phase. If everything is "later," you have no plan - you have a wish list. Cap **Now** at 3 slices (same discipline as initiative-triage).
+**7. End with a kill list.** Every plan names what you will **not** do this phase. If everything is "later," you have no plan - you have a wish list. Cap **Now** at 3 PRs (same discipline as pick-three).
 
 **Acceptance criteria gate:** no task moves to build without written happy-path AND unhappy-path criteria. Can't write them = the task isn't understood; the open question goes to the customer **before** the task starts. Vague criteria surface later as scope creep and rework.
 
@@ -54,6 +54,7 @@ Delivers: <what someone can see/test>
 Accepts: <happy path> / <unhappy path>
 Touches: <files/systems - blast radius declared upfront>
 Risk: <what could go wrong + fallback>
+Kill if: <the observation that voids this slice - copy from assumptions.md How we test, or the check that means stop>
 Verify: <specific check>
 Value promised: <business unit change this slice claims>
 
@@ -72,7 +73,7 @@ Value promised: <business unit change this slice claims>
 No kill list → not a finished plan. Reopen with the FDE until the deferrals are written.
 ## Checkpoint
 
-Walk the FDE through: sequence + why this order, where the fragile work sits, where the touchpoints land, the acceptance gate on task 1, and the kill list. One question: "Which stakeholder sees the first visible slice, and when?" Second: "Who accepted what we are not doing?"
+Walk the FDE through: sequence + why this order, where the fragile work sits, where the touchpoints land, the acceptance gate and **Kill if** on task 1, and the kill list. One question: "Which stakeholder sees the first visible slice, and when?" Second: "Who accepted what we are not doing?" Third: "What observation stops task 1 this week?"
 
 ## Method - estimation (when the sponsor asks "how long, how much?")
 
@@ -96,6 +97,7 @@ Every FDE gets asked this in week one. The honest answer is a range, not a numbe
 - Add 30% buffer for integration work (it always takes longer).
 - Add 50% buffer for AI/ML work (eval cycles are unpredictable).
 - Name assumptions explicitly: "assumes API docs are accurate", "assumes staging environment exists."
+- Each named assumption needs a **kill observation**: the result that voids the estimate. Copy it from `assumptions.md` → How we test. No kill observation = it is not an assumption, it is hope.
 - Revisit estimates every 2 weeks. An estimate that never updates is fiction.
 
 Write estimates to `decisions.md` under `## Sizing`. Include the assumptions - when they break, the estimate changes and the FDE has evidence for the conversation.
@@ -135,7 +137,7 @@ Never quietly update tasks. Name the reset: update `reality.md` and `success.md`
 
 Acme, after discover: the reconciliation job is unowned, Marco's spreadsheet is the real fallback.
 
-**Now** is three tasks, not eight. Task 1 is *failures reach a named human* - delivers a page to a rota, accepts "kill the job mid-run → the on-call is paged within 15 min", touches the job wrapper and the alert config, rollback is re-disable the route, verify by killing it in staging. Value promised: `risk-mitigation - a silent failure becomes a 15-minute one`.
+**Now** is three tasks, not eight. Task 1 is *failures reach a named human* - delivers a page to a rota, accepts "kill the job mid-run → the on-call is paged within 15 min", touches the job wrapper and the alert config, rollback is re-disable the route, **Kill if:** a real failure page is acked by nobody on the rota (the *finance would act* assumption, DISPROVED if Marco is the only name that answers), verify by killing it in staging. Value promised: `risk-mitigation - a silent failure becomes a 15-minute one`.
 
 The kill list in `decisions.md` is where the plan earns its keep: the rewrite of the reconciliation service that Tom keeps proposing goes there - *deferred, the failure mode is ownership not architecture (Priya accepted, Jun 12)* - along with the finance dashboard finance asked for directly. Both stay visible so the same argument is not re-litigated in week 4 without a receipt.
 
@@ -148,5 +150,6 @@ First visible slice goes to Marco, not Priya: he is the one whose morning change
 - Every 2-3 tasks, a stakeholder touchpoint. Trust decays without visibility.
 - No written acceptance criteria, no build.
 - No kill list, no finished plan.
-- Estimates are ranges, not promises. Name the assumptions.
+- No **Kill if** on a Now PR, that PR is hope.
+- Estimates are ranges, not promises. Name the assumptions and the observation that voids them.
 - Migrations: leaf nodes first, core last. Rollback before cutover.

package/skills/fde/references/{sketch.md → poc.md}

@@ -1,4 +1,4 @@
-# sketch - prototype to kill or confirm a direction
+# poc - kill or confirm a direction in a day
 
 **Enter when:** a direction needs validating before committing real build time - POC, spike, show something, de-risk, pick between use cases. The output is something a sponsor can reject in a room this week, not a polished product.
 

package/skills/fde/references/{status.md → readout.md}

@@ -1,4 +1,4 @@
-# status - the sponsor update that keeps the engagement alive
+# readout - the sponsor update that keeps the engagement alive
 
 **Enter when:** the weekly update is due, an exec asks "where are we," or the FDE says "I need to send Dana something." This artifact decides renewals; engineers underinvest in it.
 
@@ -24,7 +24,7 @@ Then add, still on the same page:
 
 Exec voice: no jargon, no hedging, every claim traceable (`(shipped Tue, delivery.md)`). Draft in the **FDE's voice, for the FDE to send** - never send anything yourself.
 
-For board / renewal / sponsor's boss (longer pyramid): use `exec-narrative.md`. Do not invent a second weekly format.
+For board / renewal / sponsor's boss (longer pyramid): use `board-memo.md`. Do not invent a second weekly format.
 
 ## Artifact
 

package/skills/fde/references/rescue.md

@@ -46,7 +46,7 @@ Customers remember who told them the truth before it cost them money.
 
 ## D. Pivot - the whole direction changed
 
-Not scope-defense (that's someone adding). This is: budget cut, new CTO arrives, strategic priority shift, acquisition changes everything, "we've decided to go a different direction." The engagement's foundation moved.
+Not hold-scope (that's someone adding). This is: budget cut, new CTO arrives, strategic priority shift, acquisition changes everything, "we've decided to go a different direction." The engagement's foundation moved.
 
 **Signals:** new leadership asks "why are we doing this?", the sponsor's boss questions ROI, a competing initiative gets the resources, the quarterly priorities deck doesn't mention your project, the team you're embedded in gets reorganized.
 

package/skills/fde/references/review.md

@@ -34,7 +34,7 @@ Also check:
 
 **Stage 1 fails → stop** if any SPLIT/DROP remains, or JUSTIFY lacks a written sentence. Quality review on out-of-scope code is wasted work. Record the mismatch (and the KEEP/JUSTIFY/SPLIT/DROP tally) in `decisions.md`.
 
-Stakeholder "also can you…" mid-build is `scope-defense` - different axis. This stage is **code vs claim**.
+Stakeholder "also can you…" mid-build is `hold-scope` - different axis. This stage is **code vs claim**.
 
 ## Stage 2 - is it safe to live with?
 

package/skills/fde/references/{rollback-drill.md → rollback.md}

@@ -1,4 +1,4 @@
-# rollback-drill - test the escape route before you need it
+# rollback - test the escape route before you need it
 
 **Enter when:** a deploy is planned for the next 48 hours, the FDE says "we can always revert," a previous rollback failed or took too long, or the engagement involves regulated/critical systems.
 

package/skills/fde/references/{handoff-engineering.md → runbook.md}

@@ -1,4 +1,4 @@
-# handoff-engineering - making yourself replaceable is the goal
+# runbook - making yourself replaceable is the goal
 
 **Enter when:** the engagement is entering its final phase, the customer team needs to operate without the FDE, a new FDE is taking over, or the sponsor asks "what happens when you leave?"
 
@@ -103,9 +103,9 @@ Rollback: <exact command and expected time>
 - [ ] All access returned or transferred (repos, environments, admin panels)
 - [ ] No personal credentials left in the system (API keys, tokens, SSH keys)
 - [ ] `.fde/` folder handed to the successor or archived with the team
-- [ ] Final status sent to sponsor (see `status.md`)
+- [ ] Final status sent to sponsor (see `readout.md`)
 - [ ] Retrospective completed (see `close.md`)
-- [ ] Patterns extracted (see `pattern-extract.md`)
+- [ ] Patterns extracted (see `encode-pattern.md`)
 
 ## Artifact
 

package/skills/fde/references/{use-case-scoring.md → score-use-cases.md}

@@ -1,8 +1,8 @@
-# use-case-scoring - pick the right battle, not the interesting one
+# score-use-cases - pick the right battle, not the interesting one
 
 **Enter when:** multiple potential use cases compete for attention, the customer says "we want to do everything," a transformation engagement needs a starting point, or the FDE needs to recommend which problem to solve first.
 
-**Read first:** `reality.md`, `brief.md`, `terrain.md`, `context.md`. If `business-case.md` or `prototype-log.md` exist from sketch, load those - they carry forward.
+**Read first:** `reality.md`, `brief.md`, `terrain.md`, `context.md`. If `business-case.md` or `prototype-log.md` exist from poc, load those - they carry forward.
 
 The most dangerous moment in a multi-use-case engagement is when the technically interesting problem wins over the high-value problem. Scoring replaces opinion with arithmetic. The arithmetic is wrong - all models are - but it's *visibly* wrong, which means it can be debated and corrected. Opinion can't.
 
@@ -59,7 +59,7 @@ Why this formula:
 
 ## Checkpoint
 
-Walk the FDE through the top 3 scores and the recommendation. One question: "Does the sponsor have a strong preference that overrides the scoring?" If yes, log it. If no, proceed with the highest score to sketch or plan.
+Walk the FDE through the top 3 scores and the recommendation. One question: "Does the sponsor have a strong preference that overrides the scoring?" If yes, log it. If no, proceed with the highest score to poc or plan.
 
 ## Principles
 

package/skills/fde/references/ship.md

@@ -1,10 +1,102 @@
-# ship - production without surprises
+# ship - on their site, then live
 
-**Enter when:** a slice is built, reviewed, and ready to deploy.
+**Enter when:** you are writing or updating on their codebase, they need to see something real, or you are going live.
 
-**Read first:** `context.md`, `delivery.md`, `success.md`. Load `trust-profile.md` if the deploy touches regulated data or needs an approval chain. Load `evals.md` when the deploy touches AI/ML/LLM/RAG/agents.
+**Read first:** `context.md`, `decisions.md`, `delivery.md`, `success.md`. Load `terrain.md` before you touch their code. Load `trust-profile.md` if the deploy touches regulated data or needs an approval chain. Load `evals.md` when the work touches AI/ML/LLM/RAG/agents.
 
-Opening question, calm tech lead voice: **has anyone actually *run* the rollback, or is it still a slide?** If only planned, that's today's work - say so plainly.
+Do not ask them to pick a mode. Name where you are, then start at the matching section:
+
+- Nothing on their staging yet → **one change they can see**
+- On staging, the signer in `success.md` can reject it → **go-live**
+- Prod is the question → **go-live**. Do not start a second change.
+
+If going live, opening question: **has anyone actually *run* the rollback, or is it still a slide?** If only planned, that's today's work - say so plainly.
+
+A same-day throwaway that kills an assumption is `poc`. This method is the real change on a repo they will own, then production.
+
+## Field (name it once, then the same loop)
+
+| | Brownfield | Greenfield |
+|--|------------|------------|
+| What you touch | Code they already run | A new path or empty tree they will own |
+| First move | Characterise their tests, their runner, the workaround in `terrain.md` | First path a user can click. Not the whole product. |
+| Proof | Their staging, a screen they already use | Their staging, or the environment they will operate. Local demo is not delivery. |
+| Undo | Revert this change on its own | Same. If you cannot undo it, the design is coupled. |
+
+Skip POC only when the killer assumption already lives in the repo (typical brownfield). If the bet is unproven, `poc` first.
+
+## Method - one change they can see
+
+One change = one thing a user can do, with a test, that you can revert on its own. Not "all the APIs, then all the UI." Not a 2,000-line dump. A PR is how this often lands. It is not the job. The job is the change they can see.
+
+```
+BAD (layers):
+  1: all database models
+  2: all API endpoints
+  3: all UI components
+  4: wire everything together (and pray)
+
+GOOD (one user action each):
+  1: User can create a payment (schema + endpoint + minimal UI) - testable
+  2: User can view payment status (query + endpoint + UI) - testable
+  3: Payment retry on failure (logic + endpoint + UI feedback) - testable
+  4: Admin can void a payment (auth + logic + UI) - testable
+```
+
+Each change is independently revertible.
+
+**Before you start this change:**
+
+- [ ] It is in `decisions.md` with acceptance criteria (happy + unhappy path)
+- [ ] Blast radius declared: which files, which systems, which users affected
+- [ ] Rollback named: revert this change, or something more specific
+- [ ] No dependency on an unmerged change (if dependent, state it and land in order)
+- [ ] `Kill if` is written - the observation that stops this change
+
+**The loop.** In this order:
+
+```
+Read existing code in the area (search before creating)
+  → Characterise what is already there (their tests, their runner; greenfield: the empty tree)
+    → Implement the smallest path that works
+      → Prove it on their staging (below)
+        → Cleanup pass (dedupe, simplify - behaviour unchanged)
+          → Self-review against acceptance criteria
+            → Commit with a message the client's team can read
+              → Update decisions.md + delivery.md
+```
+
+**Prove it on their staging.** A green check on your laptop is not delivery.
+
+- Run **their** test command, typecheck, or smallest proving path. Write the command and the result in `delivery.md`.
+- If the signer in `success.md` cannot reject this on a screen they already use, it is not proven.
+- Staging they operate beats a local demo. If you have no staging: `unknown - ask:` who owns an environment, then stop pretending it shipped.
+- Model in the path: `eval-pack` until `evals.md` says SHIP. Do not skip because "it looked right in chat."
+
+The proof is whatever this client already believes, plus one new receipt they can replay.
+
+**Size.** Each change targets:
+
+| Metric | Target | Why |
+|--------|--------|-----|
+| Lines changed | 100-300 | Reviewable in one sitting |
+| Time to implement | 30-90 minutes | Testable before context decays |
+| Files touched | 1-5 | Blast radius stays containable |
+| Tests added | ≥1 per new behaviour | Proves this change; guards against regression |
+
+Larger than 300 lines → split first. "It's all connected" means the design needs work, not a bigger dump.
+
+**Show it.** Every 2-3 changes, something the customer can see: an endpoint they can hit, a UI they can click, a metric that moved, a risk that was retired. Technical progress invisible to stakeholders is trust decay. `delivery.md` gets updated after every visible change.
+
+**The scope trap.** Mid-change discoveries ("this module also needs updating," "I should refactor this while I'm here"):
+
+- If it's in `decisions.md`: do it as a separate change.
+- If it's NOT in `decisions.md`: log it as a scope receipt (see `hold-scope.md`), don't touch it.
+- Ugly code outside this change stays ugly. That is discipline, not laziness.
+
+After each change: tests pass (state the command and result), acceptance criteria met, blast radius as declared, `Kill if` still false. After every 2-3: what did they see, and what's their signal? Then, when the signer can reject it on their staging, go-live below.
+
+---
 
 ## Deployment readiness gate (confirm the target before building the runway)
 
@@ -24,7 +116,7 @@ Before scoring readiness, confirm WHERE this is going. State it in 2-3 lines - b
 | **Compliance** | Region constraints? Data residency? Encryption requirements? CAB/change window? | |
 | **Infra-as-code** | Terraform/Pulumi/CDK/manual? State file location? | |
 
-**If anything is blank:** ask now. Discovering deployment constraints AFTER build is where timelines slip. If the client hasn't defined these yet, that's a conversation before you write the runbook - not after.
+**If anything is blank:** ask now. Discovering deployment constraints after the change is where timelines slip. If the client hasn't defined these yet, that's a conversation before you write the runbook - not after.
 
 Write confirmed deployment context to `delivery.md` under a `## Deployment target` section.
 
@@ -46,9 +138,9 @@ Score each dimension green/amber/red. This is the gate, not a suggestion:
 
 | Dimension | Green | Amber | Red |
 |-----------|-------|-------|-----|
-| **Value bucket** | `success.md` names primary bucket (`cost-save` \| `risk-mitigation` \| `revenue-uplift`) and a baseline→target metric; this slice’s value-ledger row has **Bucket** + **Promised** | Bucket named; **Measured** still `pending` with a pulse date | No bucket, or Promised empty / ticket-theater only |
-| **Audit receipt** | Dated line in `delivery.md` (`## Ship receipts` or ledger Evidence) proving exceptions/operating path were walked - cite `terrain.md` / `reality.md` / `audit.md` | Path described, not verified this ship | No audit receipt for this slice |
-| **Eval receipt** | **n/a** (no AI on this slice) **or** `evals.md` Verdict SHIP with dated golden run + HITL gate named | Eval pack exists; known fails open with owner + date | AI in scope and no eval receipt |
+| **Value bucket** | `success.md` names primary bucket (`cost-save` \| `risk-mitigation` \| `revenue-uplift`) and a baseline→target metric; this change's value-ledger row has **Bucket** + **Promised** | Bucket named; **Measured** still `pending` with a pulse date | No bucket, or Promised empty / ticket-theater only |
+| **Audit receipt** | Dated line in `delivery.md` (`## Ship receipts` or ledger Evidence) proving exceptions/operating path were walked - cite `terrain.md` / `reality.md` / `audit.md` | Path described, not verified this ship | No audit receipt for this change |
+| **Eval receipt** | **n/a** (no AI on this change) **or** `evals.md` Verdict SHIP with dated golden run + HITL gate named | Eval pack exists; known fails open with owner + date | AI in scope and no eval receipt |
 | **AI eval pack** | `.fde/evals.md` Verdict SHIP; goldens run this change; critical fails 0; HITL filled if policy requires | Pack exists; run stale vs change log | AI-touching deploy and pack missing / NO-SHIP / HITL required but empty |
 
 **Any RED = stop. Do not deploy. Fix the red dimension first.**
@@ -65,7 +157,7 @@ Write the readiness score (including value + receipts) to `delivery.md` before d
 
 ## Intent vs diff (before pre-blast)
 
-Ship the change you intended - not the drift that snuck in. Run this on the deploy branch against the **one-line intent** from `decisions.md` / `success.md` (the slice you said you were building).
+Ship the change you intended - not the drift that snuck in. Run this on the deploy branch against the **one-line intent** from `decisions.md` / `success.md` (the change you said you were building).
 
 ```bash
 git diff <base>...HEAD --stat
@@ -78,12 +170,12 @@ Score every touched path (or logical hunk):
 |---------------|---------|------|
 | | **KEEP** | Directly required for the stated intent |
 | | **JUSTIFY** | Adjacent but load-bearing - one sentence why it must ship *now*, or split |
-| | **SPLIT** | Real work, wrong PR - park in `decisions.md` kill/Next; do not deploy with this slice |
+| | **SPLIT** | Real work, wrong change - park in `decisions.md` kill/Next; do not deploy with this one |
 | | **DROP** | Noise (format-only, drive-by rename, unrelated tidy) - revert before ship |
 
 **Any SPLIT or DROP still in the tree = fix-first.** JUSTIFY without a written sentence = treat as SPLIT. Log a one-line receipt in `delivery.md`: `intent vs diff: KEEP n · JUSTIFY n · SPLIT n · DROP n - <intent>`.
 
-This is **code drift**, not stakeholder "also can you…" (that is `scope-defense`). Same family as review Stage 1 - ship refuses green when the diff outgrew the claim.
+This is **code drift**, not stakeholder "also can you…" (that is `hold-scope`). Same family as review Stage 1 - ship refuses green when the diff outgrew the claim.
 
 ## Pre-blast challenge (before the deploy button)
 
@@ -164,12 +256,12 @@ Never skip a step. The sponsor always wants to skip from pilot to standard - tha
 
 ## Method - progressive adoption (built it, now people need to use it)
 
-Adoption isn't a handoff-stage problem - it starts during build. Software that launches to silence is software that gets decommissioned.
+Adoption isn't a handoff-stage problem - it starts while you are still writing the change. Software that launches to silence is software that gets decommissioned.
 
-**During build:**
+**During the change:**
 - **Feature flags from day one.** Every new capability behind a flag. Ship to 5% of users first. Watch behavior before opening to 100%.
 - **Feedback loops built in.** A thumbs-up/down, a "was this helpful?", a usage counter. Instrument adoption, don't assume it.
-- **Resistance signals.** Watch for: workaround creation (they built a spreadsheet instead of using the tool), drop-off after day 3 (onboarding fails), vocal detractors (one influential skeptic can kill adoption). Address these DURING build, not after launch.
+- **Resistance signals.** Watch for: workaround creation (they built a spreadsheet instead of using the tool), drop-off after day 3 (onboarding fails), vocal detractors (one influential skeptic can kill adoption). Address these before launch, not after.
 
 **At launch:**
 - **Champion network.** Identify 2-3 power users per team who adopt early. Support them intensely - they become your multiplier.
@@ -180,24 +272,35 @@ Adoption isn't a handoff-stage problem - it starts during build. Software that l
 
 ## Artifact
 
-**`delivery.md`** - deployment record: what shipped, when, what it delivers in business terms, rollback procedure, pulse definition, **scale-readiness assessment, and adoption metrics**. Written for whoever inherits the system.
+**`decisions.md`** - each change: what was implemented, what was tested, what was deferred, `Kill if`.
+
+**`delivery.md`** - each visible change in business language; then the deployment record: what shipped, when, rollback procedure, pulse definition, **scale-readiness assessment, and adoption metrics**. Written for whoever inherits the system.
 
 ## Checkpoint
 
-Before 100%: canary clean, business metric verified, pulse written into `delivery.md`. Also green: value bucket named, audit receipt dated, eval receipt **n/a or pass**, **intent vs diff clean** (no unresolved SPLIT/DROP). Missing any of those → not green. For enterprise-scale: scale-readiness gate passed before broad rollout.
+After each change: tests pass, acceptance criteria met, blast radius as declared, `Kill if` still false, proven on staging they operate.
+
+Before 100% live: canary clean, business metric verified, pulse written into `delivery.md`. Also green: value bucket named, audit receipt dated, eval receipt **n/a or pass**, **intent vs diff clean** (no unresolved SPLIT/DROP). Missing any of those → not green. For enterprise-scale: scale-readiness gate passed before broad rollout.
 
 ## Worked example
 
-Acme, shipping the failure-routing slice into a payments environment on a Thursday.
+Acme, brownfield. Plan Now has three changes, not "the payments rewrite."
 
-Readiness scoring catches two things the diff does not. The audit receipt is missing: the operating map says Marco's manual re-run is the fallback, and nobody has checked whether the new page fires *before* his morning run or after - if after, the alert changes nothing. That gets walked and cited before deploy. Second, the intent-vs-diff read shows the PR also touches the settlement retry that was deferred in build; it comes out.
+Change 1 is *user sees retry status on a failed payment* - schema + endpoint + the existing ops screen, 180 lines, their `pytest -k payments` green, revert is this change. `Kill if:` the signer cannot reject it on the screen they already use. Ugly retry-queue code two files over stays ugly. `decisions.md` logs the change; `delivery.md` says ops can see a retry without opening the spreadsheet. Marco sees it on staging they operate. That is the proof. Local green was not.
+
+Then Thursday go-live of the failure-routing change. Readiness scoring catches two things the diff does not. The audit receipt is missing: the operating map says Marco's manual re-run is the fallback, and nobody has checked whether the new page fires *before* his morning run or after - if after, the alert changes nothing. That gets walked and cited before deploy. Second, the intent-vs-diff read shows the PR also touches the settlement retry that was deferred; it comes out.
 
 Pre-blast challenge: "what does this break if it fires at 3am and nobody acks?" Answer: nothing breaks, but the rota is not yet agreed - so the deploy waits on a name, not on code. That is a one-day slip that prevents a fake green.
 
 After deploy: `delivery.md` ship receipt with the audit cite, the kill test evidence, and the rollback line. Eval receipt: n/a, no AI in this path.
 
+Greenfield is the same loop with an empty tree: first path a user can click, on an environment they will operate, then this go-live. Not the whole product in one dump.
+
 ## Principles
 
+- One user action per change. Layers are untestable until assembled.
+- On their staging, and you can undo it. Local green is not delivery.
+- The ugly code outside this change stays ugly. That's discipline, not laziness.
 - A deployment without a tested rollback is reckless.
 - Roll back on any canary anomaly; investigate safely.
 - Verify the business metric, not just the technical one.

package/skills/fde/references/{multi-customer-ops.md → switch-clients.md}

@@ -1,4 +1,4 @@
-# multi-customer-ops - juggling engagements without dropping any
+# switch-clients - juggling engagements without dropping any
 
 **Enter when:** the FDE is running 2+ engagements simultaneously, context-switching is causing mistakes or delays, a new customer is being onboarded while existing engagements are active, or the FDE says "I'm losing track."
 

package/skills/fde/references/{assumption-audit.md → test-assumptions.md}

@@ -1,4 +1,4 @@
-# assumption-audit - pressure-test the brief before building on it
+# test-assumptions - pressure-test the brief before building on it
 
 **Enter when:** the brief feels too neat, the customer is very confident about the solution (not the problem), someone says "we just need…" about a complex system, or discover surfaced contradictions between what was said and what the codebase shows.
 
@@ -40,7 +40,7 @@ CONVENIENCE - if wrong, a task changes but the approach holds
 | "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 |
 | "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.
+**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`.
 
 **5. Present findings as a fact base, not a challenge.**
 

package/skills/fde/references/{options-analysis.md → three-options.md}

@@ -1,4 +1,4 @@
-# options-analysis - three paths, not one recommendation
+# three-options - three paths, not one recommendation
 
 **Enter when:** a significant technical or strategic decision needs to be made, the FDE is asked "what should we do?", the team is stuck between approaches, or a fork in the engagement requires the sponsor's input.