fdeops 3.5.0

package/skills/fde/references/discover.md

@@ -0,0 +1,163 @@
+# discover - find the real problem, map the terrain
+
+**Enter when:** the brief feels wrong, the real problem is unclear, shadow processes are suspected, or any phase found that the map is missing.
+
+**Read first:** `context.md`, `brief.md`. Load `terrain.md` if it exists - extend it, never regenerate from scratch.
+
+## Frame the decision first
+
+Before any scanning, write one sentence at the top of your working notes:
+
+> "What will the sponsor do differently because of this discovery?"
+
+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.
+
+## Method - part 1: the codebase (you do this work)
+
+**First move: `fde scan`** - it runs everything below deterministically in seconds (churn×tests, "temporary" archaeology, AI components, secrets redacted, previous attempts). Your job is then **interpretation**: read its output against the brief, follow the hotspots into the code, and connect the technical findings to the human signals in part 2.
+
+If the CLI is unavailable, run the manual commands below. Either way: do not load the full codebase into context - scan wide, read deep only on hotspots.
+
+**1. Stack and age.** Language, framework, build system, date of last major upgrade:
+```bash
+git log --reverse --format="%ad" --date=short | head -1   # repo birth
+git log -1 --format="%ad" --date=short                     # last commit
+```
+
+**2. Churn heat - the modules everyone touches but fears:**
+```bash
+git log --since="90 days ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20
+```
+The highest-churn file in a legacy codebase is the one everyone is afraid to refactor but cannot avoid touching. Cross-reference with complexity (file size, nesting) and mark "handle with care."
+
+**3. Test gaps - what's covered, what's a lie:**
+```bash
+find . -path ./node_modules -prune -o -name "*test*" -print | head -30
+```
+Map test files against the churn list. A high-churn module with no test neighbors is a load-bearing wall with no insurance. Spot-read the tests that do exist: tests that pass but assert nothing are worse than no tests - note them.
+
+**4. The "temporary" archaeology** (repeat `--include` per extension - brace globs silently match nothing):
+```bash
+grep -rnE "HACK|FIXME|XXX|temporary|for now|remove this|workaround" \
+  --include="*.js" --include="*.ts" --include="*.py" --include="*.java" \
+  --include="*.go" --include="*.rb" --include="*.cs" --include="*.php" . | head -30
+```
+Temporary code in production is permanent code with an excuse. Each hit is a candidate for "what was never built properly."
+
+**5. AI components - they fail silently:**
+```bash
+grep -rlnE "openai|anthropic|llm|prompt|embedding|vector|inference" \
+  --include="*.js" --include="*.ts" --include="*.py" --include="*.java" \
+  --include="*.go" . | head -20
+```
+Flag every one. AI components don't fail like regular code - they degrade as the world changes. Each needs: model version, fallback path (or note its absence), observability (or note its absence).
+
+**6. Data flow.** Where data enters, how it moves, where it stops. Entry points first: routes, queues, cron, file drops.
+
+## Method - part 2: the humans (you coach, the FDE asks)
+
+The real spec is what people **do** when the system fails - not what the slide deck says. Arm the FDE with these, in their own words:
+
+- **"How is the team coping today without the fix?"** - the workaround is the honest requirements doc.
+- **Find the spreadsheet.** Almost always there. Whoever maintains it is the best interview in the building.
+- **The hesitation.** When someone says "well, there's also this other thing we do…" - stop them, ask them to finish. The main story is what they're comfortable explaining; the hesitation is the real problem.
+- **"Which part of the codebase do you least want to touch?"** The answer is unanimous and it's the load-bearing wall. Check it against your churn scan - when the human answer and the churn data agree, that's your first map landmark.
+- **Shadow AI.** Someone pasting data into ChatGPT to cope = a real unmet need + an uncontrolled data risk. Note both.
+
+## Method - part 3: workshop facilitation
+
+When discovery requires a structured session with multiple stakeholders (alignment, prioritisation, design):
+
+**Before the room:**
+- Define the single decision the workshop must produce - not "discuss options" but "rank the three candidates and commit to one."
+- Cap at 8 people. Every person above 8 halves the probability of a decision.
+- Time-box: 90 minutes max. Anything longer splits into two sessions.
+- Pre-read: one page, sent 48 hours ahead. Nobody will read more.
+
+**In the room (the FDE facilitates, not presents):**
+1. **5 min - frame.** One slide: the decision, the constraint, the deadline. No history lesson.
+2. **15 min - diverge.** Silent post-its (or digital equivalent). Everyone writes before anyone talks - prevents the loudest voice dominating.
+3. **20 min - cluster.** Group themes, name them. The FDE does NOT label - the room labels.
+4. **30 min - converge.** Dot-vote or forced-rank. The FDE counts, the room decides.
+5. **10 min - lock.** State the decision back. "We're saying X. Anyone who can't live with this, speak now." Silence = consent.
+6. **10 min - next steps.** Who does what by when. Written before people stand up.
+
+**After the room:** Summary in `decisions.md` within 2 hours. Decisions decay - what felt clear at 3pm is debatable by 5pm if unwritten.
+
+## Method - part 4: data estate assessment
+
+When the engagement involves AI, analytics, or data-heavy automation, assess the data estate before scoring use cases:
+
+**The 5 questions (ask the data owner, not the sponsor):**
+1. **Where does data live?** - List every source: databases, warehouses, SaaS exports, spreadsheets, S3 buckets, vendor APIs. Map it.
+2. **How fresh is it?** - Real-time, daily batch, "someone uploads a CSV on Mondays"? Freshness determines what's buildable.
+3. **Who owns it?** - Not "IT" - the named person who can grant access and explain the schema. No name = no access in practice.
+4. **What's the quality?** - Sample 100 rows from each critical source. Check: nulls, duplicates, format consistency, semantic correctness. A 60% null rate in a key field = that source is fiction.
+5. **What are the governance constraints?** - PII classification, retention policies, cross-border rules, consent basis. One missed constraint = a compliance stop later.
+
+**The data readiness matrix:**
+
+| Source | Location | Freshness | Owner | Quality (sample) | Governance | Verdict |
+|--------|----------|-----------|-------|-----------------|------------|---------|
+| _fill per source_ | | | | | | Ready / Needs work / Blocker |
+
+A use case that depends on a "Blocker" source doesn't get scored - it gets a data remediation conversation first. Write this to `terrain.md` under a `## Data estate` section.
+
+## When scope is a transformation, not a single problem
+
+Score every candidate use case before anything gets prototyped:
+
+| Dimension | Question | 1–5 |
+|---|---|---|
+| Business value | What does it cost them unsolved? | |
+| 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.
+
+## Artifact (this IS the memory - write it as you work)
+
+**`reality.md`** - the readout the FDE takes into the sponsor meeting:
+```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>
+**Validated with:** <who, when>
+```
+
+**`terrain.md`** - the map every later phase loads:
+```markdown
+# Terrain
+**Stack:** <lang/framework/build, age>
+**Hotspots (handle with care):** <file - churn n/90d - tests: none/weak/ok - why it matters>
+**AI components:** <file - model - fallback? - observability?>
+**Data flow:** <entry → transform → store → exit>
+**Test landscape:** <covered / gaps / lies>
+**Unknowns:** <named explicitly - an honest gap beats a confident guess>
+```
+
+Every line carries its evidence. `(churn: 47/90d)` `(ops lead, Day 5)` `(stated, unverified)`.
+
+## Checkpoint (before any build)
+
+Present to the FDE, four things, one paragraph each - no padding:
+1. 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 recommendation: 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.
+
+## If you've formed three wrong reads
+
+Stop. Don't form a fourth hypothesis. Three disproven reads means the brief is actively misleading - usually the person who briefed doesn't know, or knows and can't say. Change method: stop analysing the system, ask three people separately "if you had to bet on what's actually wrong here, what would you say?" The thing they all hesitate before saying is the real problem.
+
+## Principles
+
+- The brief is a hypothesis until evidence confirms it.
+- 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.
+- Scan wide, read deep only on hotspots.

