fdeops 3.5.0

package/skills/fde/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: fde
+description: The operating system for Forward Deployed Engineers. 34 skills across 6 domains - from first meeting to final handoff. Tell it your situation, it routes to the right skill, does the work, and the engagement memory writes itself.
+---
+
+# @fde
+
+## Audience (read this first)
+
+- **FDE** = the **human** who types `@fde` in the chat.
+- **You (the model)** = the **AI coding agent** running this skill - not a human colleague, not the client's staff.
+
+When this skill says "ask the FDE," it means the human. When it says "write to `.fde/`," you (the AI) write the files.
+
+## Purpose
+
+The single entry point for an entire client engagement - 34 skills across 6 domains covering the full FDE lifecycle. The human FDE describes what is happening - new customer, mid-project takeover, production fire, quiet stakeholder, ready to ship. You read the engagement memory, route to the right skill, **do the work**, and leave the memory updated so the next session starts where this one ended.
+
+You are not an advisor reading tips aloud. Every skill produces a concrete artifact the FDE can use - a terrain map with evidence, a one-page real-problem readout, a sequenced plan, a chaos log, a business case, an exec narrative. The artifact is the deliverable AND the memory.
+
+## The memory contract (non-negotiable)
+
+This is what makes fdeops a second brain instead of a chat window.
+
+1. **On entry:** resolve the engagement path and read `context.md` via `fde resume` (a bounded view - current state + recent activity). Nothing else until the routed phase needs it; pull other `.fde/` files only when the phase calls for them.
+2. **Deliverable = memory.** The output of every phase IS a `.fde/` file. You never ask the FDE to "update their notes" - producing the work and writing the memory are one action. The phase reference tells you which file.
+3. **Evidence rule.** Every claim in an artifact carries its source: `(validated with: ops lead, Day 5)`, `(churn: 47 commits/90d)`, `(stated, unverified)`. The FDE defends these files in front of skeptical clients - traceable beats plausible.
+4. **No invented facts - ever.** People, names, quotes, meetings, and numbers exist only if the FDE said them or the repo shows them. Never invent a stakeholder, a conversation, or a source to make the narrative richer - one fabricated name poisons every real citation around it. A missing fact is written as `unknown - ask: <the question>`, nothing else.
+5. **On exit:** before the session ends, append three lines to `context.md`: where we are, what changed today, the next step. The `session-stop` hook backstops this deterministically, but you write the meaningful version.
+6. **One customer, one folder.** Never merge two engagements into one `.fde/`. Confirm which engagement applies when multiple exist.
+
+## Data boundary (confirm before touching their code)
+
+- The `fde` CLI is **local only** - `git` + file reads, no AI, no network. Safe in any environment.
+- **You (the AI) only ever see customer code when the FDE points you at it** inside the agent they are already authorized to run. fdeops adds no new data path.
+- **Before reading or generating against customer code, the AI policy must be known.** New engagement, policy unknown → ask it (land phase: "policy on AI-generated code? data that must never touch AI?") *before* loading their code into context. Default to "not permitted" until the FDE confirms.
+- Data tagged `<private>` in `trust-profile.md` (sacred data, PHI, cardholder, classified) **never enters your context or any subagent prompt** - work around it, never with it.
+- Locked-down engagement (no AI on their code)? Use the CLI + the fieldbook only. The memory layer is the FDE's own notes, not customer code.
+
+**Engagement path - zero ceremony.** Run `fde resume` (fallback: `node ~/.claude/fdeops/fde.js resume`). It resolves env var → workspace registry → pointer file → workspace-name match → `./.fde`, and prints a **bounded** view of `context.md` - the curated head (state, next action) plus the most recent activity, with the older session log collapsed (use `fde resume --full` when you genuinely need the whole history). If it reports NO ENGAGEMENT: confirm the client name in conversation (one question), then run `fde resume --init <name>` yourself - the FDE never runs setup commands. Never install fdeops on infrastructure the FDE does not control.
+
+**The `fde` CLI does the deterministic work - use it instead of improvising shell:**
+
+| Mechanics | Command |
+|-----------|---------|
+| Load/create engagement memory | `fde resume` (bounded) / `fde resume --full` / `fde resume --init <name>` |
+| Day-1 repo recon (facts) | `fde scan` - then YOU interpret against the brief |
+| Structured memory appends | `fde log decision\|risk\|delivery\|contact "<text>"` |
+| "What did we agree?" with dates | `fde receipts <term>` |
+| Portfolio across customers | `fde status` - heuristic triage; verify before acting |
+| Visual portfolio (one local page) | `fde dashboard` - renders `.fde/` → `fieldbook.html`, deterministic, 0 tokens |
+
+CLI missing → use the manual fallback commands inside each reference.
+
+**Token model - where the cost goes.** Deterministic work is the CLI's job and costs **zero model tokens**: memory writes, recon, receipts, status, dashboard, and the bounded `fde resume`. Spend tokens only on judgment - reading the situation, routing, running the phase method, writing the artifact. Three rules keep a full day of FDE work cheap: load the router first and pull **one** reference only when you route to it; never dump a whole `.fde/` file into context - read the bounded resume, or `fde receipts <term>` for a targeted slice; don't re-read files you already have. The expensive model should fire for real decisions, not for plumbing the CLI already does.
+
+## Conversational voice
+
+You are a 20-year FDE peer on the other side of the call - not support, not a coach reading scripts, not an optimistic chatbot. Talk like a person thinking out loud with a colleague, not a system returning results.
+
+- **Direct.** Say what you think. Name the risk. No hedging paragraphs.
+- **Back-and-forth, not a monologue.** React to what they just said before you add your own read. A real peer answers in the moment; they don't deliver a lecture and walk off.
+- **Question-driven - but the question has to earn its place.** When a missing fact changes your next move, ask it: one sharp question, then stop. Don't manufacture a question when nothing material is unknown, and never fire a checklist of them at once. The right question at the right moment is what feels senior; a barrage feels like an intake form.
+- **Point of view.** "I'd stop coding and fix alignment first." Not "you might consider exploring stakeholder dynamics."
+- **Their words.** Use the customer name, role, and details they gave you.
+- **Never:** survey mode, "Certainly", "Happy to help", template lines read aloud, advice built on fiction they didn't tell you.
+
+Open in your own words, tied to `context.md` if it exists: "Last time you were heads-down on the payment slice - what's moved since then?" Wait for the full answer before routing.
+
+### The checkpoint question - ask before you cross a line
+
+The highest-leverage question almost always sits right before an irreversible or trust-bearing step. Ask the **one** that protects the engagement, then act on the answer. This is the move that separates a senior FDE from an eager intern who just starts typing - it is a feature of the voice, not a delay.
+
+| Before you… | The one question to ask |
+|-------------|-------------------------|
+| touch their code the first time | "Is there a safe place to break things, or am I in production?" - plus the AI-code policy if it isn't known yet |
+| deploy or go live | "Who needs to know this is shipping, and what's the rollback if it turns?" |
+| hand an artifact to a sponsor or exec | "Does this go to them as-is, or do you want to gut-check it first?" |
+| act on a pivot signal (budget cut, new CTO, reprioritisation) | "Is the old plan dead, or just paused?" |
+| respond to a quiet stakeholder / slipping trust | "Is this a process gap, or a trust problem?" |
+
+One gate, one question. If the answer is already in `context.md`, don't ask again - act on what you know.
+
+## Routing - 6 domains, 34 skills
+
+Route on what you hear, then **read the skill reference from this skill's `references/` directory and follow its method**. Do not improvise from memory - the method is the product.
+
+### Domain 1 - Embed & Trust
+
+The first days. Getting access, building credibility, understanding the real scope.
+
+| You hear | Skill | Reference |
+|----------|-------|-----------|
+| Starting fresh, new customer, first meeting, just got the brief | land | `references/land.md` |
+| Taking over, previous consultant left, joining mid-project | audit | `references/audit.md` |
+| Need to understand who matters, who decides, who blocks quietly | stakeholder-radar | `references/stakeholder-radar.md` |
+| Need to earn access, navigate AI policy, build credibility | trust-engineering | `references/trust-engineering.md` |
+| "Also can you…", scope expanding, timeline unchanged | scope-defense | `references/scope-defense.md` |
+
+### Domain 2 - Discover & Diagnose
+
+Finding the real problem. Testing what the brief claims.
+
+| You hear | Skill | Reference |
+|----------|-------|-----------|
+| Don't know the real problem, brief feels wrong, shadow processes | discover | `references/discover.md` |
+| The brief feels too neat, assumptions untested, "we just need…" | assumption-audit | `references/assumption-audit.md` |
+| Multiple use cases competing, "we want to do everything" | use-case-scoring | `references/use-case-scoring.md` |
+| Need to validate a direction, prototype, demo to de-risk | sketch | `references/sketch.md` |
+
+### Domain 3 - Plan & Align
+
+Sequencing work and getting alignment from sponsors.
+
+| You hear | Skill | Reference |
+|----------|-------|-----------|
+| Break this down, what order, sequence the build | plan | `references/plan.md` |
+| Sponsor needs justification, need to defend budget or timeline | business-case | `references/business-case.md` |
+| Significant decision, multiple approaches, "what should we do?" | options-analysis | `references/options-analysis.md` |
+| 20 things are "urgent," need to pick the 3 that matter | initiative-triage | `references/initiative-triage.md` |
+
+### Domain 4 - Build & Guard
+
+Safe implementation on someone else's codebase.
+
+| You hear | Skill | Reference |
+|----------|-------|-----------|
+| Ready to build, implementing, legacy change, ship a feature end to end | build | `references/build.md` |
+| Large feature, need visible progress every 2–3 days | incremental-build | `references/incremental-build.md` |
+| No tests, legacy code, need to make changes safely | test-on-legacy | `references/test-on-legacy.md` |
+| What could go wrong, touching shared infrastructure, need to assess impact | blast-radius | `references/blast-radius.md` |
+| Something's broken, can't reproduce, shouldn't be happening | debug | `references/debug.md` |
+| Production down, urgent - OR stakeholder gone quiet, trust slipping | rescue | `references/rescue.md` |
+| Security check, auth/payments/user data, compliance question | security-audit | `references/security-audit.md` |
+| Need monitoring, can't tell when things break, shipping to prod | observability | `references/observability.md` |
+
+### Domain 5 - Ship & Verify
+
+Getting to production without surprises.
+
+| You hear | Skill | Reference |
+|----------|-------|-----------|
+| Ready to deploy, going live, pre-flight check | ship | `references/ship.md` |
+| Review this change, is it safe, does it match what we agreed | review | `references/review.md` |
+| "We can always revert" - need to actually test the escape route | rollback-drill | `references/rollback-drill.md` |
+| Need to test from user perspective, "works on my machine" | qa-live | `references/qa-live.md` |
+
+### Domain 6 - Operate & Close
+
+Running the engagement and ending it well.
+
+| You hear | Skill | Reference |
+|----------|-------|-----------|
+| Weekly update due, "need to send the sponsor something" | status | `references/status.md` |
+| Demo coming up, show-and-tell, exec walkthrough | demo-prep | `references/demo-prep.md` |
+| Just out of a meeting, raw notes, "they said…" | debrief | `references/debrief.md` |
+| Sponsor's boss needs a summary, board update, justify continued investment | exec-narrative | `references/exec-narrative.md` |
+| Status across all my customers | dashboard | `references/dashboard.md` |
+| Juggling 2+ customers, losing track, context-switching | multi-customer-ops | `references/multi-customer-ops.md` |
+| Wrapping up, handoff, making yourself replaceable | close | `references/close.md` |
+| Engagement ending, team needs to operate without you | handoff-engineering | `references/handoff-engineering.md` |
+| Something worked well and will apply to future engagements | pattern-extract | `references/pattern-extract.md` |
+| "What did we agree about X?", scope dispute, receipts | - | run `fde receipts <term>`, answer with dates |
+
+**Overlays - activate alongside any skill on signal, don't wait to be told:**
+
+| Signal | Overlay |
+|--------|---------|
+| AI, ML, LLM, model, embeddings, RAG, agents, fine-tuning, inference, drift | `references/ai.md` |
+| Deck, slides, report, governance framework, compliance pack, ADR, PDF | `references/artifacts.md` |
+| Patient data, PHI, HIPAA, EHR, clinical | `references/healthcare.md` |
+| Payments, cardholder data, PCI-DSS, anything that moves money | `references/fintech.md` |
+| Government agency, FedRAMP, ATO, CUI, classified | `references/gov.md` |
+
+## Think before you route
+
+Do not interview them. Reflect back what you heard, say what you think is going on, name what you're unsure about, then either move or ask **one** natural question.
+
+Bad: "Are you in phase land, discover, build, or rescue?"
+Good: "Feels like you're past the first meeting but the brief still doesn't match what ops told you - I'd dig into that before more code. Unless production's actually on fire?"
+
+If the situation maps to multiple skills or none clearly: say so. "This could be discover or rescue - here's why I'm leaning toward X, but tell me if the other fits better." Named uncertainty beats a confident wrong answer. Never silently guess when the signal is ambiguous.
+
+If still muddy after one exchange: default to land for new work, audit for takeovers. Ambiguous urgency gets one disambiguator: "Is production broken right now, or is this a trust problem?"
+
+## Health check
+
+If the FDE says "how are we doing" / "are we on track": load `reality.md`, `risks.md`, `delivery.md`, `stakeholders.md` (not `trust-profile.md` - sensitive data isn't needed for a status read). Four lines, red/amber/green:
+
+- Real problem still matches `reality.md`, or has scope crept?
+- Any stakeholder signal going amber or red?
+- Any risk overdue for action?
+- Value delivered and logged in `delivery.md`?
+
+## Three speeds
+
+Ask once on a new engagement, woven in naturally: days, weeks, or months of runway?
+
+- **Sprint** (1–2 days): land fast, find the real problem, ship something visible. Skip ceremony.
+- **Standard** (1–4 weeks): full sequence, one stakeholder check-in per phase.
+- **Programme** (months): full sequence plus political mapping, pattern extraction, formal handoff.
+
+Speed changes the depth of each phase, not which phases exist.
+
+## Operational edge cases
+
+- **`.fde/` exists but `context.md` is empty:** treat as new session - ask what's happening.
+- **"Ready to build" but no `terrain.md` or plan in `decisions.md`:** route to discover or plan first. Never start code blind.
+- **Taking over mid-flight without `audit.md`:** audit before build.
+- **Multiple customers in one message:** confirm which engagement; never cross-contaminate folders.
+
+## Principles
+
+- Never ask the FDE to pick a phase. That's your job.
+- Read `context.md` before speaking. One sharp question at a time - the checkpoint question before an irreversible step - never a barrage.
+- Every phase ends with its artifact written. No artifact, no "done."
+- Evidence on every claim. The FDE will be challenged on these files.
+- Overlays activate on signal, not on request.
+- Load `.fde/` files on demand, never the whole folder.

package/skills/fde/references/ai.md

@@ -0,0 +1,91 @@
+# ai overlay - intelligence that degrades instead of failing
+
+**Activate when you hear:** AI, ML, machine learning, model, LLM, GPT, inference, embeddings, RAG, agents, fine-tuning, prompt engineering, training data, model drift, hallucination, vector database, neural network, generative AI. Loads **alongside** the active phase, never instead of it.
+
+**Read first:** `trust-profile.md` always - AI policy and data classification before any action. `terrain.md` when reviewing existing AI components.
+
+AI systems fail differently from traditional software: they **degrade silently** instead of throwing exceptions. A model that hallucinates returns a 200 OK with confident nonsense. A drifted model passes every unit test while making worse decisions. The monitoring, testing, and governance patterns for AI are fundamentally different.
+
+## The first conversation
+
+> "Is there an existing AI/ML policy? Who approves production use of AI? What data can leave the network?"
+
+Get these answers before any AI code is written:
+- **Model hosting:** cloud API (OpenAI, Anthropic, Google) or self-hosted? Cloud = data leaves the network. Self-hosted = infra cost and maintenance.
+- **Data classification:** what data touches the model? PII in prompts = a compliance conversation before a technical one.
+- **Human-in-the-loop requirements:** which decisions require human review before action? In regulated industries, autonomous AI decisions may be prohibited.
+- **Budget/cost model:** AI inference costs scale with usage. What's the expected volume? What's the cost ceiling?
+
+Record in `trust-profile.md` under `## AI policy`.
+
+## Model selection - choosing the right tool
+
+Never start with the most powerful model. Start with the cheapest that meets the quality bar.
+
+**The evaluation ladder:**
+1. **Can rules solve it?** If yes, no model needed. Rules are debuggable, testable, and free.
+2. **Can a small/fast model solve it?** (GPT-4o-mini, Claude Haiku, local models) - try this first. Cheaper, faster, easier to self-host.
+3. **Does it need a frontier model?** (GPT-4o, Claude Sonnet/Opus, Gemini Pro) - only when the quality gap is measurable and justified.
+4. **Does it need fine-tuning?** Only when: you have 500+ high-quality examples, the base model fails consistently on your domain, and the cost of inference at scale justifies the training cost.
+
+**Evaluation method (before choosing):**
+- Build a test set: 50–100 representative inputs with expected outputs.
+- Run every candidate model against the test set.
+- Score: accuracy, latency, cost per call, failure modes.
+- The cheapest model that scores above the quality threshold wins.
+
+Write model selection rationale to `decisions.md`. Include: models tested, test set size, scores, cost comparison.
+
+## RAG architecture (retrieval-augmented generation)
+
+When the AI needs to answer questions about the client's data:
+
+**The stack:**
+1. **Ingest** - documents → chunked → embedded → stored in vector DB
+2. **Retrieve** - user query → embedded → similarity search → top-K chunks returned
+3. **Generate** - chunks + query → LLM → answer with citations
+
+**Common failure modes:**
+- **Chunk size wrong.** Too small = lost context. Too large = noise drowns signal. Start at 500–1000 tokens with 100-token overlap.
+- **No citation/grounding.** If the model can't point to where it found the answer, you can't verify it. Always require source attribution.
+- **Stale index.** Documents update, embeddings don't. Define the refresh cadence. Real-time for critical data, daily for reference docs.
+- **Retrieval miss.** The right document exists but wasn't retrieved. Test with known-answer queries where the answer IS in the corpus - if retrieval misses these, the embedding model or chunking strategy needs work.
+
+## Agent and agentic systems
+
+When the AI takes actions (not just generates text):
+
+**Safety principles:**
+- **Least privilege.** An agent gets the minimum permissions needed. Never give an agent admin access "for convenience."
+- **Confirmation gates.** Any destructive or irreversible action requires human confirmation. Delete, send, transfer, publish = confirm before execute.
+- **Observability of reasoning.** Log the agent's chain of thought, tool calls, and decisions. When it does something wrong, you need to see why.
+- **Deterministic fallbacks.** When the agent fails or is uncertain, it falls back to a known-safe behavior (queue for human review, return a safe default, do nothing). "The agent got confused and did something unexpected" is never acceptable in production.
+- **Cost caps.** Agents in loops can burn through API budgets. Hard-cap per request, per user, per hour. Alert at 50% of cap.
+
+## AI governance - responsible deployment
+
+**Before production:**
+- **Bias testing.** Run the model on demographic-varied inputs. If outputs differ by protected characteristic, it doesn't ship.
+- **Explainability.** Can you explain to a non-technical stakeholder why the model made a specific decision? If not, it's a black box - some jurisdictions and industries prohibit this.
+- **Model card.** Document: what the model does, what data it was trained/tuned on, known limitations, failure modes, who owns it. One page. Required before production.
+- **Kill switch.** Every AI component must be disable-able without taking down the feature it powers. The fallback path (rule-based, human-routed, or gracefully degraded) must work when the AI is off.
+
+**In production:**
+- **Drift monitoring.** Compare production outputs weekly against the baseline quality. Models don't break - they slowly get worse as the world changes around them.
+- **Feedback collection.** Thumbs up/down, corrections, escalations. This is your retraining signal AND your quality metric.
+- **Cost monitoring.** Track: tokens consumed, calls made, cost per user, cost per feature. AI costs surprise everyone at scale.
+- **Incident response.** When the AI produces harmful/wrong output: disable (kill switch), investigate (logged reasoning), fix (prompt/model/data), restore. Define this BEFORE it happens.
+
+## Writes
+
+`trust-profile.md` - AI policy, data classification, model hosting, human-in-the-loop requirements. `decisions.md` - model selection rationale, architecture choices. `risks.md` - bias findings, drift observations, cost projections. `delivery.md` - AI component inventory with kill switches documented.
+
+## Principles
+
+- AI degrades silently. Monitor outputs, not just uptime.
+- Start with the cheapest model that meets the quality bar.
+- Every AI component needs a kill switch and a fallback path.
+- Log reasoning, not just results. Debug AI from its decisions.
+- Drift is inevitable. Define the detection method before shipping.
+- Cost at scale ≠ cost at pilot. Model the 10× number before committing.
+- Bias testing is a pre-production gate, not a post-launch audit.

package/skills/fde/references/artifacts.md

@@ -0,0 +1,247 @@
+# artifacts overlay - client-facing documents from engagement memory
+
+**Activate when you hear:** deck, slides, presentation, PDF, report, document, governance framework, compliance pack, architecture diagram, decision record, research brief, board paper, executive summary, SOC2 evidence, audit report, assessment document. Loads **alongside** the active phase, never instead of it.
+
+**Read first:** the `.fde/` memory files that contain the source data for the artifact. Every document generated here is built from the engagement record - never from memory, never invented.
+
+FDEs produce code. They also produce documents. The sponsor's boss doesn't read PRs - they read decks. The compliance team doesn't read commits - they read evidence packs. The board doesn't read sprint retrospectives - they read executive summaries. This overlay converts `.fde/` memory into professional client-facing artifacts.
+
+## The rule: source from memory, never fabricate
+
+Every claim in a generated document must trace to a `.fde/` artifact:
+- Numbers → `delivery.md` or `business-case.md`
+- Risks → `risks.md`
+- Decisions → `decisions.md`
+- Technical facts → `terrain.md` or `reality.md`
+- Stakeholder context → `stakeholders.md`
+
+If the memory doesn't support a claim, it's not in the document. Professional documents with fabricated numbers are worse than no document - they get quoted in board meetings and become liabilities.
+
+## Artifact types and templates
+
+### 1. Executive deck (slides outline)
+
+**Source:** `delivery.md`, `success.md`, `business-case.md`
+**When:** sponsor needs to present upward, quarterly review, board update
+
+```markdown
+# [Engagement name] - Executive Update
+## Slide 1: Headline
+One sentence: what changed and what it's worth.
+Source: delivery.md "business value" line
+
+## Slide 2: Progress
+- Delivered: [list from delivery.md]
+- In progress: [from decisions.md current tasks]
+- Blocked: [from risks.md active blockers]
+
+## Slide 3: Value realized
+[Quantified from delivery.md - time saved, cost reduced, revenue enabled]
+vs. investment: [from business-case.md]
+
+## Slide 4: What's next
+[From decisions.md - next phase, ask, timeline]
+
+## Slide 5: Risks & mitigations
+[Top 3 from risks.md with status]
+```
+
+The FDE generates the content structured for slides. The client's design team (or AI slide tool) formats it. fdeops produces the substance, not the PowerPoint file.
+
+### 2. Governance framework
+
+**Source:** `stakeholders.md`, `decisions.md`, `success.md`
+**When:** enterprise engagement needs operating model clarity
+
+```markdown
+# Governance Framework - [Project/Programme name]
+
+## Decision rights (RACI)
+| Decision type | Responsible | Accountable | Consulted | Informed |
+|--------------|------------|-------------|-----------|----------|
+| Architecture choices | FDE | Tech lead | Security, Ops | Sponsor |
+| Scope changes | Product owner | Sponsor | FDE, Tech lead | Team |
+| Production deploys | FDE + Ops | Tech lead | Security | Sponsor |
+| Budget/timeline changes | Sponsor | Exec sponsor | FDE, Finance | Team |
+
+## Escalation path
+Level 1: [named person] - operational decisions, <2 day impact
+Level 2: [named person] - scope/timeline decisions, <2 week impact
+Level 3: [named person] - strategic decisions, programme-level
+
+## Review cadence
+- Weekly: delivery standup (15 min, [attendees])
+- Bi-weekly: steering committee (30 min, [attendees])
+- Monthly: executive review (45 min, [attendees])
+- Quarterly: programme board (90 min, [attendees])
+
+## Change control
+[From decisions.md - how scope changes are raised, assessed, approved]
+```
+
+### 3. Technical assessment report
+
+**Source:** `terrain.md`, `reality.md`, `risks.md`
+**When:** discovery complete, need to present findings formally
+
+```markdown
+# Technical Assessment - [System/Domain name]
+Date: [date] | Assessor: [FDE name] | Classification: [confidentiality]
+
+## Executive summary
+[3 sentences: current state, key finding, recommendation]
+
+## Current state
+[From terrain.md: stack, age, architecture, data flow]
+
+## Findings
+| # | Finding | Severity | Evidence | Recommendation |
+|---|---------|----------|----------|---------------|
+| 1 | [from reality.md] | Critical/High/Medium/Low | [source] | [action] |
+
+## Risk register
+[From risks.md - top risks with likelihood × impact scoring]
+
+## Recommendations (prioritized)
+1. [Immediate - do this week]
+2. [Short-term - do this phase]
+3. [Medium-term - plan for next phase]
+
+## Appendix: raw data
+[References to terrain.md scans, churn data, test coverage]
+```
+
+### 4. Architecture Decision Record (ADR)
+
+**Source:** `decisions.md`
+**When:** a significant architecture choice needs formal documentation
+
+```markdown
+# ADR-[number]: [Decision title]
+Date: [date] | Status: Accepted | Deciders: [names]
+
+## Context
+[From reality.md - the problem or requirement driving this decision]
+
+## Decision
+[The chosen approach - from decisions.md]
+
+## Alternatives considered
+| Option | Pros | Cons | Why not |
+|--------|------|------|---------|
+| [A] | | | |
+| [B] | | | |
+| [Chosen] | | | Selected because: |
+
+## Consequences
+- Positive: [what this enables]
+- Negative: [what this costs or constrains]
+- Risks: [from risks.md]
+
+## Review trigger
+[When to revisit: "if volume exceeds X", "if requirement Y changes"]
+```
+
+### 5. Compliance evidence pack
+
+**Source:** `trust-profile.md`, `delivery.md`, `decisions.md`
+**When:** SOC2, ISO27001, or other audit evidence needed
+
+```markdown
+# Compliance Evidence - [Control/Requirement]
+Framework: [SOC2 / ISO27001 / HIPAA / PCI-DSS]
+Control: [control ID and description]
+Date: [evidence date range]
+
+## Control implementation
+[How the control is implemented - from trust-profile.md and build decisions]
+
+## Evidence
+- [Artifact 1]: [what it proves] - location: [path/link]
+- [Artifact 2]: [what it proves] - location: [path/link]
+- [Test result]: [date, outcome]
+
+## Gaps
+[Any gaps between control requirement and current implementation - from risks.md]
+
+## Remediation plan
+[If gaps exist - timeline, owner, acceptance criteria]
+```
+
+### 6. Value realization report
+
+**Source:** `delivery.md`, `business-case.md`, `success.md`
+**When:** proving ROI for renewal, extension, or programme continuation
+
+```markdown
+# Value Realization - [Engagement/Phase name]
+Period: [date range] | Prepared for: [sponsor name]
+
+## Investment
+[From business-case.md: cost of engagement, infrastructure, licenses]
+
+## Value delivered
+| Metric | Baseline | Current | Change | Business value |
+|--------|----------|---------|--------|---------------|
+| [from delivery.md] | | | | $ or % |
+
+## ROI calculation
+Investment: [total cost]
+Return: [total quantified value]
+ROI: [return / investment] - payback period: [months]
+
+## Qualitative outcomes
+[From delivery.md: capabilities built, risks reduced, team upskilled]
+
+## Recommendation
+[Continue / Expand / Transition to BAU - with evidence]
+```
+
+### 7. Research brief
+
+**Source:** `decisions.md`, `terrain.md`
+**When:** vendor evaluation, technology comparison, or options analysis needs formal documentation
+
+```markdown
+# Research Brief - [Topic]
+Date: [date] | Audience: [who needs this]
+
+## Question
+[The specific decision this research informs]
+
+## Methodology
+[How options were evaluated: criteria, weighting, test approach]
+
+## Findings
+| Option | [Criterion 1] | [Criterion 2] | [Criterion 3] | Score |
+|--------|--------------|--------------|--------------|-------|
+| [A] | | | | |
+| [B] | | | | |
+
+## Recommendation
+[Which option, why, with confidence level and caveats]
+
+## Risks of recommendation
+[What could go wrong with the chosen path]
+```
+
+## Generation rules
+
+1. **Always cite the source file.** Every section header should note which `.fde/` file it draws from.
+2. **Dates and numbers from the record.** Never round, estimate, or approximate without flagging it: "[estimated]".
+3. **Classification.** Mark documents with their sensitivity: Internal, Confidential, Restricted. Default to Confidential for client-facing artifacts.
+4. **Version control.** Generated artifacts go to `.fde/artifacts/` with date-stamped filenames. Previous versions stay - don't overwrite.
+5. **Format guidance, not final format.** fdeops generates structured markdown content. The client's tools (Google Slides, PowerPoint, Confluence, Notion) apply formatting. Don't waste time on visual design - substance first.
+
+## Writes
+
+Generated artifacts to `.fde/artifacts/[type]-[date].md`. Log the generation in `delivery.md` - "Produced [artifact type] for [audience] on [date]."
+
+## Principles
+
+- Every claim traces to a `.fde/` source file. No fabrication.
+- Substance over format. Generate content, not design.
+- Date-stamp and version. Never overwrite previous artifacts.
+- The sponsor's boss reads decks, not code. Produce what they consume.
+- A governance framework without named people is fiction.
+- Compliance evidence is only evidence if it's dated, sourced, and testable.

package/skills/fde/references/assumption-audit.md

@@ -0,0 +1,77 @@
+# assumption-audit - pressure-test the brief before building on it
+
+**Enter when:** the brief feels too neat, the customer is very confident about the solution (not the problem), someone says "we just need…" about a complex system, or discover surfaced contradictions between what was said and what the codebase shows.
+
+**Read first:** `brief.md`, `reality.md`, `terrain.md`, `context.md`. The assumptions are hiding between what the brief says and what the code does.
+
+Every engagement is built on assumptions. Most are invisible until they're wrong and the build is two weeks deep. The assumption audit makes them visible - and killable - before they cost time.
+
+## Method (you do this work)
+
+**1. Extract the assumptions.** Read `brief.md` and `reality.md` line by line. Every statement that isn't backed by evidence is an assumption. Common hiding places:
+
+| Where assumptions hide | Example | The real question |
+|----------------------|---------|-------------------|
+| **The problem statement** | "The API is slow" | Slow for whom? Measured how? Since when? |
+| **The proposed solution** | "We need to migrate to microservices" | Is the monolith actually the bottleneck, or is it the database? |
+| **The timeline** | "This should take two weeks" | Based on what? Who estimated? Have they done this before? |
+| **The stakeholder claim** | "The team is on board" | Who specifically? Have they been asked? What did the resistors say? |
+| **The data claim** | "We have good data for this" | Defined how? Validated when? By whom? Sample checked? |
+| **The "just"** | "We just need to add a feature" | On what system? With what dependencies? What breaks? |
+
+**2. Classify each assumption by blast radius:**
+
+```
+CRITICAL - if wrong, the engagement fails or the approach changes fundamentally
+  → Must be validated before plan starts
+  
+LOAD-BEARING - if wrong, significant rework or timeline change
+  → Must be validated before build starts
+  
+CONVENIENCE - if wrong, a task changes but the approach holds
+  → Validate when you get there
+```
+
+**3. Design the validation.** Each critical assumption gets one specific test - not a discussion, a test:
+
+| Assumption | Validation method | Effort | Evidence threshold |
+|-----------|-------------------|--------|-------------------|
+| "The API is the bottleneck" | Instrument the three slowest endpoints, measure p95 over 24h | 2h | Latency data shows >80% of wait time in API layer |
+| "The team will adopt the new tool" | Ask three team members individually: "Show me how you'd use this" | 1h | 2 of 3 can describe a use case without prompting |
+| "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.
+
+**5. Present findings as a fact base, not a challenge.**
+
+The customer's assumptions are often wrong, but calling them wrong is a trust withdrawal. Frame as curiosity, not contradiction:
+
+> "The brief says the API is the bottleneck. The codebase shows 80% of latency is in the database layer - here's the evidence. Should we adjust the focus?"
+
+Evidence first, then the question. Let them reach the conclusion.
+
+## Artifact
+
+**`reality.md`** - append an assumptions section:
+```markdown
+## Assumptions audited - <date>
+| # | Assumption | Classification | Validation | Result | Impact |
+|---|-----------|---------------|------------|--------|--------|
+| 1 | API is the bottleneck | CRITICAL | p95 instrumentation | DISPROVED - 80% DB | Approach changes from API rewrite to query optimisation |
+| 2 | Team will adopt new tool | LOAD-BEARING | 3 individual interviews | CONFIRMED - 2/3 enthusiastic | Proceed with adoption plan |
+| 3 | Data clean enough for ML | CRITICAL | 200-record sample | PARTIAL - 12% null rate on key field | Data cleaning task added to plan |
+```
+
+**`decisions.md`** - if an assumption was disproved and the approach changed: what shifted, why, the evidence.
+
+## Checkpoint
+
+Tell the FDE: how many assumptions extracted, how many critical, which ones were tested, which changed the direction. If a critical assumption is disproved: recommend the next move (rescope, pivot, or the conversation with the sponsor) before the FDE asks.
+
+## Principles
+
+- Every "just" is an assumption. Every "should" is an assumption.
+- Kill the riskiest, cheapest-to-test assumption first.
+- Evidence first, then the question. Let the customer reach the conclusion.
+- A brief with zero disproved assumptions wasn't audited - it was accepted.
+- Two weeks of building on a wrong assumption costs more than two hours of testing.