fdeops 3.5.0

package/skills/fde/references/initiative-triage.md

@@ -0,0 +1,78 @@
+# initiative-triage - when 20 things are "urgent," pick the 3 that matter
+
+**Enter when:** a transformation engagement with a long list of initiatives, the customer's roadmap has more items than weeks, competing teams want different things, or the FDE needs to recommend what to do *first* across a complex programme.
+
+**Read first:** `reality.md`, `success.md`, `stakeholders.md`, `context.md`. Load `business-case.md` if individual initiative cases exist.
+
+Every enterprise engagement generates more work than any timeline can hold. Triage is the discipline of saying "not now" to real work with real sponsors - and making it stick. Without it, the FDE drowns in parallel efforts and ships nothing well.
+
+## Method (you do this work)
+
+**1. Collect the full list.** From the customer's roadmap, from discovery, from stakeholder requests, from `decisions.md` scope receipts. No filtering yet - everything goes on the board:
+
+```markdown
+| # | Initiative | Requested by | Stated priority | Current status |
+|---|-----------|-------------|----------------|----------------|
+| 1 | Payment API rewrite | CTO | P1 | Blocked on schema decision |
+| 2 | Customer dashboard | Product | P1 | Design phase |
+| 3 | SOC2 compliance | CISO | P0 | Not started |
+| ... | ... | ... | ... | ... |
+```
+
+Notice: every stakeholder's initiative is P0 or P1. That's the problem this skill solves.
+
+**2. Apply the triage matrix.** Each initiative scores on three axes:
+
+| Axis | Question | Scale |
+|------|----------|-------|
+| **Impact** | If this ships, what changes for the business in 90 days? | 1 (marginal) → 5 (transformative) |
+| **Dependency** | How many other initiatives are blocked waiting for this? | 0 (standalone) → 5 (critical path for 3+ others) |
+| **Cost of delay** | What happens each week this doesn't ship? | 1 (nothing) → 5 (measurable loss or regulatory exposure) |
+
+**Triage score = Impact + Dependency + Cost of delay** (simple sum, 3–15 range).
+
+**3. Sort into three lanes:**
+
+| Lane | Score | Action |
+|------|-------|--------|
+| **Now** (max 3) | 11–15 | Active work this phase. FDE and team capacity allocated. |
+| **Next** (max 5) | 7–10 | Sequenced for the following phase. Dependencies tracked but not started. |
+| **Later** (unlimited) | 3–6 | Captured, not committed. Revisit at next triage. |
+
+**The cap matters.** "Now" has exactly 3 slots. Not 4, not "3 plus this small one." Discipline is the product.
+
+**4. Handle the political override.** When a powerful stakeholder pushes a low-scoring initiative into "Now":
+
+- Show the displacement: "Adding X to Now means Y drops to Next. Y is currently blocking Z and W."
+- Let them choose: "Which of the current three should Y replace?" Making the trade-off visible makes the conversation honest.
+- If they override without trading: log it. `decisions.md`: "Initiative X added to Now without displacement by <who>. Capacity impact: <what slows>."
+
+**5. Set the triage cadence.** Triage is not a one-time event:
+
+| Engagement type | Triage frequency | Trigger for emergency re-triage |
+|----------------|-----------------|-------------------------------|
+| Sprint (1–2 weeks) | Once, at plan | Crisis or sponsor change |
+| Standard (1–4 weeks) | Weekly | New P0 from sponsor |
+| Programme (months) | Bi-weekly | Quarterly review, team change, market shift |
+
+**6. Communicate the triage result.** The output is not just a priority list - it's a commitment:
+
+> "We're committing to these three initiatives this phase: [A, B, C]. Here's why, here's what they deliver, and here's what's explicitly deferred: [D, E, F, ...]. If priorities change, we re-triage - we don't add without removing."
+
+## Artifact
+
+**`decisions.md`** - the triage table with scores, lanes, and the commitment statement. Dated. Referenced by plan and status.
+
+**`reality.md`** - if triage revealed that the engagement scope is larger than the timeline supports, update the assessment.
+
+## Checkpoint
+
+Walk the FDE through: the 3 "Now" initiatives and why, the top "Next" items and what triggers their promotion, and the one initiative that will generate the most political pushback for being in "Later." Prepare the FDE for that conversation.
+
+## Principles
+
+- "Now" has 3 slots. Not 4. Discipline is the product.
+- Every addition requires a removal. Visible trade-offs beat invisible overload.
+- Triage is recurring, not one-time. The list changes; the discipline doesn't.
+- A logged override protects the FDE. An unlogged override blames them.
+- The initiative everyone wants but nobody will trade for is the one to watch.