package/skills/fde/references/exec-narrative.md

@@ -0,0 +1,108 @@
+# exec-narrative - the story that gets the next phase funded
+
+**Enter when:** the sponsor's boss needs a summary, a board update mentions the engagement, the FDE needs to justify continued investment, or a quarterly review is approaching.
+
+**Read first:** `delivery.md`, `success.md`, `reality.md`, `risks.md`, `stakeholders.md`, `context.md`. The narrative is built from the engagement record, not from memory.
+
+Technical FDEs lose renewals by presenting work instead of outcomes. The exec doesn't want to know what was built - they want to know what it changed. A good exec narrative takes 60 seconds to deliver and survives hostile questions.
+
+## Method (you do this work)
+
+**1. The Pyramid Principle.** One governing thought, supported by three arguments, each backed by evidence. The exec hears the conclusion first, not the journey:
+
+```
+GOVERNING THOUGHT: (one sentence - the conclusion)
+"The payment processing overhaul cut manual reconciliation from 
+3 FTEs to 0.5 FTE and eliminated the $2M annual audit risk."
+
+SUPPORT 1: What was done (one paragraph)
+  → Evidence from delivery.md
+
+SUPPORT 2: What it saved (quantified)
+  → Evidence from business-case.md + delivery.md
+
+SUPPORT 3: What's next (the ask)
+  → Evidence from decisions.md + risks.md
+```
+
+**2. Four narrative lengths.** The same story, scaled for the context:
+
+| Length | When | Format |
+|--------|------|--------|
+| **30 seconds** | Elevator, hallway, Slack thread | The governing thought + one number |
+| **2 minutes** | Stand-up, exec check-in | Governing thought + 3 supports + the ask |
+| **10 minutes** | Quarterly review, steering committee | Full pyramid + hard questions answered + visual |
+| **60 minutes** | Board presentation, transformation review | Full pyramid + demos + deep-dive appendix |
+
+Write all four. The FDE will need different lengths at different moments - having them pre-written means they're never caught improvising.
+
+**3. The opening frame - SCQA.** Structure the first 30 seconds:
+
+| Element | Purpose | Example |
+|---------|---------|---------|
+| **Situation** | Where we are (shared context) | "We started this engagement to fix the payment failures that were costing $200K/month in manual reconciliation." |
+| **Complication** | What changed or what's at stake | "The problem was deeper than expected - the reconciliation failures traced to a data integrity issue in the core ledger." |
+| **Question** | The decision the exec needs to make | "Should we extend the engagement to fix the root cause, or ship the workaround?" |
+| **Answer** | Your recommendation | "Fix the root cause. The workaround adds $40K/year in maintenance and doesn't eliminate the audit risk." |
+
+**4. Value in their units.** Translate every technical achievement:
+
+| What you did (internal) | What it means (their units) |
+|------------------------|---------------------------|
+| Reduced p95 latency from 3s to 200ms | Customers complete checkout 15x faster |
+| Added test coverage from 12% to 78% | Change failure rate dropped from 40% to 5% |
+| Migrated from monolith to three services | Team can deploy independently - shipping frequency from monthly to weekly |
+| Built ML fraud detection | $1.2M/year in fraud losses reduced to <$200K projected |
+
+Never: "we refactored the authentication module." Always: what the refactoring *did* for them.
+
+**5. Pre-wire the hostile questions.** Before any exec presentation, write the five toughest questions and one-line answers:
+
+```markdown
+## Hard questions - <presentation date>
+1. "Why did this take longer than estimated?"
+   → The original brief assumed API-only work; discovery revealed a database integrity issue. We surfaced it in week 2 instead of shipping a patch that would have required rework.
+
+2. "How do we know it won't break again?"
+   → Three guards: automated reconciliation check (runs daily), alerting on drift >0.1%, and the characterisation test suite covering the 12 failure modes we found.
+
+3. "What happens when the FDE leaves?"
+   → Handoff document written for the 2am scenario. The team ran the runbook independently last Thursday - no callbacks.
+
+4. "Why should we fund phase 2?"
+   → Phase 1 addressed the bleeding. Phase 2 eliminates the root cause. Without it: $40K/year maintenance on the workaround + the audit risk remains.
+
+5. "Can the internal team do phase 2 without you?"
+   → They can, with 2x the timeline. The value of an FDE in phase 2 is speed - the patterns are established and the trust with the ledger team is built.
+```
+
+**6. The one number.** Every exec narrative needs a single memorable quantity:
+
+- "31 spreadsheet rows to zero"
+- "p95 held at 180ms"
+- "$200K monthly risk retired"
+- "Time-to-deploy from 4 hours to 12 minutes"
+
+The number should appear in the first 30 seconds and be the thing they repeat to *their* boss.
+
+## Artifact
+
+**`delivery.md`** - append under `## Exec narrative - <date>`:
+- The four narrative lengths (30s, 2min, 10min, 60min)
+- The SCQA frame
+- The hard-question sheet
+- The one number
+
+**`context.md`** - note: exec narrative prepared, presentation date, what must be updated before delivery.
+
+## Checkpoint
+
+Dry-run the 2-minute version with the FDE. Confirm: the one number lands in the first 30 seconds, the SCQA frame answers "why now," and the hardest question has a prepared answer. If the FDE can't deliver the 30-second version from memory, simplify.
+
+## Principles
+
+- Conclusion first, evidence second. The exec decides in the first 30 seconds.
+- Value in their units. Never present work; present outcomes.
+- One number per narrative. The room remembers one thing - make it the right thing.
+- Pre-wire every hostile question. Surprise in an exec meeting is a trust withdrawal.
+- Write all four lengths. The FDE will need them at different moments.

