fdeops 3.16.0 → 3.20.0

package/skills/fde/references/ship.md

@@ -1,10 +1,106 @@
-# ship - production without surprises
+# ship - Deliver the increment
 
-**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 skill 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.
+
+**Done means:** the signer in `success.md` can reject this on staging they operate. A green check on your laptop is not delivery. Do not start the next change until this one is rejectable.
+
+If `terrain.md` **Data estate** lists a **Blocker** this change depends on: stop. That is discover, not ship. Do not build a path they cannot feed.
+
+## 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 +120,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 +142,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 +161,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,7 +174,7 @@ 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>`.
@@ -164,12 +260,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 +276,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/switch-clients.md

@@ -1,4 +1,4 @@
-# switch-clients - juggling engagements without dropping any
+# switch-clients - Switch engagements
 
 **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/test-assumptions.md

@@ -1,4 +1,4 @@
-# test-assumptions - pressure-test the brief before building on it
+# test-assumptions - Test assumptions
 
 **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/three-options.md

@@ -1,4 +1,4 @@
-# three-options - three paths, not one recommendation
+# three-options - Generate options
 
 **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.
 

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

@@ -1,4 +1,4 @@
-# what-breaks - know what breaks before you touch it
+# what-breaks - Assess impact
 
 **Enter when:** about to make a change on a system you don't fully understand, touching a high-churn module from `terrain.md`, modifying shared infrastructure (auth, database, messaging), or the FDE asks "what could go wrong?"
 

package/skills/fde/references/who-decides.md

@@ -1,4 +1,4 @@
-# who-decides - reading the room before it reads you
+# who-decides - Map decision rights
 
 **Enter when:** new stakeholders appear, signals shift mid-engagement, a meeting felt off but you can't say why, or it's been two weeks and the map hasn't been updated.
 

package/templates/.fde/assumptions.md

@@ -8,4 +8,4 @@
 **Blast radius:** `CRITICAL` · `LOAD-BEARING` · `CONVENIENCE`  
 **Status:** `OPEN` · `TESTING` · `CONFIRMED` · `DISPROVED` · `PARKED`
 
-**Rule:** a CRITICAL assumption still OPEN blocks plan. DISPROVED → update `reality.md` / `success.md` and log the reset in `decisions.md` the same day.
+**Rule:** a CRITICAL assumption still OPEN blocks plan. `How we test` is the kill observation (the result that stops the work) - plan copies it as `Kill if`. DISPROVED → update `reality.md` / `success.md` and log the reset in `decisions.md` the same day.

package/templates/.fde/reality.md

@@ -1,7 +1,12 @@
 # Reality (actual problem)
 
-<!-- Hypothesis until the discover phase confirms with evidence. -->
+<!-- Hypothesis until the discover phase confirms with evidence. Dashboard reads Working theory / Evidence / Differs from brief how. -->
 
 **Working theory:**
 **Evidence:**
 **Differs from brief how:**
+
+**Situation:**
+**Complication:**
+**Question:**
+**Answer-space:**

package/templates/.fde/terrain.md

@@ -9,7 +9,7 @@
 ## Operating map (exception-led)
 
 <!-- How work actually runs when the happy path fails. Fill in discover; leave blank until heard/seen.
-     fde doctor requires ≥1 real exception row before plan/build/ship/close. -->
+     fde doctor requires ≥1 real exception row before plan/ship/outcome/close. -->
 
 | Exception / break | Who notices first | What they do today (workaround) | System of record then | Blast if wrong | Evidence |
 |-------------------|-------------------|---------------------------------|-----------------------|----------------|----------|

package/skills/fde/references/thin-slices.md

@@ -1,100 +0,0 @@
-# thin-slices - thin slices on someone else's codebase
-
-**Enter when:** the build task is larger than a single PR, multiple files or systems are involved, or the FDE needs to show visible progress to a stakeholder every 2-3 days.
-
-**Read first:** `decisions.md` (the plan), `terrain.md` (the danger zones), `context.md`. This skill works *inside* the build phase - it's the execution discipline that makes large features safe on codebases you don't own.
-
-The FDE who builds a 2,000-line feature in one PR gets it rejected. The FDE who ships five 200-line PRs - each reviewable, testable, and revertible - earns the team's trust. On someone else's codebase, small and visible beats clever and large.
-
-## Method (you do this work)
-
-**1. Slice vertically, never horizontally.**
-
-```
-BAD (horizontal):
-  PR 1: Build all database models
-  PR 2: Build all API endpoints
-  PR 3: Build all UI components
-  PR 4: Wire everything together (and pray)
-
-GOOD (vertical):
-  PR 1: User can create a payment (schema + endpoint + minimal UI) - testable
-  PR 2: User can view payment status (query + endpoint + UI) - testable
-  PR 3: Payment retry on failure (logic + endpoint + UI feedback) - testable
-  PR 4: Admin can void a payment (auth + logic + UI) - testable
-```
-
-Each vertical slice delivers working functionality the customer can see. Each slice is independently revertible.
-
-**2. The slice checklist.** Before starting any slice:
-
-- [ ] Slice is in `decisions.md` with acceptance criteria (happy + unhappy path)
-- [ ] Blast radius declared: which files, which systems, which users affected
-- [ ] Rollback path identified: "revert this PR" or something more specific
-- [ ] No dependency on an unmerged slice (if dependent, state it and merge in order)
-
-**3. The implementation loop.** For each slice, in this order:
-
-```
-Read existing code in the area (search before creating)
-  → Characterise what is already there (their tests, their runner)
-    → Implement the minimal working path
-      → On-site proof (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
-```
-
-**On-site proof.** A green check on your laptop is not delivery. Before the slice is done:
-
-- 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 slice 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."
-
-Do not prove it with a textbook ritual. The proof is whatever this client already believes, plus one new receipt they can replay.
-
-**4. Size discipline.** Each slice 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 the slice works; guards against regression |
-
-A slice larger than 300 lines → split before implementing. "It's all connected" means the design needs work, not the slice limit.
-
-**5. Stakeholder visibility rhythm.** Every 2-3 slices, something the customer can see:
-
-- A working endpoint they can hit
-- A UI change 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 slice.
-
-**6. The scope trap.** Mid-slice 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 slice.
-- If it's NOT in `decisions.md`: log it as a scope receipt (see `hold-scope.md`), don't touch it.
-- The hardest discipline: leaving ugly code alone when it's not in your slice.
-
-## Artifact
-
-**`decisions.md`** - each slice logged with: what was implemented, what was tested, what was deferred.
-
-**`delivery.md`** - each visible slice with business-language description of what it delivers.
-
-## Checkpoint
-
-After each slice: tests pass (state the command and result), acceptance criteria met, blast radius as declared. After every 2-3 slices: stakeholder visibility confirmed - what did they see, and what's their signal?
-
-## Principles
-
-- Vertical slices, always. Horizontal layers are untestable until assembled.
-- 100-300 lines per slice. Larger means split first.
-- Every slice is independently revertible. If it isn't, the design is coupled.
-- Visible progress every 2-3 slices. Technical progress alone is trust decay.
-- The ugly code outside your slice stays ugly. That's discipline, not laziness.