package/skills/fde/references/land.md

@@ -0,0 +1,75 @@
+# land - first 48 hours
+
+**Enter when:** new customer, first meeting, just got the brief, nothing started yet.
+
+**Read first:** `context.md` if it exists. Nothing else until you know what kind of engagement this is.
+
+## Method - part 1: interrogate the brief (you do this work)
+
+Read the brief the FDE gives you. What is **not** in it matters as much as what is. Produce the gap list yourself:
+
+- **No named decision-maker** → the FDE will spend two weeks building for someone who can't say yes. Flag it.
+- **"Straightforward cleanup" on an 8-year-old system** → the previous attempt is still visible in git history as a revert. Flag it.
+- **Very tight timeline** → someone already promised the outcome before hiring the FDE. Flag it.
+- **No out-of-scope section** → scope creep is pre-authorized. Flag it.
+
+Write these into `brief.md` as **questions to answer**, not problems - they're what the FDE is walking in to resolve.
+
+Pre-arrival checks to run through with the FDE:
+- Access confirmed? Repo, environment, docs. Waiting for access on day two burns trust.
+- Has someone tried this before? Find out why it failed before assuming this approach is different.
+- Other vendors/teams in scope? Then the FDE is not the only one in the room, even when alone in the meeting.
+- Tech stack recon: job postings, GitHub org - know the stack before they say it.
+
+## Method - part 2: the first conversation (you coach, the FDE asks)
+
+Intent: before any tech, learn what keeps the sponsor up at night - personally, not the project charter. Failure talk surfaces truth faster than "requirements." Angles in the FDE's own words:
+
+- "Before you open the laptop - what would make this a bad engagement for *them*, not just a delayed project?"
+- "What are they afraid you'll miss?"
+- "Who loses credibility if this goes wrong?"
+
+Let silence sit. If their fear doesn't match the written brief, the brief is wrong - say so plainly, log it.
+
+**Listen for, and capture as you hear it:**
+- **The real decision-maker** - whoever others mention most, especially if not yet met. That's who judges the work.
+- **The previous attempt** - "we tried something similar last year" is the most important sentence in the first meeting. Who was involved? Still there and protective, or gone because of it?
+- **The passed-over internal team** - they know exactly what's wrong, and they resent the FDE's presence. Find them before the first standup, ask what they tried, use their language in every meeting. Make them look right and they protect you; ignore them and they wait for the mistake.
+- **The sacred thing** - "Is there anything in this environment I should treat as untouchable?" The hesitation before the answer is the answer.
+- **AI posture and policy** - tools already in use (sanctioned or shadow), and: "Does your organisation have a policy on AI-generated code? Are there decisions where you would not be comfortable with AI involvement?"
+- **Boundaries in multi-vendor rooms** - who owns what surface, who signs off before a change crosses it.
+
+## The day 1 deliverable
+
+Before the end of day 1, ship one visible thing: a small bug fix, a cleanup the team has stepped over, a dashboard tweak, a config improvement. Not because it matters technically - because it proves you can ship in their environment without breaking things. The first deploy sets the trust trajectory for the entire engagement. A day-1 deliverable earns more credibility than a week-3 architecture deck.
+
+## Artifact (write as the conversation is debriefed)
+
+**`brief.md`** - what they said, who sent the FDE, the timeline, **and the gap list**.
+
+**`success.md`** - what done looks like, how it's measured, who actually signs off, what is explicitly out of scope. Agreed with the customer, not assumed.
+
+**`stakeholders.md`**:
+```markdown
+| Who | Role | Signal | Notes |
+|-----|------|--------|-------|
+| <name> | sponsor / champion / resistor / veto / passed-over | green/amber/red | <evidence, day> |
+```
+
+**`trust-profile.md`** - sacred data (`<private>` tagged), fears heard, AI policy, approval chain. Sensitive: never loaded for status reads, never into subagent prompts.
+
+One falsifiable hypothesis about the real problem goes at the bottom of `brief.md` - discover will test it.
+
+## Checkpoint
+
+One page back to the FDE: success + sign-off owner, out-of-scope boundary, sacred data, stakeholder map with veto power, AI posture, the hypothesis. If it doesn't fit one page, the engagement isn't understood yet.
+
+If remote: trust-building takes ~40% longer - push for a short video call before anything asynchronous.
+
+## Principles
+
+- Never start technical work before `success.md` exists.
+- Sacred data never enters AI context. Ever.
+- The brief is a hypothesis; discover confirms it.
+- The passed-over internal team is the best source of truth, not an obstacle.
+- If the customer cannot define success, that is the first problem to solve.