package/skills/fde/references/fintech.md

@@ -0,0 +1,48 @@
+# fintech overlay - money moves, failures are silent
+
+**Activate when you hear:** payments, transfers, settlements, reconciliation · PCI-DSS, PSD2, SOX, open banking, SWIFT · banking, lending, insurance, trading, crypto · "we handle money" in any form. Loads **alongside** the active phase, never instead of it.
+
+**Read first:** `trust-profile.md` always - data classification and AI policy before any action. `terrain.md` only when reviewing transaction/cardholder code.
+
+Financial systems carry a failure class others don't: **silent money loss.** A bug that processes a payment twice or drops a transaction is regulatory breach + customer harm + potential criminal liability, not a defect ticket.
+
+## The first conversation
+
+> "Does this system store, process, or transmit cardholder data? What's the current PCI-DSS compliance level?"
+
+Cardholder data = PAN, CVV, PIN, expiry. PAN never stored post-authorisation without explicit business case + encryption + masking (last 4 only). **Full PANs in logs, analytics events, or error messages is the first finding and outranks everything else.** Tag all cardholder scope in `trust-profile.md` under `<private>`.
+
+## Idempotency - the most common silent failure
+
+Same operation twice must equal once. Retries, network failures, double-clicks all duplicate requests; without idempotency that's double charges and phantom credits. On any code that creates transactions, verify:
+- An idempotency key on every write operation
+- Key checked **before** processing, not after
+- Retries reuse the same key, never a new one
+
+Missing from a payment flow → flag before production. "We'll add it later" has caused real customer harm in every fintech that said it.
+
+## Transaction integrity
+
+Atomic or nothing. A transfer that debits A and fails before crediting B is a financial error that may require regulatory reporting, not a technical error. Verify: DB-level transactions wrap the operations · compensating transactions exist · **the reconciliation path can catch a discrepancy at midnight.**
+
+## Fraud and reporting - surface early
+
+> "What fraud signals does this system monitor, and what happens when a transaction is flagged?"
+
+Immaturity markers: no velocity checks, no geographic anomaly detection, a review queue nobody actions, a manual override bypassing all controls. The engagement needn't build fraud detection - it must know what exposure the gaps leave. Same for regulatory reporting (CTR/SAR thresholds): manual reporting that relies on memory is a compliance risk; verify changes don't break automated reporting.
+
+## AI in financial systems
+
+Regulators commonly require **explainability** for automated decisions (credit, fraud, account actions). Before any AI-driven decision ships: explainability requirement for this jurisdiction confirmed · right-to-explanation satisfiable · decisions logged with input features. Some institutions prohibit AI final decisions on regulated activities - check `trust-profile.md` first.
+
+## Writes
+
+`trust-profile.md` - cardholder scope, PCI level, AI policy, reporting obligations. `risks.md` - idempotency gaps, integrity issues, fraud-control gaps, compliance exposure.
+
+## Principles
+
+- Idempotency is not optional.
+- Full PANs in logs = immediate flag.
+- Atomic or nothing; partial transaction states are financial errors.
+- If midnight reconciliation can't catch it, there is no financial integrity.
+- AI on regulated decisions needs explainability and an audit trail before build.

