fdeops 3.5.0

package/skills/fde/references/audit.md

@@ -0,0 +1,61 @@
+# audit - taking over mid-engagement
+
+**Enter when:** picking up someone else's work - previous consultant left, joining mid-project, half-done system.
+
+**Read first:** `context.md` if it exists - otherwise start cold. The point of this phase is to establish ground truth, not assume it.
+
+## Method - part 1: read everything that exists (you do this work)
+
+Before forming any opinion:
+
+1. **Inherit the paper.** Any previous `.fde/`, docs, README claims, ADRs, ticket history the FDE can export. Read it all - the previous FDE's decisions are evidence, not verdicts.
+2. **Run the discover scans** (see `discover.md` method part 1: churn, test gaps, "temporary" grep, AI components). On a takeover, add:
+```bash
+git log --format="%an" | sort | uniq -c | sort -rn | head   # who actually built this
+git log --since="60 days ago" --format="%ad %s" --date=short | head -20  # what was happening when they left
+```
+A repo where one departed author wrote 80% of commits = tribal knowledge walked out the door. Mark every module only they touched.
+3. **Test the claims.** For each "this works" in the inherited docs, find the evidence: a passing test, a prod metric, a recent successful run. No evidence → it goes in the "assumed" column. "It should work" ≠ "it works."
+
+## Method - part 2: the unload (you coach)
+
+Let the team unload - what actually works, what's theater, what's held together with duct tape. Don't interrupt; separate fact from story. Then one follow-up if needed:
+
+> "What's the one thing you'd be insane to touch blind?"
+
+That's the load-bearing wall. Also establish: the single highest risk right now (what stops the customer's business if it breaks today), and who holds knowledge that exists nowhere else.
+
+## Artifact
+
+**`audit.md`** - written for the FDE who picks this up at 2am:
+```markdown
+# Audit - <date>
+**Works (evidence):** <item - evidence>
+**Assumed, unverified:** <item - what claim, what's missing>
+**Load-bearing, do not touch blind:** <module - why - who knows it>
+**Highest risk right now:** <one line>
+**First 3 actions:** 1. … 2. … 3. …
+```
+
+**`terrain.md`** - the map as understood now. Honest beats complete: mark unknowns explicitly.
+
+**`reality.md`** - real problem vs stated brief, even if the delta is small.
+
+**`context.md`** - updated so anyone walking in is operational in five minutes.
+
+All four files. Every later phase reads from these - an audit that doesn't populate them leaves the next phase blind.
+
+## Checkpoint - route explicitly, never straight to build
+
+- Real problem still unclear → **discover**.
+- Problem clear, brief confirmed → **plan**.
+- Active crisis in the inherited system → **rescue** now.
+
+Build without a plan in an inherited system is the fastest path to the second incident.
+
+## Principles
+
+- Read everything that exists before forming any opinion.
+- "It should work" is not "it works." Verify.
+- The most dangerous systems are the ones everyone assumes someone else understands.
+- Don't build until `audit.md`, `terrain.md`, `reality.md` are written.

package/skills/fde/references/blast-radius.md