package/skills/fde/references/multi-customer-ops.md

@@ -0,0 +1,114 @@
+# multi-customer-ops - juggling engagements without dropping any
+
+**Enter when:** the FDE is running 2+ engagements simultaneously, context-switching is causing mistakes or delays, a new customer is being onboarded while existing engagements are active, or the FDE says "I'm losing track."
+
+**Read first:** Run `fde status` for the portfolio view. Then per engagement: `context.md` only - load deeper files only for the engagement being worked on.
+
+The solo FDE running three customers simultaneously is the norm, not the exception. Without a system, the third customer gets the scraps of attention left after the other two have their crises. Multi-customer ops is the discipline of giving each customer the experience of being your only customer.
+
+## Method (you do this work)
+
+**1. The hard boundary: one `.fde/` per customer, always.**
+
+```
+~/fde-engagements/
+  acme-corp/.fde/         ← Acme's engagement memory
+  globex/.fde/            ← Globex's engagement memory
+  initech/.fde/           ← Initech's engagement memory
+```
+
+**Never:**
+- Merge two customers' data into one folder
+- Reference one customer's code/data in another's context
+- Load two customers' `.fde/` folders in the same session
+- Copy patterns between customers without stripping identifying information
+
+Cross-contamination is the fastest way to lose two engagements at once.
+
+**2. The daily triage.** Every morning, before opening any editor:
+
+```markdown
+## Daily triage - <date>
+
+| Customer | Trust signal | Top risk | Today's action | Time budget |
+|----------|-------------|----------|---------------|-------------|
+| Acme | green | Migration deadline Fri | Finish data mapping, send status | 4h |
+| Globex | AMBER | Sponsor went quiet Tue | Proactive conversation TODAY | 2h |
+| Initech | green | None active | Build slice 3, push PR | 2h |
+
+Priority order: Globex (amber trust), Acme (deadline), Initech (steady)
+```
+
+**3. The triage rules.** In order of priority:
+
+| Priority | Rule | Why |
+|----------|------|-----|
+| **1** | Trust fires first | A green-trust engagement with a deadline can wait 4 hours. An amber-trust engagement cannot wait 4 hours - it's 48 hours from red. |
+| **2** | Deadlines second | Real deadlines (customer-facing, regulatory, contractual) outrank planned milestones. |
+| **3** | Highest-value delivery third | The engagement where today's work produces the most visible outcome. |
+| **4** | Steady-state last | Engagements on track with no urgent needs get allocated remaining time. |
+
+**4. Context-switch protocol.** When moving between customers:
+
+```
+BEFORE LEAVING CUSTOMER A:
+  1. Write 3 lines to context.md: where we are, what changed, next step
+  2. Commit or stash any work in progress
+  3. Close all customer A files and browser tabs
+
+BEFORE STARTING CUSTOMER B:
+  1. Run: fde resume (loads Customer B's engagement)
+  2. Read context.md - where did we leave off?
+  3. Confirm: what's the one thing to accomplish in this block?
+  4. Set a time boundary (e.g., "2 hours on Globex, then back to Acme")
+```
+
+The 3-line context update is the bridge. Without it, the next session starts with "what was I doing?" - that's 20 minutes of re-discovery each time.
+
+**5. The communication cadence.** Each customer gets a rhythm:
+
+| Engagement intensity | Status cadence | Touchpoint type |
+|---------------------|---------------|-----------------|
+| Active build (daily work) | Weekly written + ad-hoc Slack | Status update + visible progress |
+| Light touch (2–3 days/week) | Weekly written | Status update + next week's plan |
+| Monitoring only | Bi-weekly written | Health check + any emerging risks |
+
+**The golden rule: no customer should have to chase you for an update.** Proactive status updates are cheaper than reactive ones - and they protect trust across all engagements.
+
+**6. Capacity management.** The honest conversation with yourself:
+
+| Situation | Action |
+|-----------|--------|
+| All engagements are steady | Allocate by value; reserve 20% for unplanned |
+| One engagement is on fire | Other engagements get a proactive heads-up: "Focus is on X this week; here's what's planned for you next week" |
+| Two engagements are on fire | Triage - one gets full attention, one gets stabilised, tell the sponsor of the stabilised one what's happening |
+| Three+ are on fire simultaneously | Escalate to your manager/team. Solo capacity is exceeded - communicate before quality drops |
+
+**7. The cross-contamination checklist.** Before every customer interaction:
+
+- [ ] Am I in the right `.fde/` folder?
+- [ ] Am I referencing the right customer's context?
+- [ ] Is the status update addressed to the right person?
+- [ ] Does my current context contain any data from another customer?
+- [ ] Are my browser tabs / code editors pointed at the right customer?
+
+One wrong customer name in a status update damages both relationships.
+
+## Artifact
+
+**`context.md`** (per customer) - the 3-line bridge updated at every context switch. The most-written file in multi-customer ops.
+
+**`fieldbook.html`** - regenerated by `fde dashboard` (deterministic, zero tokens) to give the portfolio view. Trust-ordered.
+
+## Checkpoint
+
+The daily triage is the checkpoint. One line per customer: signal, priority, today's action. If any customer hasn't been touched in 3+ business days: flag it - silence is noticed.
+
+## Principles
+
+- One `.fde/` per customer. Never merge. Never cross-reference.
+- Trust fires outrank deadlines. A deadline can be renegotiated; trust can't.
+- Write the 3-line context bridge at every switch. 20 seconds saves 20 minutes.
+- No customer should have to chase for an update.
+- Two fires simultaneously is a triage decision. Three is an escalation.
+- The wrong customer name in a status update is a two-customer trust fire.