package/skills/fde/references/gov.md

@@ -0,0 +1,47 @@
+# government overlay - classification first, everything second
+
+**Activate when you hear:** federal/state agency, military, intelligence · FedRAMP, FISMA, NIST 800-53, CMMC, ITAR · ATO, SSP · CUI or classified data · contractor handling government data. Loads **alongside** the active phase.
+
+**Read first:** `trust-profile.md` always - classification level and clearance requirements before any action.
+
+Government runs on statutory authority, multi-year procurement, clearances, and classification regimes where one mishandled file is a federal offence. Slower by design; security stakes higher than any commercial engagement.
+
+## The first conversation
+
+> "What is the classification level of the data this system handles? Is there a System Security Plan I should read before we start?"
+
+- **Unclassified** - no special handling. **CUI** - NIST 800-171 handling. **Secret/Top Secret** - clearances, air-gap, need-to-know.
+- CUI or above constrains everything: which tools are allowed, where code is written, **whether AI assistance is permitted at all**, who can see what. Tag in `trust-profile.md` under `<private>` immediately. If the SSP doesn't exist, that's the first finding - a system without a security plan can't get an ATO.
+
+## ATO - the constraint nobody warns about
+
+> "Is this system operating under an ATO, or does this work require a new one?"
+
+A new ATO = months to years (Security Assessment Report, POA&M, Continuous Monitoring) - the delivery timeline just changed; plan around it in week one. Existing ATO: new external connections, auth changes, new data stores, or boundary changes can trigger re-assessment.
+
+## FedRAMP and sovereignty
+
+Cloud services holding federal data must be FedRAMP-authorised **at the right level** (Moderate ≠ High) - verify at fedramp.gov/marketplace. **This includes AI services: most commercial AI APIs are not FedRAMP-authorised - possibly including the assistant in use. Check the policy before processing any federal data.** Residency: data, backups, DR replicas, and third-party routes stay inside the required boundary.
+
+## Controls and clearance
+
+NIST 800-53 baseline by impact level (CUI+ → Moderate, 325+ controls). The engagement doesn't implement them all - it knows which controls its changes touch. Common in dev work: AC-2 (account management), AU-2 (audit events), CM-7 (least functionality), SI-10 (input validation).
+
+> "Does this work require a security clearance, at what level?"
+
+Required and not held → adjust scope to the unclassified components; be explicit about the boundary.
+
+## Procurement
+
+New tools or vendors may need months of procurement. Contracting officers (CO/COR) approve scope changes - not the program manager. Identify tool additions early.
+
+## Writes
+
+`trust-profile.md` - classification, ATO status, AI policy, clearance, FedRAMP constraints. `risks.md` - ATO gaps, FedRAMP violations, residency risks, control gaps.
+
+## Principles
+
+- Classification level determines tools, process, and people. Ask first.
+- ATO timelines are delivery timelines. Week one, not week ten.
+- FedRAMP is a gate, not a formality - for AI tools too.
+- No SSP = first finding.

