fdeops 4.0.3 → 4.1.0

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

@@ -0,0 +1,90 @@
+# business-case - Build the business case
+
+**Context:** apply [task context and evidence](task-context.md) before using the named records below.
+
+**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 poc produced a direction that needs funding.
+
+**Read first:** `reality.md`, `success.md`, `delivery.md`, `context.md`. Load `business-case.md` from poc 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 |
+|-----------|---------------|---------|
+| **Labor capacity / direct spend** | Ask: "What does this problem cost per month in money?" | Manual reconciliation hours × loaded rate = capacity value; separately identify reducible spend |
+| **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>
+    → Benefit: <capacity released, avoidable cash spend, revenue, or risk reduction>
+      → Net cash: realizable incremental cash benefit - full costs over <time horizon>
+```
+
+Keep drivers, units, sources, and ranges explicit. For example, 3 people × 8h/week × $75/h × 52 weeks = $93.6K/year of labor capacity value. It is cash savings only if spend actually falls (for example, paid overtime or a contractor cost ends). Name who can realize the benefit and how. Include build, ongoing operation, adoption, and transition costs; avoid double-counting capacity and revenue enabled by the same hours. Do not calculate cash payback from capacity value alone.
+
+**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:
+
+> "The capacity case assumes the team reclaims 6 hours/week per person. At 3 hours, that benefit halves. Cash payback remains unproven until finance identifies avoidable spend. Validate time-spent before and after the pilot with representative 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 from realizable cash benefits, or not established>
+**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," inspect the disputed inputs and sources, test plausible ranges, and identify what measurement would resolve the disagreement. Never reverse-engineer assumptions to hit a desired number.
+
+## Worked example
+
+Acme phase 2 needs funding. The case starts with the cost of doing nothing, not the cost of building.
+
+Anchor: two silent failures since March, each one day of finance reconciliation by hand plus a late close (`reality.md`, Marco's sheet). That is the number the sponsor already believes because her own team reported it.
+
+Driver model the sponsor can trace: incidents/quarter × hours of manual reconciliation × loaded cost, plus the tail risk of a late regulatory close - stated separately, because mixing a certain small number with an uncertain large one is how a case loses credibility.
+
+Sensitivity names the two drivers that swing it: incident frequency (2/quarter → 1/quarter and the case halves) and whether the manual re-run continues in parallel (if Marco keeps re-running every morning, the saving is theoretical). The second one is the honest weakness, so it is in the case rather than waiting to be found in the room - with the condition that makes it hold: the morning re-run stops after two clean cycles, agreed with Marco.
+
+## 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-poc/references/debug.md

@@ -0,0 +1,18 @@
+# debug - Find and repair the cause
+
+**Enter when:** a reproducible failure, regression, incident symptom, or misleading output needs investigation.
+
+Use [task context](task-context.md). Work from supplied permitted evidence without requiring `.fde/`. During an active incident, follow the authorized containment procedure before diagnosis; investigation authority alone does not authorize production writes.
+
+## Method
+
+1. Capture expected and observed behavior, exact input or trigger, affected revision/environment, and the last known working state. Preserve useful errors and timestamps without copying secrets or raw private data. Mark reports you have not reproduced as reports.
+2. Inspect the failing path, callers, recent relevant changes, and existing tests. Reproduce in a permitted environment with the smallest representative case. If reproduction is unavailable, identify what observation would distinguish causes and gather safe evidence; do not claim a hypothesis is proven.
+3. Keep a short hypothesis list. For each, name the predicted observation and a discriminating check. Change one relevant variable at a time. Trace values and control flow across the actual boundary instead of repeatedly changing code until the symptom disappears.
+4. Fix the cause at the appropriate layer. Check whether the proposed fix changes behavior for other callers, stale data, retries, concurrency, or permissions. Preserve evidence of the original failure and avoid unrelated cleanup.
+5. Add a regression check when it can meaningfully reproduce the bug; show that it fails before the fix and passes after when practical. If the check cannot run against the before-state, say so. Run affected adjacent and required checks using [verification](verification.md).
+6. Review the final diff and exercise the original journey. For substantial or risky fixes use [review](review.md). After two unsuccessful repair cycles, reassess the hypothesis and evidence instead of repeating the same attempt; continue useful investigation and isolate the missing decision or access.
+
+## Deliverable and acceptance
+
+Report the cause with its evidence, the fix, the original reproducer's result, adjacent checks, and unresolved uncertainty. A disappearing symptom with no discriminating evidence is a mitigation, not a demonstrated root cause. In engagement mode record the incident/fix receipt in the appropriate existing record; standalone work may return it directly. Release or rollback requires the existing operational authority and [ship](ship.md) or recovery procedure.

package/skills/fde-poc/references/discover.md

@@ -0,0 +1,254 @@
+# discover - Frame the problem
+
+**Enter when:** the brief feels wrong, the real problem is unclear, shadow processes are suspected, or any phase found that the map is missing.
+
+**Read first:** `context.md`, `brief.md`. Load `terrain.md` if it exists - extend it, never regenerate from scratch.
+
+## Validation gate (confirm understanding, clarify where it elevates)
+
+Before discovering, state what you're investigating and why in 2-3 lines:
+
+> "Investigating: [the hypothesis or problem area]. This informs: [the decision it feeds - descope/rescope/pick A over B]. Existing terrain: [what's already mapped vs. what's unknown]."
+
+Then check - probe ONLY if it prevents wasted discovery:
+
+1. **Hypothesis is testable.** If the stated problem is unfalsifiable ("the architecture is wrong") → rephrase it: "I'd narrow this to: [specific testable claim]. That closer to what you're seeing?"
+2. **Discovery feeds a decision.** If there's no named decision → one line: "What changes depending on what we find? That keeps the discovery focused."
+3. **Not repeating previous work.** If terrain.md already covers this area → name it: "Terrain already maps this from Day [X]. Extending it or has something shifted?"
+
+State your read, let the FDE correct, then discover.
+
+Before asking for facts, inspect the supplied brief and existing redacted records for the answer. Once the decision frame is confirmed and code access is authorized, use the scan below and targeted file reads to resolve technical unknowns. Phrase remaining questions around the discrepancy found: “The queue already exists, but alerts are disabled; who currently checks it?”
+
+## Brief interrogation (when the hypothesis is still mush)
+
+Use when the "problem" is unfalsifiable, success is undefined, or you cannot name the decision discovery informs. Skip when `reality.md` / `terrain.md` already pin a testable claim and the FDE is ready to dig.
+
+Same format as land - one Q + GUESS, no checklist:
+
+```
+READ: <the real problem you think exists, in one sentence>
+CONFIDENCE: ~NN% - missing: <what would falsify or confirm it>
+Q: <one question that changes where you dig>
+GUESS: <your answer, so they can correct it>
+```
+
+Stop when you can write the four lines under **Frame the decision first**. If a name, quote, or metric is still missing, write `unknown - ask:` - never invent ops folklore to make the map look complete.
+
+## Frame the decision first
+
+Same SCQA spine as readout (`S → C → Q → A`), aimed at the floor, not a deck. Write it **before** any scan. Confirm with the FDE, then dig.
+
+| Line | What it is | Fail if |
+|------|------------|---------|
+| **Situation** | What they already treat as true - the workaround, the sheet, the owner who left | It could be copied from the RFP |
+| **Complication** | What broke, so they cannot stay here | No tension, or three problems joined by "and" |
+| **Question** | One decision the named signer must make | It smuggles the solution ("how do we add alerting") |
+| **Answer-space** | Shape of a satisfying answer: confirm brief / descope / rescope / pause | A novel, or "insights" |
+
+Tests on **Question** - rewrite until all five hold:
+
+1. **Decision-shaped** - answering it changes what someone does.
+2. **Single** - one thing, not three.
+3. **Scoped** - who, where, by when.
+4. **Answerable** - evidence could settle it in this engagement.
+5. **Neutral** - does not assume the fix.
+
+Cannot write the Question → keep interrogating. Do not `fde scan`. Every later output of this phase aims at that Question. Sub-questions go to the operating map or `assumptions.md`, not into the Question.
+
+## Parts of the problem (decompose only)
+
+After the Question is locked, and **before** `fde scan` or any option: write what the problem is made of. No advice, no playbook, no solution.
+
+If the stated brief hides a deeper job, name that deeper job in one sentence and **wait**. Do not silently replace their problem with yours.
+
+In `terrain.md` under `## Parts`, list the smallest useful pieces that still change what you examine next. Typical cuts: people, process step, system, data, time, cost. For each piece: what it contains, and how it connects to the Question. Stop when a further split would not change where you dig.
+
+Do not mark pieces as facts or assumptions here. That is `test-assumptions`. Do not assemble options here. That is `three-options`.
+
+## Method - part 1: the codebase (you do this work)
+
+**First code move: `fde scan`** - after the Question is locked. It runs everything below deterministically in seconds (churn×tests, "temporary" archaeology, AI components, secrets redacted, previous attempts). Your job is then **interpretation**: read its output against the brief, follow the hotspots into the code, and connect the technical findings to the human signals in part 2.
+
+If the CLI is unavailable, run the manual commands below. Either way: do not load the full codebase into context - scan wide, read deep only on hotspots.
+
+**1. Stack and age.** Language, framework, build system, date of last major upgrade:
+```bash
+git log --reverse --format="%ad" --date=short | head -1   # repo birth
+git log -1 --format="%ad" --date=short                     # last commit
+```
+
+**2. Churn heat - the modules everyone touches but fears:**
+```bash
+git log --since="90 days ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20
+```
+The highest-churn file in a legacy codebase is the one everyone is afraid to refactor but cannot avoid touching. Cross-reference with complexity (file size, nesting) and mark "handle with care."
+
+**3. Test gaps - what's covered, what's a lie:**
+```bash
+find . -path ./node_modules -prune -o -name "*test*" -print | head -30
+```
+Map test files against the churn list. A high-churn module with no test neighbors is a load-bearing wall with no insurance. Spot-read the tests that do exist: tests that pass but assert nothing are worse than no tests - note them.
+
+**4. The "temporary" archaeology** (repeat `--include` per extension - brace globs silently match nothing):
+```bash
+grep -rnE "HACK|FIXME|XXX|temporary|for now|remove this|workaround" \
+  --include="*.js" --include="*.ts" --include="*.py" --include="*.java" \
+  --include="*.go" --include="*.rb" --include="*.cs" --include="*.php" . | head -30
+```
+Temporary code in production is permanent code with an excuse. Each hit is a candidate for "what was never built properly."
+
+**5. AI components - they fail silently:**
+```bash
+grep -rlnE "openai|anthropic|llm|prompt|embedding|vector|inference" \
+  --include="*.js" --include="*.ts" --include="*.py" --include="*.java" \
+  --include="*.go" . | head -20
+```
+Flag every one. AI components don't fail like regular code - they degrade as the world changes. Each needs: model version, fallback path (or note its absence), observability (or note its absence).
+
+**6. Data flow.** Where data enters, how it moves, where it stops. Entry points first: routes, queues, cron, file drops.
+
+**7. Existing capability.** Trace the requested user action through existing code, configuration, tests, and operating workarounds. In `terrain.md`, record what can already be reused and the evidence that it works or fails. Check whether a configuration, ownership, or process change could resolve the observed break. A disabled feature is a lead, not a proven root cause. Keep observations and hypotheses distinct; option selection still belongs to plan / three-options. Summarize the remaining gap in `reality.md`: what works today → what the customer needs → what is still missing, with sources. If existing capability meets the need, say so; do not manufacture a build requirement.
+
+## Method - part 2: the humans (you coach, the FDE asks)
+
+The real spec is what people **do** when the system fails - not what the slide deck says. Arm the FDE with these, in their own words:
+
+- **"How is the team coping today without the fix?"** - the workaround is the honest requirements doc.
+- **Find the spreadsheet.** Almost always there. Whoever maintains it is the best interview in the building.
+- **The hesitation.** When someone says "well, there's also this other thing we do…" - stop them, ask them to finish. The main story is what they're comfortable explaining; the hesitation is the real problem.
+- **"Which part of the codebase do you least want to touch?"** The answer is unanimous and it's the load-bearing wall. Check it against your churn scan - when the human answer and the churn data agree, that's your first map landmark.
+- **Shadow AI.** Someone pasting data into ChatGPT to cope = a real unmet need + an uncontrolled data risk. Note both.
+- **Exception-led operating map.** For each real break (not the slide-deck process): what fails, who notices first, what they do today, and which artifact is trusted in that moment. Prefer exceptions over happy-path swimlanes - the workaround is the operating system. Write rows under `terrain.md` → `## Operating map (exception-led)`. If the section is missing on an older engagement, add it; never regenerate the rest of terrain. When AI is in play, also fill `## Intelligence placement` (deterministic vs LLM judgement vs human approve). **`fde doctor` requires at least one filled exception row before plan/ship/outcome/close** - empty map after discover is a hygiene fail, not optional polish.
+
+## Method - part 3: workshop facilitation
+
+When discovery requires a structured session with multiple stakeholders (alignment, prioritisation, design):
+
+**Before the room:**
+- Define the single decision the workshop must produce - not "discuss options" but "rank the three candidates and commit to one."
+- Cap at 8 people. Every person above 8 halves the probability of a decision.
+- Time-box: 90 minutes max. Anything longer splits into two sessions.
+- Pre-read: one page, sent 48 hours ahead. Nobody will read more.
+
+**In the room (the FDE facilitates, not presents):**
+1. **5 min - frame.** One slide: the decision, the constraint, the deadline. No history lesson.
+2. **15 min - diverge.** Silent post-its (or digital equivalent). Everyone writes before anyone talks - prevents the loudest voice dominating.
+3. **20 min - cluster.** Group themes, name them. The FDE does NOT label - the room labels.
+4. **30 min - converge.** Dot-vote or forced-rank. The FDE counts, the room decides.
+5. **10 min - lock.** State the decision back. "We're saying X. Anyone who can't live with this, speak now." Silence = consent.
+6. **10 min - next steps.** Who does what by when. Written before people stand up.
+
+**After the room:** Summary in `decisions.md` within 2 hours. Decisions decay - what felt clear at 3pm is debatable by 5pm if unwritten.
+
+## Method - part 4: data estate and the pipe
+
+Always map the estate before you score a use case - not only when someone said "AI." A path they cannot feed is a discover miss, not a ship surprise.
+
+**Their words first.** In `terrain.md`, write the names the floor uses for the workaround, the sheet, the exception path, and the person who left. Later plan/ship/review sentences use those names. Do not translate their floor into generic product language.
+
+**The 5 questions (ask the data owner, not the sponsor):**
+1. **Where does data live?** - List every source: databases, warehouses, SaaS exports, spreadsheets, S3 buckets, vendor APIs. Map it.
+2. **How fresh is it?** - Real-time, daily batch, "someone uploads a CSV on Mondays"? Freshness determines what's buildable.
+3. **Who owns it?** - Not "IT" - the named person who can grant access and explain the schema. No named owner: access responsibility remains unverified.
+4. **What's the quality?** - Sample 100 rows from each critical source. Check: nulls, duplicates, format consistency, semantic correctness. A 60% null rate in a key field = that source is fiction.
+5. **What are the governance constraints?** - PII classification, retention policies, cross-border rules, consent basis. One missed constraint = a compliance stop later.
+
+**The pipe (what talks to what).** For each source that a use case depends on, write: the system it flows from and to, the contract (object, table, file, API), whose credentials, what happens when the vendor 500s or the Monday file does not land, and whether the join the sponsor described actually exists. Their IdP, CRM, and warehouse are delivery work when the path needs them - policy questions in `trust-profile.md` are not a substitute.
+
+**The data readiness matrix:**
+
+| Source | Location | Freshness | Owner | Quality (sample) | Governance | Pipe | Verdict |
+|--------|----------|-----------|-------|-----------------|------------|------|---------|
+| _fill per source_ | | | | | | | Ready / Needs work / Blocker |
+
+A use case that depends on a "Blocker" source **or a Blocker pipe** doesn't get scored - it gets a remediation conversation first. `what-breaks` finding an invisible integration at ship is already too late. Write this to `terrain.md` under a `## Data estate` section.
+
+**Promised dependencies are not ready dependencies.** For consequential promises such as "data in two weeks," record or update one dependency entry in `assumptions.md` with the responsible owner, dated verification checkpoint, and evidence needed. Unknown owners or dates stay unknown; propose a checkpoint for confirmation. Link the affected work; if the checkpoint slips, identify what can proceed and what needs replanning. Missing ownership is an unresolved dependency, not proof that the project will fail. On-prem or restricted access is a constraint to investigate, not a red flag by itself.
+
+**Verify the future operator now.** Check the proposed owner in `success.md` against who will actually monitor, recover, and support the result. Record whether they have agreed, access or training gaps, and a practical handoff check there; carry these into `handoff.md` at close. Keep unconfirmed ownership explicit. Reuse supplied evidence and ask only what changes the plan.
+
+## When scope is a transformation, not a single problem
+
+Score every candidate use case before anything gets prototyped:
+
+| Dimension | Question | 1-5 |
+|---|---|---|
+| Business value | What does it cost them unsolved? | |
+| Complexity | How hard to build safely? (5 = hardest) | |
+| Data readiness | Available, clean, sufficient volume today? | |
+
+**Score = (Value × Data readiness) / Complexity.** Highest score gets prototyped first (hand to `poc`). A 5-value/1-complexity/5-readiness case scores 25; a 5-value/5-complexity/2-readiness case scores 2 - they look identical on a whiteboard. Never let a technically interesting use case override the score.
+
+## Artifact (this IS the memory - write it as you work)
+
+**`reality.md`** - the readout the FDE takes into the sponsor meeting. Keep the three schema lines the dashboard reads (`Working theory` / `Evidence` / `Differs from brief how`). Then the decision frame:
+
+```markdown
+# Reality (actual problem)
+**Working theory:** <the real problem, one sentence>
+**Evidence:** <workaround/data/quote, source, day>
+**Differs from brief how:** <delta, with evidence>
+**Situation:** <what the floor already treats as true>
+**Complication:** <what forces a decision now>
+**Question:** <one decision-shaped sentence>
+**Answer-space:** confirm brief / descope / rescope / pause - and what a yes looks like
+**Implication for build:** <first change they can see>
+**Validated with:** <who, when>
+```
+
+**`terrain.md`** - the map every later phase loads:
+```markdown
+# Terrain
+**Stack:** <lang/framework/build, age>
+**Hotspots (handle with care):** <file - churn n/90d - tests: none/weak/ok - why it matters>
+**AI components:** <file - model - fallback? - observability?>
+**Data flow:** <entry → transform → store → exit>
+**Test landscape:** <covered / gaps / lies>
+**Unknowns:** <named explicitly - an honest gap beats a confident guess>
+
+## Operating map (exception-led)
+| Exception / break | Who notices first | What they do today | System of record then | Blast | Evidence |
+|-------------------|-------------------|--------------------|----------------------|-------|----------|
+| <break> | <role> | <workaround> | <sheet/DB/person> | CRITICAL / LOAD-BEARING / CONVENIENCE | <who/day> |
+```
+
+Every line carries its evidence. `(churn: 47/90d)` `(ops lead, Day 5)` `(stated, unverified)`.
+
+**`assumptions.md`** - update statuses from what discovery proved or disproved. Seed any new OPEN assumptions the brief never named. CRITICAL + OPEN must be named in the checkpoint.
+
+## Checkpoint (before any build)
+
+Present to the FDE, five things, one paragraph each - no padding:
+1. The Question, then the real problem, with the two strongest pieces of evidence.
+2. The top 3 risk areas of the codebase, one line of why each.
+3. What must not be touched without characterisation tests.
+4. The exception-led operating map: the two breaks that matter most, who owns the workaround, and where shadow systems live.
+5. The Answer-space: confirm brief / descope / rescope - and the decision it puts in front of the sponsor.
+
+If discovery revealed the problem is 3× the brief: the FDE tells the customer **before** telling themselves it's manageable. Lead with evidence, offer three paths (descope / rescope / pause-and-plan), confirm any reset in writing - update `success.md` and `brief.md` before continuing.
+
+## If you've formed three wrong reads
+
+Stop. Don't form a fourth hypothesis. Three disproven reads means the brief is actively misleading - usually the person who briefed doesn't know, or knows and can't say. Change method: stop analysing the system, ask three people separately "if you had to bet on what's actually wrong here, what would you say?" The thing they all hesitate before saying is the real problem.
+
+## Worked example
+
+Acme's brief blamed missing monitoring. Discovery goes to the workaround first.
+
+`git log` shows the reconciliation module at 47 commits/90d with no tests, all from one author who left in February. Marco (ops lead) turns out to keep a spreadsheet: every morning he re-runs the job manually and eyeballs the totals - a habit nobody mentioned because to him it is just the job. That spreadsheet is the system of record when the job fails, which is the actual finding.
+
+`reality.md` keeps the schema, then the frame. **Working theory:** the job has no owner, and the manual re-run masks failures for a day. **Evidence:** Marco's sheet, Day 5; two silent failures since March, finance escalation Mar 14. **Differs from brief how:** alerting existed last year and was disabled - adding it again without an owner reproduces the same outcome. **Situation:** Marco re-runs the job every morning and the spreadsheet is truth when it fails. **Complication:** two silent failures since March already hit finance, and the author of the module left in February. **Question:** should Priya fund a named owner on the failure path, or fund alerting and accept the same miss in six months? **Answer-space:** fund ownership / fund alerting-as-theatre / pause until she names who acks. `terrain.md` gets the hotspot row and an operating-map row: `job fails silently → Marco notices next morning → re-runs by hand → spreadsheet is truth → LOAD-BEARING (Marco, Day 5)`.
+
+Checkpoint to the FDE leads with that Question, not a tour of the repo.
+
+## Principles
+
+- The brief is a hypothesis until evidence confirms it.
+- No scan until the Question is one decision the signer must make.
+- The workaround is more honest than the requirements document.
+- Churn data + the human's "don't touch that" pointing at the same module = the map is true.
+- Never modify code before the terrain map exists.
+- Scan wide, read deep only on hotspots.
+
+Before changing a surprising workaround, use the targeted history check in [audit](audit.md#before-changing-an-unfamiliar-workaround). Inspect only the implicated file or region; commit messages supply clues, not proof of current requirements.

package/skills/fde-poc/references/eval-pack.md

@@ -0,0 +1,26 @@
+# eval-pack - Evaluate the model's allowed behavior
+
+**Enter when:** AI, LLM, RAG, or agent behavior needs evidence before an experiment, release, or material expansion. Non-AI work skips this method.
+
+Use [task context](task-context.md). Supplied permitted context and an evaluation report are sufficient without `.fde/`. In a coordinated engagement, use the existing trust/terrain context and keep the report in `evals.md`; read only privacy-safe views.
+
+## Method
+
+1. **Define the evaluated surface.** Name the model judgment, inputs, outputs, downstream actions, environment, and relevant failure impact. Separate model quality from deterministic tool authorization and application checks. Document the actual allowed action boundary and its source; missing authority remains unknown.
+2. **Choose cases by risk and coverage.** Use permitted historical examples, expert-labeled cases, or clearly marked synthetic fixtures. Cover relevant segments, boundary conditions, known failure modes, and critical harms. Record input, expected outcome/rubric, provenance, and critical-failure rule per case. Keep evaluation cases separate from tuning where possible; no fixed case count proves safety.
+3. **Agree the pass rule before the run.** Define quality thresholds, critical failures, coverage expectations, and acceptable uncertainty for this use. Use deterministic checks where possible and inspect subjective labels or judge reliability. Propose missing criteria for agreement; do not manufacture acceptance from the observed scores.
+4. **Run the actual evaluated path.** Record model/provider version, prompts/configuration, retrieval corpus or tools, application revision, environment, fixtures, and run date. Repeat where variability matters. Report totals, per-segment results, critical failures, and limitations using [verification](verification.md). A model-only run does not prove the agent's tool boundary works.
+5. **Verify action authority and controls.** Human approval is required where the user's policy or task requires it. Already agreed bounded automation may run within its documented actions, identities, environments, and limits; do not require fresh approval for every authorized action. Check enforcement outside the model, least privilege, input/output validation, cost/rate limits, stop conditions, observability, and recovery as applicable. Unknown or exceeded authority blocks those actions. Evaluation success never grants new authority.
+6. **Make a scoped verdict.** Report **SHIP** only when agreed criteria pass, critical failures are zero, applicable authority/control checks pass, and material coverage gaps are resolved or the release is explicitly narrowed by the responsible decision-maker. Otherwise report **NO-SHIP** with the smallest corrective step: fix, gather evidence, descope, or reconsider the judgment surface. A SHIP verdict is technical evidence for the stated scope, not permission to deploy.
+
+## Deliverable and acceptance
+
+Return the suite/source, thresholds, counts and segments, top failure modes, control evidence, human-review gate or bounded automation authority, limitations, and dated verdict. Record unknown values honestly. Reevaluate after changes that affect model behavior, retrieval, tool permissions, or data conditions; cite why unchanged evidence remains applicable rather than implying a rerun.
+
+When coordinated, append a concise eval receipt to delivery records. For release use [ship](ship.md). For ongoing use define the drift signals, sample policy permitted by data handling rules, owner, and conditions that suspend or narrow automation. Do not store secrets, raw `<private>` data, or hidden chain-of-thought in reports.
+
+## Principles
+
+- Thresholds and authority come from the agreed contract, never from a convenient observed result.
+- Critical failures block the evaluated release scope; disclose coverage and uncertainty.
+- Bound automation with enforceable controls, and require human review where the policy requires it.

package/skills/fde-poc/references/integrate.md

@@ -0,0 +1,18 @@
+# integrate - Prove the system boundary
+
+**Enter when:** connecting an API, data source, SDK, event stream, tool, or service, or changing its contract.
+
+Start from [task context](task-context.md). Permitted supplied context is enough; `.fde/` is optional. Use the customer's existing clients, authentication, fixtures, and diagnostic tools. Do not create another integration platform to make one connection.
+
+## Method
+
+1. Map producer, consumer, owner, direction, and side effects. Inspect the actual installed version and local implementation; verify uncertain behavior against current official documentation. Identify the relevant schema, authentication scopes, network boundary, and permitted test environment.
+2. Write the acceptance example: an input at the real boundary and the observable downstream result. Include a rejection or failure example. Separate configuration validity, successful authentication, transport connectivity, contract compatibility, and end-to-end behavior; none proves the next.
+3. Inspect credentials by presence and required scope without printing values. Use existing secret storage. Check data classification and retention before moving data; never pass raw `<private>` blocks into a model. Prefer sanitized or synthetic cases approved for the target environment.
+4. Implement the narrow adapter using native repository patterns. Validate external inputs and model outputs, bound timeouts and retries, preserve error context without leaking payloads, and handle cancellation. For writes, establish idempotency or duplicate detection before retries; for events, check ordering, replay, and poison messages as applicable.
+5. Exercise a permitted success case and relevant failures: denied access, malformed data, rate limit, timeout, duplicate delivery, or partial completion. Trace correlation IDs or safe evidence across both sides. A mock proves client behavior only; if live access is unavailable, report that gap instead of claiming an integration works.
+6. Check cleanup and recovery for test side effects. Use [verification](verification.md) for receipts and [review](review.md) for security or data-contract changes. Route deployment through [ship](ship.md) only when authorized.
+
+## Deliverable and acceptance
+
+Return the boundary contract, changed paths, environment, evidence at each tested layer, and remaining dependencies with owners when known. Done requires the agreed end-to-end result or an explicit narrower agreed scope. Do not silently replace live acceptance with a stub. In engagement mode, update the terrain/delivery record with confirmed facts; otherwise return the receipt directly.

package/skills/fde-poc/references/plan.md

@@ -0,0 +1,167 @@
+# plan - Sequence the work
+
+**Context:** apply [task context and evidence](task-context.md). Standalone planning evaluates supplied facts directly; it does not require initialized engagement records.
+
+**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 poc produced one. Not the full folder.
+
+**On an initialized engagement, before a new delivery plan or material scope change:** run `fde doctor --ready`. For standalone planning, check the supplied outcome, scope, acceptance and authority directly; do not initialize records to run this validator. Missing binary success or a named customer-side signer blocks progression: review the proposed acceptance check and authority with the FDE first. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint. Routine reversible fixes within confirmed scope reuse the existing signer, acceptance criteria, and engineering plan; record verification without reopening settled decisions.
+
+## Validation gate (confirm understanding, clarify where it elevates)
+
+Before planning, state what you're working from in 2-3 lines:
+
+> "Planning against: [success definition from success.md]. Scope boundary: [out-of-scope items]. Reality check: [brief aligns with reality.md / or note the delta]."
+
+Then check - probe ONLY if it prevents a bad plan:
+
+1. **Success is measurable.** If "done" is vague ("make it better") → rephrase it: "I'm reading success as: [specific measurable outcome]. That the target?"
+2. **Reality matches the brief.** If discovery contradicted the brief → name it: "Discovery found [X] but the brief says [Y]. Planning against reality unless you say otherwise."
+3. **Out-of-scope exists.** If missing → one line: "Nothing's marked out-of-scope yet. That means every new request is implicitly in. Worth defining now or after the first plan draft?"
+
+State your read, let the FDE correct, then plan.
+
+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`, `assumptions.md`, and the **Question** on `reality.md`. Make the boundary explicit using the supplied request; ask if an ambiguity changes the commitment. Investigate a critical open assumption before planning work that depends on it. If the problem itself is unclear, use discovery for that gap; absent filenames do not block a plan supported by supplied facts.
+
+**Reuse check.** Before sequencing a build, compare the requested solution with the smallest existing capability or operating change that could satisfy the same acceptance test. Cite the relevant repo/config/workaround evidence. Record why reuse is sufficient or insufficient in `decisions.md`; include “no new code” when supported. A request for AI does not establish that a model is needed. If a host engineering pack already has an approved implementation plan, reference it from `decisions.md`; do not generate a parallel user-story backlog.
+
+**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. One user action per change.** Each task delivers something visible and testable ("user submits form, sees it saved"), never a layer ("build the database layer"). See `ship`.
+
+**4. Size to a coherent, verifiable outcome.** Split unrelated work and tasks too complex to review or recover safely. Use bounded review sections for large cohesive changes; elapsed time and line count are signals to examine, not universal limits.
+
+**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.
+
+**7. End with a kill list.** Every plan names what you will **not** do this phase. If everything is "later," you have no plan - you have a wish list. Cap **Now** at 3 PRs (same discipline as pick-three).
+
+**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.
+
+A plan is **not done** until all four blocks exist:
+
+```markdown
+## Plan - <date>
+### Now (max 3)
+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>
+Kill if: <the observation that voids this slice - copy from assumptions.md How we test, or the check that means stop>
+Verify: <specific check>
+Value promised: <business unit change this slice claims>
+Baseline: <value + source/date/window/environment, or pending + measurement owner>
+Acceptance owner: <name + authority source, or unknown - ask: who can accept?>
+Evidence to collect: <before/after check, sample/window, environment, and receipt location>
+Reuse: <existing capability used, or evidence it cannot satisfy the criteria>
+
+### Next
+- ...
+
+### Later
+- ...
+
+### Kill list (explicitly not this phase)
+| Item | Why killed / deferred | Who accepted |
+|------|----------------------|--------------|
+| <rewrite / nice-to-have / political ask> | <evidence> | <name, date> |
+```
+
+In `Who accepted`, distinguish a proposed deferral from an agreement: use `pending` until a named person accepted this scope with a dated source. Sponsorship alone is not approval of every plan detail.
+
+No kill list → not a finished plan. Reopen with the FDE until the deferrals are written.
+## Checkpoint
+
+Walk the FDE through: sequence + why this order, where the fragile work sits, where the touchpoints land, the acceptance gate and **Kill if** on task 1, and the kill list. One question: "Which stakeholder sees the first visible slice, and when?" Second: "Who accepted what we are not doing?" Third: "What observation stops task 1 this week?"
+
+## 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."
+- Each named assumption needs a **kill observation**: the result that voids the estimate. Copy it from `assumptions.md` → How we test. No kill observation = it is not an assumption, it is hope.
+- 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.
+
+## Worked example
+
+Acme, after discover: the reconciliation job is unowned, Marco's spreadsheet is the real fallback.
+
+**Now** is three tasks, not eight. Task 1 is *failures reach a named human* - delivers a page to a rota, accepts "kill the job mid-run → the on-call is paged within 15 min", touches the job wrapper and the alert config, rollback is re-disable the route, **Kill if:** a real failure page is acked by nobody on the rota (the *finance would act* assumption, DISPROVED if Marco is the only name that answers), verify by killing it in staging. Value promised: `risk-mitigation - a silent failure becomes a 15-minute one`.
+
+The kill list in `decisions.md` is where the plan earns its keep: the rewrite of the reconciliation service that Tom keeps proposing goes there - *deferred, the failure mode is ownership not architecture (Priya accepted, Jun 12)* - along with the finance dashboard finance asked for directly. Both stay visible so the same argument is not re-litigated in week 4 without a receipt.
+
+First visible slice goes to Marco, not Priya: he is the one whose morning changes, and his confirmation is what makes the sponsor update true.
+
+## 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.
+- No kill list, no finished plan.
+- No **Kill if** on a Now PR, that PR is hope.
+- Estimates are ranges, not promises. Name the assumptions and the observation that voids them.
+- Migrations: leaf nodes first, core last. Rollback before cutover.