@@ -0,0 +1,91 @@
+# blast-radius - know what breaks before you touch it
+
+**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?"
+
+**Read first:** `terrain.md`, `decisions.md`, `trust-profile.md` (for sacred systems), `context.md`.
+
+On your own codebase, you know what breaks. On someone else's, you discover it in production. Blast-radius analysis is the discipline of mapping the damage before making the change - not after.
+
+## Method (you do this work)
+
+**1. Trace the dependency chain.** For the file/module/system you're about to change, answer:
+
+| Question | How to find it |
+|----------|---------------|
+| Who calls this? | `grep -rn "function_name\|module_name" --include="*.ts" --include="*.py" .` |
+| Who does this call? | Read the imports and external calls in the module |
+| What data flows through? | Trace inputs to outputs - especially user data and money |
+| What breaks if this returns differently? | Check every caller's assumptions about the return value |
+| What breaks if this is slow? | Timeouts, queues, user-facing latency |
+| What breaks if this is down? | Circuit breakers? Fallbacks? Or cascade failure? |
+
+**2. Classify the blast radius:**
+
+```
+CONTAINED  → Only the module you're changing is affected
+             Rollback: revert the PR
+             Example: changing a utility function with no external callers
+
+ADJACENT   → 2–5 callers or one downstream system affected
+             Rollback: revert the PR + verify downstream
+             Example: changing an API response format used by the frontend
+
+SYSTEMIC   → Multiple systems, shared infrastructure, or data integrity
+             Rollback: may require data migration or coordinated rollback
+             Example: changing the auth token format, modifying a shared database schema
+
+IRREVERSIBLE → Cannot be rolled back without data loss or manual intervention
+               Example: data migration, dropping a column, changing encryption keys
+```
+
+**3. The blast-radius declaration.** Before writing any code, state it explicitly in `decisions.md`:
+
+```markdown
+## Blast radius: <change name>
+Classification: ADJACENT
+Affected: payment-service, billing-dashboard, reconciliation-job
+Data impact: none (read-only change to response format)
+Rollback: revert PR; frontend falls back to previous format handler
+Monitoring: error rate on /api/payments endpoint, billing dashboard load time
+Time to detect: <5 minutes via error rate alert
+```
+
+**4. Match the change to the blast radius:**
+
+| Blast radius | Required before merge |
+|-------------|----------------------|
+| CONTAINED | Unit tests + self-review |
+| ADJACENT | Unit + integration tests + team review + monitoring plan |
+| SYSTEMIC | Full test suite + team review + staged rollout + incident playbook |
+| IRREVERSIBLE | All of the above + sponsor approval + tested rollback of the rollback + go/no-go checkpoint |
+
+**5. The invisible integration.** The most dangerous blast radius is the one you can't see in the code:
+
+- A webhook endpoint that an external system calls - not in your repo's imports
+- A cron job that reads the table you're modifying - runs at midnight, fails silently
+- A reporting pipeline that depends on the exact column format
+- An monitoring alert that triggers on a metric your change affects
+
+**Ask the team:** "Is anything outside this repo reading from or writing to <the thing you're changing>?" The answer is almost always "yes, and here's one we forgot about."
+
+**6. The 2am test.** For any SYSTEMIC or IRREVERSIBLE change, ask: "If this fails at 2am on Saturday, who gets woken up, what do they see, and what can they do?" If the answer is "they see nothing until Monday" - the monitoring plan needs work before the change ships.
+
+## Artifact
+
+**`decisions.md`** - the blast-radius declaration, filed before the change starts. Updated if the blast radius grew during implementation.
+
+**`risks.md`** - new risks discovered during the trace (the invisible integrations, the midnight cron job).
+
+**`terrain.md`** - update if the dependency trace revealed connections the map didn't know about.
+
+## Checkpoint
+
+Before merge: blast radius declared and still accurate, monitoring in place for the affected scope, rollback tested (not just planned). If the blast radius grew during implementation: re-classify, update the declaration, adjust the review/rollout requirements.
+
+## Principles
+
+- Declare the blast radius before writing code, not after.
+- The invisible integration is always there. Ask the team.
+- Match the process to the blast radius - contained gets speed, systemic gets ceremony.
+- "We can always revert" is not a rollback plan. Test the rollback.
+- If the 2am failure is invisible until Monday, the monitoring isn't ready.

package/skills/fde/references/build.md