package/skills/fde/references/observability.md

@@ -0,0 +1,103 @@
+# observability - if you can't see it running, you can't operate it
+
+**Enter when:** shipping a feature to production, the customer says "we don't know when things break," a post-incident review revealed gaps in monitoring, or the handoff needs the team to operate what was built.
+
+**Read first:** `terrain.md`, `delivery.md`, `context.md`. Load `trust-profile.md` if the data flowing through logs contains sensitive information.
+
+Code without observability is code you can't operate. The FDE who ships a feature without telemetry creates a callback in six weeks when it breaks and nobody can tell why. Observability is built alongside the feature, not after - the same way tests are.
+
+## Method (you do this work)
+
+**1. Define "working" before instrumenting.** Write 2–4 questions that the person on call will ask about this feature:
+
+```
+FEATURE: payment retry logic
+QUESTIONS ON-CALL WILL ASK:
+1. What fraction of payments succeed on first attempt vs after retry?
+2. When a payment fails permanently, why? (provider error? timeout? validation?)
+3. Is the payment provider slower than usual?
+4. Are retries causing duplicate charges?
+→ Every signal below must help answer one of these.
+```
+
+If you can't name the questions, you're not ready to instrument - you'll log everything and learn nothing.
+
+**2. Pick the right signal for each question:**
+
+| Signal | Answers | When to use |
+|--------|---------|-------------|
+| **Structured log** | "What happened in this specific case?" | Individual request debugging, audit trails |
+| **Metric** | "How often / how fast, in aggregate?" | Dashboards, alerting, trend detection |
+| **Trace** | "Where did time go across services?" | Cross-service latency, bottleneck identification |
+
+Rule of thumb: metrics tell you **that** something is wrong, traces tell you **where**, logs tell you **why**.
+
+**3. Structured logging - events, not prose.**
+
+```
+BAD:  logger.info(`Payment ${id} failed for user ${userId} after ${n} retries`)
+      → Unqueryable, inconsistent format, buried in noise
+
+GOOD: logger.info({ event: "payment_failed", payment_id: id, user_id: userId,
+        retry_count: n, error_code: "PROVIDER_TIMEOUT", duration_ms: elapsed })
+      → Queryable, alertable, structured for dashboards
+```
+
+Every log line: a stable event name + machine-readable fields. Human-readable messages are for debugging sessions; structured events are for production operations.
+
+**4. The four metrics every FDE feature needs:**
+
+| Metric | What it measures | Alert threshold |
+|--------|-----------------|-----------------|
+| **Error rate** | Failures / total requests | >2x baseline for 5 minutes |
+| **Latency (p95/p99)** | How long the operation takes | >2x normal for 5 minutes |
+| **Throughput** | Requests per second/minute | <50% of normal for 10 minutes (demand drop = upstream problem) |
+| **Business metric** | The thing the feature is supposed to improve | Direction reverses for 1 hour |
+
+The business metric is the one most FDEs skip and the one the sponsor cares about most. "Error rate is fine" means nothing if payments processed per hour dropped.
+
+**5. Alert design - avoid noise, ensure action:**
+
+| Principle | How |
+|-----------|-----|
+| **Every alert has an owner** | If nobody is named, nobody responds |
+| **Every alert has a runbook** | "Error rate spiked" → "Check these three things in this order" |
+| **Severity maps to response time** | Critical: 15 min. Warning: next business day. Info: weekly review. |
+| **No alert without action** | If the response is "ignore it" three times, delete the alert |
+
+**6. AI component observability.** AI features fail differently - they degrade, they don't crash:
+
+| What to observe | Why |
+|----------------|-----|
+| Model input/output pairs (sampled, privacy-respecting) | Detect drift: outputs changing without code changing |
+| Latency per model call | Provider degradation is gradual, not binary |
+| Fallback activation rate | If fallback fires >5%, the primary path has a problem |
+| Confidence/quality score trend | A score that slowly drops = model drift |
+| Token usage / cost per request | Cost creep is invisible until the bill arrives |
+
+**7. The sacred-data boundary.** Before shipping any observability:
+
+- Check `trust-profile.md` for `<private>` tagged data.
+- PII in logs = a breach, not a debug aid. Mask, hash, or exclude.
+- In healthcare: PHI in logs violates HIPAA. In fintech: PANs in logs violate PCI-DSS.
+- Default: log IDs, not values. `user_id: 12345` not `user_email: jane@...`
+
+## Artifact
+
+**`delivery.md`** - under each shipped feature: what's observable, where to look, alert thresholds, the runbook.
+
+**`handoff.md`** (when close approaches) - the on-call guide: "what each alert means and what to do."
+
+**`risks.md`** - if observability gaps were found in existing code: what's unobserved and the risk it carries.
+
+## Checkpoint
+
+Before marking a feature shipped: the four metrics are emitting, alerts have owners and runbooks, sacred data is not in logs. If any gap: "Observability incomplete - <specific gap> - shipping without it means <specific risk>."
+
+## Principles
+
+- Define the questions before choosing the signals. Unquestioned telemetry is noise.
+- Metrics for detection, traces for location, logs for explanation.
+- Every alert has an owner and a runbook, or it's noise.
+- AI features need observability for drift, not just failures.
+- PII in logs is a breach. Default to IDs, not values.

