npm - fdeops - Versions diffs - 4.1.1 → 5.1.0 - Mend

fdeops 4.1.1 → 5.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (264) hide show

package/skills/fde/references/discover.md CHANGED Viewed

@@ -1,254 +1,112 @@
-# discover - Frame the problem
+# discover - Find the problem behind the request
-**Enter when:** the brief feels wrong, the real problem is unclear, shadow processes are suspected, or any phase found that the map is missing.
+**Enter when:** the customer brief is unclear, the proposed solution may miss the real problem, or a change has exposed an unmapped part of the work.
-**Read first:** `context.md`, `brief.md`. Load `terrain.md` if it exists - extend it, never regenerate from scratch.
+Apply [task context and evidence](task-context.md) first. Supplied notes are enough to begin. In an existing engagement, use permitted summaries of `context.md`, `brief.md`, `reality.md` and relevant `terrain.md` sections; extend existing findings instead of restarting.
-## Validation gate (confirm understanding, clarify where it elevates)
+## Choose the depth the task needs
-Before discovering, state what you're investigating and why in 2-3 lines:
+- **Notes or meeting preparation:** return the current steps, observations, hypotheses and a few questions that would change the next decision. No repository scan, workshop or customer-record setup is required.
+- **A specific delivery problem:** follow the affected people, systems and data far enough to explain the break and identify what evidence is missing.
+- **A wider engagement:** map dependencies and decision owners across the involved teams. Examine each candidate problem before choosing where to invest; do not make a full enterprise inventory a prerequisite for one useful finding.
-> "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]."
+State what you are investigating and which decision it informs. Reuse the user's stated goal. Ask only when a missing answer changes the next action; otherwise proceed with a clearly labelled provisional interpretation.
-Then check - probe ONLY if it prevents wasted discovery:
+## Frame the decision
-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?"
+Write a short frame from the evidence available:
-State your read, let the FDE correct, then discover.
+| Part | What to establish |
+|---|---|
+| Situation | How people complete this task today |
+| Complication | The observed delay, failure, cost or constraint |
+| Question | The decision that further evidence should help someone make |
+| Possible outcomes | Confirm the brief, change its scope, investigate further or pause |
-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?”
+Keep the question specific and neutral. “What causes requests to wait before assignment?” leaves room for different explanations. “How should we automate assignment?” assumes the solution before establishing the cause.
-## Brief interrogation (when the hypothesis is still mush)
+Name the decision owner when known. An unknown owner or unmeasured baseline is a finding, not a reason to keep questioning indefinitely. Return a provisional frame and identify who or what could verify it. Do not present a new interpretation as agreed scope.
-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.
+## Trace the work
-Same format as land - one Q + GUESS, no checklist:
+Follow an ordinary case from arrival to completion, then relevant exceptions. Use the customer's terms for the request, system and people involved.
-```
-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>
-```
+For each step, establish:
-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.
+- Who performs it and where the input comes from.
+- What they do, check or decide, and which system they update.
+- Time spent working versus time spent waiting.
+- What happens when information is missing or the normal path fails.
+- Who notices the failure, how they recover, and which record they trust.
-## Frame the decision first
+Distinguish measured timings from estimates. A team lead's recollection is useful evidence about their experience; it is not a measured baseline. Do not infer that the slowest visible step causes the whole delay without following its dependencies.
-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.
+Use concrete questions when the supplied material leaves a gap: “Show me the last request that waited a day. What had to happen before someone could take it?” Ask about spreadsheets, manual transfers or other workarounds when there is evidence of them, without assuming they exist.
-| 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" |
+When a workaround looks surprising, use the targeted history check in [audit](audit.md#before-changing-an-unfamiliar-workaround). History supplies clues, not proof that an old requirement still applies.
-Tests on **Question** - rewrite until all five hold:
+## Inspect systems when relevant and permitted
-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.
+If the question depends on application behavior and code access is authorized, use `fde scan` and targeted file reads. If the CLI is unavailable, use the repository's existing search, Git and test tools. Do not load the whole repository or unrelated customer data.
-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.
+Follow the actual path: entry point → validation → processing → storage or downstream action. Inspect the code, configuration and tests that can explain the observed discrepancy.
-## Parts of the problem (decompose only)
+Check existing capability before proposing new work. A disabled feature, frequent edits or a missing nearby test is a lead to investigate, not proof of a root cause. Record the evidence behind any technical risk. When there is no repository access, state that implementation behavior remains unchecked and finish the work possible from the notes.
-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.
+## Check the data and dependencies the proposed work needs
-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.
+For each relevant source, establish where it lives, how fresh it is, who controls access, which fields the task needs, and what happens when it is unavailable. Inspect a permitted sample appropriate to the question; report its size and limitations rather than treating a small sample as representative by default.
-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.
+| Source or connection | Needed for | Freshness and quality evidence | Access owner | Failure or constraint | Next check |
+|---|---|---|---|---|---|
+| Fill only relevant sources | | | Unknown if unconfirmed | | |
-Do not mark pieces as facts or assumptions here. That is `test-assumptions`. Do not assemble options here. That is `three-options`.
+Check mappings between systems, supported APIs, permissions and retry behavior where they affect feasibility. A promised export or integration is not yet an available dependency. Record its responsible owner, verification date and required evidence when known; propose missing commitments for confirmation.
-## Method - part 1: the codebase (you do this work)
+For AI work, identify which steps can use deterministic logic, which need model judgment, and which require a human decision. Keep that allocation provisional until the affected owners agree. Establish who would operate the resulting change and what access or training they would need.
-**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.
+## Use a workshop only when it resolves a real disagreement
-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.
+A short meeting with the relevant decision makers may help when teams describe different problems or constraints. Bring the observed cases and the decision to be made. Ask participants to state their constraints before discussing options.
-**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
-```
+Summarize areas of agreement and disagreement. A vote or an absence of objections does not establish authority or acceptance. Ask the responsible owner to confirm the decision and record any unresolved objection, next action and date. Draft the summary promptly, then follow the record-confirmation rules before saving it.
-**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."
+## Return a useful discovery result
-**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.
+Use the smallest output that answers the user's request:
-**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."
+1. The current task and the decision under investigation.
+2. What the evidence establishes, with its source.
+3. The working explanation and plausible alternatives.
+4. Relevant exceptions, dependencies or technical risks actually observed.
+5. Missing evidence and the next check that would change the decision.
-**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).
+Do not fill a quota of risks, exceptions or questions. If no system was inspected, do not invent code findings. If several interpretations have failed, reassess the evidence and investigation method rather than blaming the person who wrote the brief.
-**6. Data flow.** Where data enters, how it moves, where it stops. Entry points first: routes, queues, cron, file drops.
+For a bound engagement, propose updates to the existing records after the discovery result is reviewed:
-**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.
+- `reality.md`: preserve `Working theory`, `Evidence` and `Differs from brief how`; add the decision frame and validation status.
+- `terrain.md`: relevant steps, system behavior, data dependencies and unknowns. Preserve the `## Operating map (exception-led)` section and its columns when recording observed breaks.
+- `assumptions.md`: new or changed assumptions, verification owners and checkpoints.
-## Method - part 2: the humans (you coach, the FDE asks)
+An operating-map row uses: `Exception / break | Who notices first | What they do today | System of record then | Blast | Evidence`. Preserve the existing schema. If no break has been observed, report that gap; do not fabricate a row to satisfy a readiness check.
-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.
+For standalone work, return the same findings in the conversation or requested document. No `.fde/` write or initialization is needed.
 ## Worked example
-Acme's brief blamed missing monitoring. Discovery goes to the workaround first.
+This example is fictional and uses only supplied meeting notes.
-`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.
+The brief asks for an assistant to draft responses. The supplied notes say drafting takes about four minutes, while requests sometimes wait a day for assignment. The timings come from a team lead; no measured baseline is available.
-`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)`.
+**Working theory:** assignment delay may matter more than drafting time. **Evidence:** the lead's estimates in the supplied notes, still unverified. **Differs from brief how:** the requested assistant addresses drafting, while the reported delay concerns assignment. **Question:** what causes the assignment delay, and which change would reduce it? **Next check:** trace a sample of recent requests using arrival and assignment timestamps, then ask the people handling delayed cases what prevented assignment.
-Checkpoint to the FDE leads with that Question, not a tour of the repo.
+The discovery result does not reject the assistant or declare an ownership problem solved. It gives the FDE a focused way to find out what to build, change or investigate next. Return this as a short draft for notes-only work; in a bound engagement, propose it for `reality.md` with validation still pending.
 ## 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.
+- Investigate the work before choosing a solution.
+- Keep observations, estimates and hypotheses distinct.
+- Match discovery effort to the decision at hand.
+- Unknown ownership and missing evidence remain explicit.
+- Confirmation comes from the responsible person, never from silence.

package/skills/fde/references/ingest.md CHANGED Viewed

@@ -2,7 +2,9 @@
 **Enter when:** the FDE wants to catch the engagement up from external sources - "make sure Acme is up to date," "pull what's relevant," "grab today's Granola and Denise's last email." Raw transcripts and long emails that are too big to paste usefully.
-**Connect / capability (different entry):** "connect a new MCP", "connect Granola/Slack/Notion", "what can you pull?" → `references/connect.md` first. Recipes: `mcp/recipes/` (file, granola, slack, notion).
+**Connect / capability (different entry):** "connect a new MCP", "connect Granola/Slack/Notion", "what can you pull?" → `references/connect.md` first. Use [source setup](source-setup.md) for files and supported source tools.
+**Review only:** requested source reads and a sourced draft can proceed without a customer record. Use [source setup](source-setup.md) and [debrief](debrief.md). Do not stage or apply anything until the intended customer is selected; do not silently create a record for a review-only request.
 **Read first:** the bounded `fde resume` packet and targeted recall for affected prior facts. Bind the engagement before staging anything.
@@ -60,7 +62,7 @@ Carry an actual `[source: ...]` locator on each consequential fact. Preserve ups
 ## MCP sink + recipes
-Optional `mcp/fdeops-ingest` wraps the same verbs over stdio. Source MCPs remain separate - the FDE adds whichever fetch tools they trust. Setup coach: `connect.md`. Copy-paste recipes: `mcp/recipes/`.
+Optional `mcp/fdeops-ingest` wraps the same verbs over stdio. Source MCPs remain separate - the FDE adds whichever fetch tools they trust. Setup coach: `connect.md`. Portable setup guidance: [source setup](source-setup.md).
 ## Checkpoint

package/skills/fde/references/plan.md CHANGED Viewed

@@ -6,7 +6,7 @@
 **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.
+**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 acceptance criteria or authority blocks the affected implementation commitment, not a provisional plan. Draft proposed checks and next steps, mark them pending, and ask only what changes the next action. 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)
@@ -17,8 +17,8 @@ Before planning, state what you're working from in 2-3 lines:
 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?"
+2. **Reality matches the brief.** If discovery contradicted the brief → name it: "Discovery found [X] but the brief says [Y]. Here is the proposed adjustment; it remains unagreed until confirmed."
+3. **Out-of-scope exists.** If missing → one line: "I will keep this draft within the supplied request and mark proposed exclusions for confirmation."
 State your read, let the FDE correct, then plan.
@@ -42,19 +42,19 @@ An FDE plan is not a sprint backlog. The technical sequence is the easy part. Th
 **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).
+**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. Keep **Now** small enough to review and act on; split by independently verifiable outcomes.
 **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.
+For standalone planning, return the requested draft or save to the authorized project document. In a bound engagement, propose the plan for **`decisions.md`** under its confirmation rules, or link the existing approved plan; do not duplicate it.
 A plan is **not done** until all four blocks exist:
 ```markdown
 ## Plan - <date>
-### Now (max 3)
+### Now
 Task N: <outcome, not activity>
 Delivers: <what someone can see/test>
 Accepts: <happy path> / <unhappy path>