@@ -0,0 +1,98 @@
+# build - safe implementation on someone else's codebase
+
+**Enter when:** an agreed slice is ready to implement - feature, fix, integration, legacy change. Includes the review gate before merge.
+
+**Read first:** `context.md`, `terrain.md`, `decisions.md`. Load `trust-profile.md` when touching regulated areas. No map or no plan → route to discover/plan first; say it plainly: "We're not ready to touch code until we know what's connected to this module."
+
+## The loop (you do this work, in this order)
+
+1. **Confirm scope in writing.** The task exists in `decisions.md` with acceptance criteria. Not there → plan first or name the scope creep.
+2. **Declare blast radius.** Read the full dependency chain of what you're about to change. State: which files, which users, which systems. The change that breaks something always looked small.
+3. **Confirm the rollback path exists** before writing a line. "We can always revert" is not a rollback path.
+4. **Legacy code: characterisation tests first.** Tests for what the code *actually does right now* - including the parts that seem wrong; those behaviours are the contract the system depends on. Then wrap with Strangler Fig: new interface around old code, deprecate gradually, never rewrite in place.
+5. **Search before creating.** Read the existing code in the area; don't add parallel helpers where a service exists. Integrating an SDK/vendor API → read real source (local `reference/repos/...` or official repo) before guessing names; record the files used in `decisions.md`. If an API looks invented, stop and search source.
+6. **Build the minimal working path.** Thin vertical slice the customer can see. No opportunistic refactors. Every changed line traces to the task.
+7. **Verify with evidence.** Run tests/typechecks/smallest proving script. State what ran and what didn't. "Seems right" is never evidence.
+8. **Cleanup pass after it works.** Dedupe repeated mechanics into the smallest service module; behavior unchanged; re-run the same tests. If you wrote 200 lines and 50 would do, rewrite before review.
+9. **Review gate (before merge):** two stages, in order - (a) **scope**: does the diff match what was agreed in `decisions.md`, nothing more? (b) **safety**: blast radius honest, tests meaningful, rollback real, secrets absent. Fix real findings, re-verify, repeat until clean or blocked on a human decision.
+10. **Log and deliver.** Update the artifacts (below). Visible progress beats invisible perfection - every 2–3 tasks something shown to a stakeholder.
+
+**Touching existing code - classify before changing:**
+- **Fix now:** actively failing or blocking.
+- **Fix when touched:** will bite when surrounding code changes - fix as part of this change.
+- **Document and leave:** ugly but uninvolved. The hardest discipline. Opportunistic refactors create diffs nobody asked for and regressions nobody expected.
+
+**AI components:** build the fallback path *before* the AI path (model slow? garbage? down?). Add observability before deploy: log inputs, outputs, confidence - hallucinations don't throw exceptions. Confirm the data processing agreement covers customer data before it goes to an external model; in regulated environments this is a blocker, not a detail.
+
+**Regulated environments:** check the AI code policy in `trust-profile.md` first. Some modules require human review of AI-generated code or prohibit it. Find out before building, not after showing the code.
+
+## Mid-build scope requests
+
+"Also can you add…" → "That's worth looking at - let me place it." Current phase, future phase, or separate engagement? If it's outside `success.md`, name it: "Outside what we agreed; future phase or rescope conversation." Absorbed scope sets the precedent that the boundary doesn't exist - and in commercial engagements it silently moves billing and liability. Surface it to whoever owns the commercials.
+
+## Method - integration design (connecting systems)
+
+FDEs spend 40%+ of build time on integrations. Connecting system A to system B is where projects die quietly - wrong assumptions about APIs, missing auth, schema mismatches, rate limits.
+
+**The integration checklist (before writing code):**
+
+1. **Contract first.** Define what crosses the boundary: request shape, response shape, error shape. Write it down before calling anything. An undocumented contract changes without warning.
+2. **Auth model.** OAuth2, API key, mTLS, SAML? Who provisions the credential? Who rotates it? What's the expiry? One expired token at 2am = production down.
+3. **Rate limits and quotas.** Every external API has them, most aren't documented. Test with a burst early - don't discover the 429 on launch day.
+4. **Error taxonomy.** Retryable (timeout, 503) vs. fatal (401, 422). Build retry with exponential backoff for the first, circuit-breaker for the second.
+5. **Data transformation.** Their schema ≠ your schema. Map fields explicitly. Null handling rules. Timezone assumptions. Currency/locale. One unmapped field = silent data corruption.
+6. **Idempotency.** Can you safely retry? If not, you need deduplication. Double-charges, double-posts, double-notifications - all integration bugs.
+7. **Observability at the boundary.** Log every outbound call: request (redacted), response code, latency. The integration is the first thing to blame and the last thing instrumented.
+
+**The integration contract template (write to `decisions.md`):**
+```
+Integration: [System A] → [System B]
+Direction: push / pull / bidirectional
+Auth: [method] - provisioned by [who] - expires [when]
+Rate limit: [n] req/[period]
+Retry: [strategy]
+Data mapping: [field map or link to schema]
+Failure mode: [what happens when B is down]
+Owner: [who gets paged]
+```
+
+## Method - team amplification (making their engineers better)
+
+The FDE's job is to make themselves replaceable. Not at handoff - every day. A client team that can only ship when the FDE is present is a dependency, not a success.
+
+**Daily practices:**
+- **Pair, don't take over.** When a client engineer is stuck, pair for 30 minutes rather than solving it alone in 10. The 10-minute fix creates dependency; the 30-minute pair creates capability.
+- **Review their PRs with teaching intent.** Not "fix this" - "here's why this approach creates risk, and here's the pattern I'd use instead." Link to their own codebase for examples, not external docs.
+- **Make decisions visible.** When you make an architecture choice, write a 3-line rationale in `decisions.md`. The team sees your reasoning, not just your output.
+- **Name patterns, not just fixes.** "This is a circuit breaker pattern - here's when to use it again" converts one fix into a reusable skill.
+
+**Weekly practices:**
+- **One 30-min knowledge session per week.** Not a lecture - pick the hardest thing you built this week, walk through the thinking with the team. Answer: "why this approach and not the obvious one?"
+- **Track the team's solo wins.** When a client engineer ships without FDE help, note it. This is the metric that proves the engagement is working.
+
+**The independence signal:** When the team stops asking "how should we do X?" and starts asking "we're thinking X because Y - does that sound right?" - the engagement is succeeding.
+
+## Stop signals - reassess immediately
+
+- "I'll add tests after this works" - the regression is already in.
+- "Small change, no need to declare blast radius" - famous last words.
+- "I'll refactor this while I'm here" - unasked-for risk in an unrelated change.
+- **Three fixes in and still broken - the diagnosis is wrong.** No fourth fix: state your current model of the problem, name the evidence that would disprove it, test that first (see `debug.md`).
+
+## Artifact (logged as you go, not after)
+
+- **`decisions.md`** - each significant choice: what, alternatives considered, why this one. For non-trivial architecture decisions, present three options to the FDE (safe / pragmatic / aggressive) with costs and a recommendation - three options is a real decision; one option is a request for trust. Integration contracts go here too.
+- **`risks.md`** - new risks discovered while building.
+- **`delivery.md`** - what shipped, in business terms (time saved, failures prevented), and how to roll back. This is the value log the dashboard and close read.
+
+## Checkpoint
+
+Before merge: the two-stage review (scope, then safety) has run clean, verification evidence is stated, and the slice is demonstrable. If `trust-profile.md` requires human sign-off on AI-generated code, that sign-off exists.
+
+## Principles
+
+- Characterisation tests before modification. Every time.
+- Blast radius declared before every change; rollback confirmed before every deploy.
+- Scope creep is a decision, not a request. Name it.
+- Build the fallback before the AI feature.
+- Small diffs, objective verification, no thousand-line hope PRs.