package/skills/fde/references/options-analysis.md

@@ -0,0 +1,81 @@
+# options-analysis - three paths, not one recommendation
+
+**Enter when:** a significant technical or strategic decision needs to be made, the FDE is asked "what should we do?", the team is stuck between approaches, or a fork in the engagement requires the sponsor's input.
+
+**Read first:** `reality.md`, `terrain.md`, `success.md`, `context.md`. Load `business-case.md` if the decision has cost implications.
+
+One option is a request for trust. Two options is a false choice. Three options is a conversation between professionals. The FDE who presents three genuine options earns the decision-maker's respect - and their protection when things get hard.
+
+## Method (you do this work)
+
+**1. Name the decision.** One sentence: what needs to be decided, by whom, by when, and what happens if it's deferred.
+
+> "Decision: approach for the payment migration. Decided by: CTO. Needed by: Friday. Deferral cost: blocks the next sprint and delays the pilot by two weeks."
+
+**2. Generate three genuine options.** Not "good / medium / bad" - three approaches with real trade-offs:
+
+| Option archetype | Description | When it fits |
+|-----------------|-------------|-------------|
+| **Conservative** | Lowest risk, smallest change, longest timeline | When trust is thin or the system is fragile |
+| **Pragmatic** | Balanced risk/reward, proven patterns, moderate timeline | When the team is competent and the deadline is real |
+| **Ambitious** | Highest reward, most change, highest risk | When the sponsor has appetite and the team has capacity |
+
+Each option must be one the FDE would genuinely recommend under different circumstances. If you can't defend an option, replace it - padding is visible.
+
+**3. Structure each option identically.** Same dimensions, same format - so comparison is instant:
+
+```markdown
+### Option A: <name> (Conservative)
+- **What:** <the approach in one paragraph>
+- **Timeline:** <estimate with basis>
+- **Cost:** <effort, infrastructure, external>
+- **Risk:** <what could go wrong and the mitigation>
+- **Trade-off:** <what you give up by choosing this>
+- **Best when:** <the condition that makes this the right choice>
+```
+
+**4. Add the comparison matrix.** Visually scannable:
+
+| Dimension | Option A | Option B | Option C |
+|-----------|----------|----------|----------|
+| Timeline | 6 weeks | 4 weeks | 3 weeks |
+| Risk | Low | Medium | High |
+| Reversibility | Easy rollback | Partial rollback | Difficult to reverse |
+| Team impact | Minimal | Moderate retraining | Significant ramp-up |
+| Long-term cost | Highest (tech debt) | Moderate | Lowest |
+
+**5. State your recommendation - and why.** The options are objective; the recommendation is your professional judgment:
+
+> "I recommend Option B. The timeline pressure makes the conservative approach too slow, but the system fragility (see terrain.md hotspots) makes the ambitious approach reckier than the reward justifies. Option B gets us to pilot in 4 weeks with a tested rollback."
+
+**6. Handle the override gracefully.** If the sponsor picks a different option:
+
+- Log it in `decisions.md`: the choice, who made it, the trade-off they accepted.
+- Adjust the plan to the chosen option. Don't passive-aggressively optimise for your preference.
+- If the chosen option has a specific risk you flagged: note the early-warning signal in `risks.md` so it's caught if it materialises.
+
+## Artifact
+
+**`decisions.md`** - the options analysis:
+```markdown
+## Decision: <name> - <date>
+Decided by: <who>
+Options presented: A (<name>), B (<name>), C (<name>)
+Recommended: B - <one line why>
+Chosen: <A/B/C> by <who>
+Trade-off accepted: <what the choice gives up>
+```
+
+The full option details in the same entry or linked to a section in `reality.md`.
+
+## Checkpoint
+
+Present the three options and the recommendation. One question to the FDE: "Which option matches what the sponsor can hear right now?" (A risk-averse sponsor after an incident → conservative. A founder pre-fundraise → ambitious.) If unsure: present all three and let the sponsor decide.
+
+## Principles
+
+- Three options, never one. One option is a request for trust; three is a real decision.
+- Each option must be genuinely defensible - no straw men.
+- Same structure for each option. Comparison should take 30 seconds.
+- Recommend one. State why. Accept the override gracefully.
+- An override logged with its trade-off protects the FDE when the risk materialises.