package/skills/fde/references/handoff-engineering.md

@@ -0,0 +1,139 @@
+# handoff-engineering - 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?"
+
+**Read first:** `delivery.md`, `terrain.md`, `reality.md`, `decisions.md`, `context.md`, `stakeholders.md`. The handoff is built from the full engagement record. Load `trust-profile.md` for operational boundaries.
+
+The mark of a great FDE engagement is that the team can operate without you. A handoff that requires a callback in six weeks means the engagement didn't end - it paused. Handoff engineering is deliberate: it's designed, tested, and verified before the last day.
+
+## Method (you do this work)
+
+**1. The handoff inventory.** Everything the team needs to operate, categorised:
+
+| Category | What to hand off | Test: can they do it alone? |
+|----------|-----------------|---------------------------|
+| **Code knowledge** | Architecture decisions (`decisions.md`), why the code is shaped the way it is | Team member can explain the three most important design decisions |
+| **Operational** | Deploy, rollback, incident response, monitoring | Team member runs the deploy and rollback procedure independently |
+| **Tribal** | The things only you know - the workaround, the contact, the context | Written in `handoff.md` and reviewed with the person who'll carry it |
+| **Political** | Stakeholder dynamics, approval chains, who to call when | Documented in `stakeholders.md` with signal history |
+| **Data/AI** | Model versions, retraining triggers, drift monitoring, fallback paths | Owner named for each AI component; kill switch documented |
+
+**2. The 2am document.** Written for the person woken up on a Saturday night with zero context:
+
+```markdown
+# Operations runbook - <system name>
+
+## The 3 things that will break (and the fix for each)
+
+### 1. <most likely failure>
+Symptom: <what they'll see>
+Cause: <most likely why>
+Fix: <exact steps, copy-pasteable commands>
+Who to call if this doesn't fix it: <name, contact>
+
+### 2. <second most likely failure>
+...
+
+### 3. <third most likely failure>
+...
+
+## Deploy
+Command: <exact command>
+Time: <how long it takes>
+Verify: <how to confirm it worked>
+Rollback: <exact command and expected time>
+
+## Alerts
+| Alert | Means | Do this |
+|-------|-------|---------|
+| <alert name> | <plain English> | <action or link to detailed runbook> |
+
+## Contacts
+| Who | When to call | How |
+|-----|-------------|-----|
+| <name> | <scenario> | <phone/slack/email> |
+```
+
+**3. The knowledge transfer sessions.** Not a document dump - three structured sessions:
+
+| Session | Focus | Attendees | Duration | Output |
+|---------|-------|-----------|----------|--------|
+| **Architecture walkthrough** | Why, not what. The decisions, the trade-offs, the things that almost went wrong. | Full team | 60–90 min | Recording + Q&A log |
+| **Operational drill** | Deploy, rollback, incident response. They do it, you watch. | On-call team | 60 min | Drill report with confidence level |
+| **Edge-case handover** | The things that aren't in any document. The workarounds, the fragile spots, the "ask Sarah because she's the only one who knows." | Team lead + 1 | 30 min | Additions to `handoff.md` |
+
+**4. The confidence check.** After the knowledge transfer, score the team's readiness:
+
+| Area | Confidence (1–5) | Evidence |
+|------|------------------|----------|
+| Daily operations | | Can they deploy and rollback without help? |
+| Incident response | | Did they complete the drill within acceptable time? |
+| Architecture decisions | | Can they explain why the system is built this way? |
+| AI components (if any) | | Do they know how to monitor, retrain, and disable? |
+| Stakeholder management | | Do they know who to update and how? |
+
+**Average below 3.5 → the handoff is not complete.** Extend if possible; if not, document the gaps and name the risk.
+
+**5. The successor brief.** If a new FDE is taking over, write a brief that gets them operational in one hour:
+
+```markdown
+# Successor brief - <engagement name>
+
+## In 30 seconds
+<The real problem, the solution, where it stands>
+
+## Read these files first
+1. context.md - current state
+2. reality.md - the real problem (not the brief)
+3. decisions.md - what was decided and why
+4. stakeholders.md - who matters and their current signal
+5. risks.md - what's dangerous right now
+
+## The three things I wish I'd known on day one
+1. <thing>
+2. <thing>
+3. <thing>
+
+## The one thing that will bite you
+<specific warning>
+```
+
+**6. The clean exit.** Before the last day:
+
+- [ ] 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`)
+- [ ] Retrospective completed (see `close.md`)
+- [ ] Patterns extracted (see `pattern-extract.md`)
+
+## Artifact
+
+**`handoff.md`** - the 2am document + the operational inventory. The most important file the engagement produces after the code itself.
+
+**`context.md`** - final update: engagement status, handoff confidence, named gaps.
+
+## Checkpoint
+
+The acid test: "Can the team run this system for 30 days without calling you?" If yes → handoff complete. If no → name exactly what's missing, and either fix it or document the risk for the sponsor.
+
+## The permanent crutch anti-pattern
+
+Warning signs you've become a dependency instead of a deliverer:
+- The team defers decisions until you're in the room
+- "Can you just stay one more month?" (translation: the handoff hasn't started)
+- You're the only person who's run the deploy or the rollback
+- The sponsor introduces you as "part of the team" in month 4
+- The customer calls you within a week of "close"
+
+If you see 2+: accelerate the handoff immediately. The longer you stay past usefulness, the harder it is for the team to believe they can operate alone. A great FDE engagement ends with the team forgetting they needed you.
+
+## Principles
+
+- The goal of every engagement is to make yourself replaceable.
+- The 2am document is the real handoff - everything else supports it.
+- Knowledge transfer is three sessions, not a doc dump.
+- A confidence score below 3.5 means the handoff isn't done.
+- The successor brief gets the next FDE operational in one hour or it's too long.
+- Clean exit: no personal credentials left behind, ever.
+- If you're still indispensable after close, the engagement failed on the most important criterion.

package/skills/fde/references/healthcare.md

@@ -0,0 +1,45 @@
+# healthcare overlay - PHI ends licences
+
+**Activate when you hear:** patient records, EHR/EMR, clinical data · HIPAA, HITECH, HL7, FHIR · hospital, clinic, payer, pharma · "we handle patient data," even informally. Loads **alongside** the active phase.
+
+**Read first:** `trust-profile.md` always - PHI classification and AI policy before any action. `terrain.md` only when reviewing patient-data code.
+
+A PHI breach can end an operating licence; an audit-trail gap can invalidate a clinical trial; a model trained on patient data without consent can trigger federal investigation.
+
+## The first conversation
+
+> "Walk me through what patient data this system touches, stores, transmits - and who has access."
+
+PHI is broader than names: IPs, device identifiers, sub-state geography, and dates (other than year) can all qualify in context. When in doubt, treat as PHI. Tag everything in `trust-profile.md` under `<private>` - **PHI never enters AI context in plaintext: not prompts, not test fixtures, not dev logs.**
+
+## AI policy before a single line
+
+> "Does your organisation have a policy on AI tools accessing patient data? Is there a BAA covering the tools we're using?"
+
+Unclear answer = treat as prohibited until confirmed. Asking costs zero; guessing wrong is catastrophic.
+
+## Audit trails - non-negotiable
+
+Every action on PHI logged: who, what, when, from where (HIPAA Security Rule). On any PHI-touching code verify: identity+timestamp+action logged · logs immutable to application code · audit logs separate from app logs · retention ≥ 6 years. **No audit trail + a request to build a PHI feature → the audit trail gets built first.**
+
+## Break-glass
+
+Clinical systems need emergency override (a clinician must reach a record even when auth fails). Every break-glass event must **alert and trigger review**, not just log; verify it can't be silently disabled.
+
+## Minimisation, consent, encryption
+
+- Store the minimum PHI for the purpose; if de-identified data answers the question, use it. De-identification = HIPAA Safe Harbor's 18 identifiers - a legal definition, not a judgment call.
+- Data collected for one purpose can't serve another without consent - **including model training.** A model trained on records without explicit consent is immediate legal exposure.
+- Minimums: TLS 1.2+ in transit (1.3 preferred), AES-256 at rest, keys managed separately. Check `trust-profile.md` for stricter local rules.
+
+## Writes
+
+`trust-profile.md` - PHI scope, AI policy, consent coverage, BAA status. `risks.md` - compliance gaps with severity and remediation path.
+
+## Principles
+
+- PHI never enters AI context in plaintext.
+- Audit trails before features.
+- Unclear AI policy = prohibited until confirmed.
+- De-identification is a legal definition (18 identifiers).
+- Break-glass must alert, not just log.

package/skills/fde/references/incremental-build.md

@@ -0,0 +1,91 @@
+# incremental-build - 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)
+  → Write characterisation tests for what's there (if legacy)
+    → Implement the minimal working path
+      → Verify with evidence (tests + typecheck + smallest proving run)
+        → Cleanup pass (dedupe, simplify - behaviour unchanged)
+          → Self-review against acceptance criteria
+            → Commit with descriptive message
+              → Update decisions.md + delivery.md
+```
+
+**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 `scope-defense.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.