package/skills/fde/references/business-case.md

@@ -0,0 +1,78 @@
+# business-case - the economics that get the sponsor to say yes
+
+**Enter when:** the sponsor needs justification for the next phase, the FDE needs to defend budget or timeline, a feature decision needs cost/benefit evidence, or sketch produced a direction that needs funding.
+
+**Read first:** `reality.md`, `success.md`, `delivery.md`, `context.md`. Load `business-case.md` from sketch if it exists - extend it, don't restart.
+
+Technical FDEs lose engagements by shipping good code without business justification. The sponsor's boss doesn't ask "is the code clean?" - they ask "what did we get for the money?" A business case translates technical work into the language that keeps the engagement alive.
+
+## Method (you do this work)
+
+**1. Name the cost of doing nothing.** This is the anchor. Every business case starts not with what you'll build, but with what it costs them to leave the problem unsolved:
+
+| Cost type | How to find it | Example |
+|-----------|---------------|---------|
+| **Direct cost** | Ask: "What does this problem cost per month in money?" | Manual reconciliation: 3 people × 8h/week × loaded cost = $X/month |
+| **Opportunity cost** | Ask: "What can't you do because of this problem?" | Can't onboard enterprise clients because the API can't handle their volume |
+| **Risk cost** | Ask: "What happens if this breaks at the worst time?" | A payment processing outage during Black Friday = $X/hour in lost sales |
+| **Velocity cost** | Measure: deployment frequency, lead time, change failure rate | Team ships once/month instead of once/week; each delay = N features not reaching customers |
+
+**2. Build the driver model.** Not a spreadsheet - a logic chain the sponsor can trace:
+
+```
+Investment: <hours × rate, or fixed cost>
+  → Delivers: <specific outcome from success.md>
+    → Saves: <cost-of-nothing × probability of success>
+      → Net: savings - investment over <time horizon>
+```
+
+Keep the drivers explicit. "We estimate $200K savings" means nothing. "3 people × 8h/week × $75/h × 52 weeks = $93.6K/year, minus $40K build cost = $53.6K net year one" is defensible.
+
+**3. Sensitivity check - name the two drivers that swing the result:**
+
+Every business case has 1–2 variables where a small change flips the outcome. Name them explicitly:
+
+> "This case holds if the team actually reclaims 6+ hours/week per person. If it's only 3 hours, the payback extends from 5 months to 14 months. The validation: measure time-spent before and after pilot with 2 team members."
+
+The sponsor who sees you've identified where the case could break trusts the case more, not less.
+
+**4. Frame for the audience.** Different stakeholders need different lenses on the same case:
+
+| Audience | Lead with | Avoid |
+|----------|----------|-------|
+| **CFO / finance** | ROI, payback period, cash flow impact | Technical architecture, feature lists |
+| **CTO / engineering** | Technical debt retired, velocity improved, risk reduced | Revenue projections they can't verify |
+| **CEO / founder** | Strategic enablement, competitive edge, customer impact | Detailed calculations (give the summary, offer the detail) |
+| **Product** | User impact, adoption metrics, feature velocity | Cost structures that aren't their domain |
+
+**5. The one-page format.** The business case fits one page or it isn't understood:
+
+```markdown
+## Business case: <initiative name>
+
+**The problem costs:** <one line, quantified>
+**The investment:** <hours and cost>
+**The return:** <quantified, with time horizon>
+**Payback:** <months>
+**Sensitivity:** <the 1-2 drivers that swing it, with thresholds>
+**Risks:** <what must be true for this to hold>
+**Recommendation:** <proceed / proceed-with-conditions / defer>
+```
+
+## Artifact
+
+**`business-case.md`** - the one-page case. Lives alongside `success.md` and `reality.md` as a first-class engagement artifact. Referenced by plan, status, and close.
+
+**`decisions.md`** - log the sponsor's response: approved, modified, deferred. With the date.
+
+## Checkpoint
+
+Walk the FDE through: the cost of doing nothing (anchor), the investment, the return, and the one sensitivity that matters most. If the FDE says "the sponsor won't buy the ROI number" - ask what number they would believe and work backwards from there.
+
+## Principles
+
+- The cost of doing nothing is always the opening move. Anchor before proposing.
+- Driver models with visible arithmetic beat magic spreadsheets.
+- Name the sensitivity. The case that admits its weakness earns more trust.
+- One page. If it doesn't fit, you don't understand it yet.
+- A business case the FDE can't explain in 60 seconds won't survive the sponsor's boss.