package/skills/fde/references/pattern-extract.md

@@ -0,0 +1,93 @@
+# pattern-extract - if you did it twice, encode it
+
+**Enter when:** the engagement is closing and reusable patterns exist, a technique worked well and will apply to future clients, the FDE notices themselves doing the same thing on a second engagement, or close identified a pattern worth preserving.
+
+**Read first:** `decisions.md`, `reality.md`, `delivery.md`, `retrospectives/`, `context.md`. Patterns live in what was *done*, not what was planned.
+
+The difference between a 5-year FDE and a 15-year FDE is not talent - it's encoded patterns. The 15-year FDE walks into a new engagement and recognises the situation in minutes because they've seen it before, named it, and know the move. Pattern extraction turns experience into reusable intelligence.
+
+## Method (you do this work)
+
+**1. Identify the pattern candidates.** Scan the engagement for things that:
+
+| Signal | Example |
+|--------|---------|
+| Worked well and would work again in a similar situation | The "show the workaround first" approach to earning ops team trust |
+| Failed and the failure mode is predictable | The "refactor before understanding" mistake on legacy codebases |
+| Was discovered late and should have been discovered early | The hidden cron job that broke the migration - always ask about cron jobs |
+| Required a workaround that others would face too | The compliance dance for getting AI tools approved in regulated environments |
+| Involved a political dynamic that repeats | The passed-over internal team dynamic - present in every engagement with external FDEs |
+
+**2. Write the pattern in a transferable format.** Each pattern must be usable by a future FDE who has never heard of this engagement:
+
+```markdown
+## Pattern: <name>
+
+### Situation
+<When does this pattern apply? What does the FDE see/hear that triggers recognition?>
+
+### The move
+<What to do, specifically. Not advice - steps.>
+
+### Why it works
+<The mechanism - why this approach succeeds where the obvious approach fails.>
+
+### Watch out for
+<The failure mode or edge case that makes the pattern not apply.>
+
+### Evidence
+<Which engagement, what happened, what the result was. Specific, not generic.>
+```
+
+**3. The pattern quality test.** Before encoding:
+
+| Test | Pass | Fail |
+|------|------|------|
+| **Transferable?** | Another FDE could apply this without context from this engagement | Only makes sense if you know the specific client |
+| **Specific enough?** | Contains concrete steps, not just principles | "Build trust" / "Communicate well" - too vague to act on |
+| **Repeatable?** | Applies to a class of situations, not just this one | Only worked because of a unique circumstance |
+| **Falsifiable?** | You can tell when the pattern is working or not | No way to measure whether applying it helped |
+
+**4. Classify by domain.** Patterns sort into the same domains as the skills:
+
+| Domain | Pattern type | Example |
+|--------|-------------|---------|
+| **Embed & Trust** | Political / relational | "The passed-over team warm-up protocol" |
+| **Discover & Diagnose** | Investigative / analytical | "The cron-job discovery checklist for legacy systems" |
+| **Plan & Align** | Structural / strategic | "The three-option presentation for nervous sponsors" |
+| **Build & Guard** | Technical / safety | "The Strangler Fig on financial transaction code" |
+| **Ship & Verify** | Operational / process | "The regulated-environment change-approval timeline buffer" |
+| **Operate & Close** | Knowledge / handoff | "The 2am document format that actually gets used" |
+
+**5. Version and evolve.** Patterns are living documents:
+
+- First use: **v0.1** - hypothesis based on one engagement
+- Second use: **v1.0** - confirmed pattern, refined from two experiences
+- After modification: increment minor version with what changed and why
+- After contradiction: note the counter-example, adjust the "watch out for" section
+
+**6. Cross-engagement pattern mining.** When the FDE has multiple engagements in `.fde/`:
+
+- Compare `reality.md` across engagements - do the same problems recur?
+- Compare `decisions.md` - are the same decisions being made?
+- Compare `retrospectives/` - are the same lessons being "learned" twice?
+
+A pattern learned twice is a process failure. Encoding it prevents the third time.
+
+## Artifact
+
+**`patterns.md`** - the pattern library, growing across engagements. Each pattern in the format above. Indexed by domain and situation trigger.
+
+**`retrospectives/YYYY-MM-DD-<engagement>.md`** - reference to which patterns were extracted from this engagement.
+
+## Checkpoint
+
+Present the extracted patterns to the FDE: "From this engagement, I've identified N patterns worth encoding. The highest-value one is <name> because <it will apply to future engagements in these situations>." Confirm the pattern is accurate - the FDE's field judgment outranks the analysis.
+
+## Principles
+
+- If you did it twice, encode it. The same lesson learned three times is a failure.
+- Patterns are steps, not principles. "Build trust" isn't a pattern; "fix a small visible bug on day one" is.
+- Every pattern needs a situation trigger - the FDE must recognise when it applies.
+- Version patterns. A pattern from one engagement is a hypothesis; from two, it's confirmed.
+- The pattern library is the FDE's compound interest. It's what separates 5 years of experience from 1 year repeated 5 times.