package/skills/fde/references/close.md

@@ -0,0 +1,43 @@
+# close - handoff and pattern extraction
+
+**Enter when:** the engagement is ending - the customer team must run this without the FDE.
+
+**Read first:** `context.md`, `reality.md`, `success.md`, `delivery.md`, `decisions.md`. The only phase that needs the full picture. Load `terrain.md` only if the handoff needs codebase-specific guidance.
+
+The engagement doesn't end at ship. It ends when the customer can maintain what was built without calling.
+
+## Method (you do this work, with the FDE's answers)
+
+**0. The opening question:** "What will bite them when you're gone?" Their answer shapes everything written below.
+
+**1. The retrospective.** Work through, blame-free and specific:
+- Did the real problem match the brief? (Compare `brief.md` vs `reality.md` - you have the receipts.)
+- Which trust moments mattered?
+- What did the codebase teach that `terrain.md` didn't know at the start?
+- Which risk almost became real?
+- AI components: did they behave in production? What failure modes did the prototype hide? Is the team equipped to maintain them?
+
+**2. The pattern.** Anything that happened here and will happen again - a compliance approach, a migration pattern, a stakeholder dynamic - gets encoded for reuse. **If you do it twice, encode it.**
+
+**3. The handoff.** Operational knowledge for the person woken at 2am, not technical documentation: the 3 things that will break and the fix for each · who holds the tribal knowledge · what each alert means · deploy and rollback in plain language. AI components additionally: model version, what normal output looks like (so drift is recognisable), fallback behaviour, who owns retraining, **how to disable the AI path without taking down the feature** - without this the team turns it off at the first misbehaviour and it stays off.
+
+**4. Transformation engagements - four extra answers in `handoff.md`:**
+- Who owns AI governance after the FDE leaves? (Who can pull a model from production?)
+- The retraining trigger, exactly: "precision < 0.82 on validation for 3 consecutive weeks → <owner> retrains." A number, a condition, an owner - not "when performance drops."
+- The operating model at scale: who coordinates twenty use cases across five teams?
+- Decision authority for new use cases: intake, risk assessment, approver.
+
+## Artifact
+
+**`retrospectives/YYYY-MM-DD-<engagement>.md`** - one file per close (separate files make cross-engagement patterns scannable). **`patterns.md`** - reusable patterns extracted. **`handoff.md`** - the 2am document.
+
+## Checkpoint
+
+Direct assessment to the FDE: did the engagement achieve `success.md` · 2–3 lessons that matter · is the pattern worth encoding · is the handoff complete or where are the gaps. Honest - a gap named now is cheaper than a callback in six weeks.
+
+## Principles
+
+- Done = the customer operates without you.
+- The retrospective is an investment in the next engagement, not a post-mortem.
+- Encode what repeated. The same lesson learned twice is a process failure.
+- Write the handoff for 2am.

package/skills/fde/references/dashboard.md

@@ -0,0 +1,40 @@
+# dashboard - the portfolio view
+
+**Enter when:** the FDE runs several customers and asks "where am I across everything?"
+
+**Read per engagement:** `reality.md`, `brief.md`, `success.md`, `risks.md`, `decisions.md`, `delivery.md`, `stakeholders.md`. Never `terrain.md` (too large) or `trust-profile.md` (sensitive - stakeholder signals live in `stakeholders.md`).
+
+The visual artifact is rendered by code, not by you. `fde dashboard` reads every `.fde/` folder and writes a self-contained `fieldbook.html` - deterministically, offline, **at zero token cost**. Your job is the judgment the render can't do: which engagement gets tomorrow morning, and why.
+
+## Method (you do this work)
+
+0. **First move: `fde status`** - instant heuristic triage (trust-first ordering) across every engagement. Use it as the index; then deep-read only the folders that are red/amber or that the FDE asks about, and apply the full card method below.
+1. **Find the engagements:** `~/fde-engagements/*/.fde/` (primary) · workspace `./.fde/` if present · paths the FDE names. Read each folder **separately** - never merge two customers.
+2. **Per engagement, read the card the way a human would:**
+   - Name, phase, week
+   - Real problem (`reality.md`) vs original brief (`brief.md`)
+   - Definition of success
+   - Top active risk
+   - Last significant action + next step
+   - Value delivered so far
+   - **Trust signal** - the most important row: **green** (no adverse signals) / **amber** (a stakeholder gone quiet or routing around the FDE) / **red** (escalation or explicit concern). Technical progress on a red-trust engagement is wasted until trust is addressed.
+3. **Triage order:** red trust first, then overdue risks, then stalled delivery. Say which engagement gets tomorrow morning and why.
+4. **Refresh the visual:** run `fde dashboard` to (re)generate `fieldbook.html` (defaults to `~/fde-engagements/fieldbook.html`). It is a deterministic render of the `.fde/` markdown - never hand-write HTML, never paste a model-built page. The session-end hook also refreshes it automatically when an engagement moved, so it is current next time the FDE opens it.
+
+Sparse data: the render shows what exists and pads nothing. An empty field honestly shows what hasn't been captured.
+
+## Artifact
+
+**`fieldbook.html`** - generated by `fde dashboard`, never hand-maintained. One file, opens in a browser, works offline, `<private>` notes redacted. Portfolio grid on top (a card per client: trust, phase, next action, top risk); click a card to drill into that engagement's full memory below.
+
+## Checkpoint
+
+One paragraph to the FDE: the portfolio in red/amber/green, the single most urgent item, and what it costs to ignore it this week. Offer to open the fieldbook (`fde dashboard --open`).
+
+## Principles
+
+- The render is deterministic and free; the judgment is yours.
+- Read what's there; invent nothing.
+- Trust signal outranks technical progress.
+- One file, opens in a browser, works offline - and never leaks `<private>` notes.
+- Thin data is information, not a gap to fill.