package/skills/fde/references/plan.md

@@ -0,0 +1,108 @@
+# plan - sequence the work
+
+**Enter when:** scope is understood and the work needs breaking down - a slice, a phase, or the whole delivery.
+
+**Read first:** `reality.md`, `success.md`, `terrain.md`, `stakeholders.md`. Load `business-case.md` if sketch produced one. Not the full folder.
+
+An FDE plan is not a sprint backlog. The technical sequence is the easy part. The hard part is when to show progress, who approves the next phase, and where trust is thin enough that two silent weeks read as failure. A technically correct plan that ignores engagement politics fails on schedule.
+
+## Method (you do this work)
+
+**0. Lock scope first.** Read `success.md`. If out-of-scope is undefined, define it now with the FDE - a plan on undefined scope accumulates silent commitments.
+
+**1. Work backwards from success.** What's the last thing that must be true before done? And before that? That's the dependency chain - not a wish list.
+
+**2. Front-load the fragile.** Check `terrain.md` hotspots. Risky modules go early - fail fast, not in week three.
+
+**3. Slice vertically.** Each task delivers something visible and testable end to end ("user submits form, sees it saved"), never a horizontal layer ("build the database layer").
+
+**4. Size to 30–90 minutes, PR-sized.** Longer = two tasks. Each task implementable, testable, reviewable without a thousand-line diff.
+
+**5. AI components get explicit eval tasks.** "Output validated on 50 real production examples," "fallback tested under model unavailability," "inputs/outputs logging to <destination>" - these are pre-conditions of shipping, in the plan before build starts.
+
+**6. Stakeholder touchpoints every 2–3 tasks.** "Show progress to <name from stakeholders.md>." Not ceremony: a customer who sees small wins stays bought in; silence gets filled with doubt.
+
+**Acceptance criteria gate:** no task moves to build without written happy-path AND unhappy-path criteria. Can't write them = the task isn't understood; the open question goes to the customer **before** the task starts. Vague criteria surface later as scope creep and rework.
+
+## Artifact
+
+The plan goes to **`decisions.md`** - always. Build reads the plan from `decisions.md`; anywhere else and the build starts blind.
+
+```markdown
+Task N: <outcome, not activity>
+Delivers: <what someone can see/test>
+Accepts: <happy path> / <unhappy path>
+Touches: <files/systems - blast radius declared upfront>
+Risk: <what could go wrong + fallback>
+Verify: <specific check>
+```
+
+## Checkpoint
+
+Walk the FDE through: sequence + why this order, where the fragile work sits, where the touchpoints land, the acceptance gate on task 1. One question: "Which stakeholder sees the first visible slice, and when?"
+
+## Method - estimation (when the sponsor asks "how long, how much?")
+
+Every FDE gets asked this in week one. The honest answer is a range, not a number. A single-point estimate is a promise; a range is a professional assessment.
+
+**The 3-point method:**
+1. **Best case** - everything goes right, no surprises, team has capacity. This is what the sponsor wants to hear.
+2. **Expected case** - normal friction: one discovery changes the plan, one integration takes longer, one approval cycle stalls. This is what to plan against.
+3. **Worst case** - a major unknown surfaces, a dependency fails, a key person is unavailable. This is what to protect against.
+
+**Present as:** "2–4 weeks expected, could stretch to 6 if [named risk]." Never give one number.
+
+**The sizing table:**
+
+| Slice | Complexity | Dependencies | Unknowns | Estimate (expected) |
+|-------|-----------|--------------|----------|---------------------|
+| _per vertical slice from the plan_ | Low/Med/High | Named | Named | X days/weeks |
+
+**Rules:**
+- Estimate in weeks for engagements > 1 month. Days for < 1 month.
+- Add 30% buffer for integration work (it always takes longer).
+- Add 50% buffer for AI/ML work (eval cycles are unpredictable).
+- Name assumptions explicitly: "assumes API docs are accurate", "assumes staging environment exists."
+- Revisit estimates every 2 weeks. An estimate that never updates is fiction.
+
+Write estimates to `decisions.md` under `## Sizing`. Include the assumptions - when they break, the estimate changes and the FDE has evidence for the conversation.
+
+## Method - migration strategy (when the engagement is "move from X to Y")
+
+Migrations are the most common enterprise FDE engagement. The strategy precedes the plan:
+
+**Step 1: Classify the migration type.**
+
+| Type | What it means | Risk profile |
+|------|---------------|-------------|
+| **Rehost** (lift-and-shift) | Same code, different infrastructure | Low code risk, high ops risk |
+| **Replatform** | Minor code changes to use new platform features | Medium risk, clear scope |
+| **Refactor** | Rewrite components to fit the new architecture | High risk, scope creep magnet |
+| **Replace** | Buy/build new, retire old | Highest risk, requires parallel running |
+| **Retire** | Turn off, nobody uses it | Politically hard, technically easy |
+
+**Step 2: Map the dependency graph.** What calls what. What breaks if this moves first. The migration order is the reverse of the dependency chain - leaf nodes first, core last.
+
+**Step 3: Define the cutover strategy.**
+- **Big bang** - everything moves at once. Fast but catastrophic on failure. Only for small systems.
+- **Strangler fig** - new traffic to new system, old traffic drains. Safe but slow. Preferred for anything load-bearing.
+- **Parallel run** - both systems run, outputs compared. Expensive but safest for data-critical systems.
+
+**Step 4: Write the rollback before the migration starts.** "If we move service X and it fails, we route back to old within [time]." No rollback = no migration.
+
+**Step 5: Define success metrics per phase.** Not "migration complete" - that's a project plan. "Error rate same or lower, latency within 10%, zero data loss, team can operate without FDE." Measurable, per service.
+
+Write migration strategy to `decisions.md` under `## Migration`. Each service gets a row: type, order, cutover method, rollback, success metric.
+
+## When the plan changes mid-engagement
+
+Never quietly update tasks. Name the reset: update `reality.md` and `success.md`, one paragraph in `decisions.md` - what changed, why, new sequence. An undocumented reset looks like drift; a documented one looks like the FDE caught something important.
+
+## Principles
+
+- Plan from success backwards, not from today forwards.
+- Fragile zones early. Fail fast.
+- Every 2–3 tasks, a stakeholder touchpoint. Trust decays without visibility.
+- No written acceptance criteria, no build.
+- Estimates are ranges, not promises. Name the assumptions.
+- Migrations: leaf nodes first, core last. Rollback before cutover.