package/skills/fde/references/debrief.md

@@ -0,0 +1,36 @@
+# debrief - capture the meeting before it evaporates
+
+**Enter when:** the FDE just left a meeting/call and dumps raw notes, a transcript, or "they said…". The highest-frequency moment in FDE life (3–5×/day). Capture within the hour - memory decays fast.
+
+**Read first:** `context.md`, `stakeholders.md` (to update signals against what's known).
+
+## Method (you do this work)
+
+Take the raw dump exactly as given. Extract into five buckets - **only what was actually said**; rule 4 applies with full force here (no invented names, no embellished quotes):
+
+1. **Decisions** - what was agreed, by whom, in their words where possible.
+2. **Action items** - owner + due date. Unowned actions get `owner: unknown - ask`.
+3. **Stakeholder signals** - tone shifts, hesitations, who went quiet, who pushed back, verbatim quotes that matter. Map each to green/amber/red movement *with the evidence*.
+4. **Risks** - new ones surfaced, old ones confirmed or retired.
+5. **Open questions** - what the FDE must chase before the next session.
+
+Ambiguity in the dump → ask **one** clarifying question, then write. Never stall the capture on completeness.
+
+## Artifact (this IS the memory - write immediately)
+
+- Decisions → `decisions.md` via `fde log decision "<text> (meeting: <who>, <date>)"` or direct append, dated and attributed.
+- Signal changes → `stakeholders.md`: update the signal column with evidence + date. A quote moves a signal; a vibe does not.
+- Risks → `risks.md`, dated.
+- Action items + open questions → `context.md` under "Next actions".
+- Sacred/sensitive things mentioned (data, systems, politics) → `trust-profile.md` if new.
+
+## Checkpoint
+
+Read back the 2–3 most consequential captures in one breath - "Logged: descope agreed with Dana; ops lead went amber (quote attached); CISO ticket now blocking" - so the FDE can correct on the spot. Then stop. No summary theatre.
+
+## Principles
+
+- Capture within the hour or lose the nuance forever.
+- The verbatim quote outranks the paraphrase. The hesitation outranks the quote.
+- Signals move on evidence, never on inference.
+- A meeting that produced no decisions and no actions - say so; that's a finding about the meeting.

package/skills/fde/references/debug.md

@@ -0,0 +1,55 @@
+# debug - systematic, never guessing
+
+**Enter when:** something is broken, can't be reproduced, or "shouldn't be happening" - and production is NOT down (that's `rescue.md`).
+
+**Read first:** `context.md`, `terrain.md`, `chaos-log.md` (if this happened before, the cause is probably the same). Nothing else - noise kills focus.
+
+Debugging on an engagement differs from debugging your own code: no full context, no history, high pressure to "just fix it." That pressure causes the second incident. The sequence below is the protection.
+
+## Method (you do this work - never skip a step)
+
+**1. Reproduce.** Get a consistent repro before looking at any code. Can't reproduce → instrument first (logging, narrowing) - not fixes. An unreproducible bug that gets "fixed" comes back.
+
+**2. Isolate to the smallest failing case.** Strip everything that isn't the failure. Payment flow bug → does one hard-coded test transaction fail? Smallest case = smallest context = smallest blast radius for the fix.
+
+**3. Ask "what changed?" before reading code.** Last 2 hours, 24 hours, last deploy - this one question solves most production bugs:
+```bash
+git log --since="48 hours ago" --format="%ad %an %s" --date=relative
+git log --stat -5 --format="%h %s"   # works on any history depth
+```
+Don't read the codebase like a book. Write a script that answers one specific question - one execution, one answer.
+
+**4. One hypothesis.** Not three. State it explicitly:
+> "Hypothesis: X. If right, changing Y fixes it. If wrong, the symptom persists."
+A hypothesis that can't be falsified isn't one.
+
+**5. Fix the root cause, not the symptom.** A 500 is a symptom; an NPE is a symptom; the cause is upstream. Patch the symptom and you're back in a week.
+
+**6. Verify the fix holds.** Repro case passes; tests covering the changed code + downstream callers green; no new errors in logs for N minutes. Define done *before* declaring it - "seems fixed" requires another cycle.
+
+## Talking to the customer mid-debug (you coach)
+
+They'll ask for status before there is one. The FDE gives: what's narrowed, what's ruled out, what's being tested next, and **a specific time** they'll hear back. Proactive update if past that time - never make them chase. Skip the phrases that add heat: "weird one," "never seen this," "might be…". Partial clarity beats raw uncertainty. Fixed without root cause → stabilise honestly, don't close the story until the why is explainable.
+
+## Artifact
+
+**`chaos-log.md`** - append, same day:
+```markdown
+## <date> - <symptom>
+**Root cause:** <not the symptom>
+**What changed to fix it:** <change>
+**Hypotheses tested:** <in order, results>
+**Recurrence risk:** <where this can happen again>
+```
+Update `terrain.md` if the investigation disproved something the map claimed.
+
+## Checkpoint
+
+Before closing: repro passes, root cause stated in one sentence, chaos log written. If the root cause is still unknown, the incident stays open - say so.
+
+## Principles
+
+- Reproduce before touching anything. Always.
+- "What changed?" is the first question, not the last.
+- One hypothesis at a time. Three fixes failed = wrong mental model - stop.
+- Fix upstream. Symptoms patched are incidents scheduled.

package/skills/fde/references/demo-prep.md

@@ -0,0 +1,31 @@
+# demo-prep - the demo is the heartbeat of the engagement
+
+**Enter when:** a demo, show-and-tell, or exec walkthrough is coming. FDE engagements live demo-to-demo; a flat demo costs more than a slipped task.
+
+**Read first:** `delivery.md` (what actually works), `stakeholders.md` (who's in the room, what they care about, current signals), `success.md` (the promise being demonstrated), `trust-profile.md` (what must never appear on screen).
+
+## Method (you do this work)
+
+1. **Pick the ONE outcome** the room cares about - from `stakeholders.md`, not from what was hardest to build. Engineers demo effort; the room buys outcomes.
+2. **Build the arc:** the problem in their words → before (the pain, ideally the workaround they recognize) → after, **live** → the one number → what's next. Five beats, ten minutes.
+3. **The one number.** Every demo needs a single memorable quantity ("31 spreadsheet rows to zero", "p95 held at 180ms"). Pull it from `delivery.md`; if no number exists, that's a gap to fix *before* the demo, not narrate around.
+4. **Live vs. canned, decided per beat.** Demo live only what has run clean **twice today**. Everything else: recording or screenshot. A live failure in front of a skeptical room undoes three weeks of trust.
+5. **The hard-question sheet.** Write the five toughest questions this room will ask (check `risks.md` and amber/red stakeholders for where they'll push) + one-line answers with evidence. Include the question you're afraid of.
+6. **The failure plan.** If the live path breaks: the pre-recorded fallback, and the one sentence that keeps the room ("let me show you the captured run while that resets").
+7. **Sacred-data sweep.** Nothing from `trust-profile.md` `<private>` on screen - real customer data, carrier rates, PHI, keys. Demo data is staged data.
+
+## Artifact
+
+`delivery.md` under `## Demo plan - <date>`: the arc, live/canned split, the one number, hard-question sheet, fallback. `context.md`: demo scheduled, prep state, what must run clean twice before it.
+
+## Checkpoint
+
+Dry-run the arc with the FDE once, timed. Confirm: the one number lands in the first three minutes; the riskiest beat has a fallback; the opening line is about *their* problem, not our work.
+
+## Principles
+
+- Demo the outcome, never the architecture.
+- One number per demo. Rooms remember numbers, not features.
+- Never demo live what hasn't run clean twice today.
+- Rough is honest in week one; rough is alarming in week four - match polish to engagement stage.
+- Sacred data stays off screen, every time, no exceptions.