Demo docs consultation

Salesforce Docs Consultation — Decision Tree

The Salesforce Docs MCP (salesforce_docs_search, salesforce_docs_fetch) exposes the official Salesforce documentation over HTTP. Use it when release-accuracy or error diagnosis genuinely moves the needle. Do NOT use it as ambient verification — org audit and skill-library metadata rules remain primary.

When to Consult — YES

1. Industry cloud data model — the SE named an industry cloud (Health Cloud, Life Sciences Cloud, FSC, Manufacturing Cloud, etc.). Always search for that cloud's standard data model, key objects, and recommended patterns in Stage 4. The SE knows which cloud; docs know which objects.
2. Object with platform restrictions — EntityDefinition pre-flight found IsEverCreatable/IsQueryable/IsTriggerable/IsSearchable = false, or the object is not in QueueSobject. Search for practical workarounds so the spec carries actionable guidance (not just boolean flags) into building.
3. Screen-flow component outside Scout's autonomous whitelist — the SE's screen-flow design references a component Scout cannot autonomously deploy (Repeater, Data Table, File Upload/Preview, Kanban Board, custom LWC screen component, reactive cross-screen formulas). Consult docs to confirm the component's current capabilities and decide: (a) scope down to whitelisted components, or (b) route the whole screen flow to the SE Manual Checklist. Never silently swap components.
4. Release-gated feature mentioned by the SE that you cannot immediately name the release for (e.g. "Agent Script subagents", "Data Cloud zero-copy", "Flow HTTP Callout").
5. Novel metadata type you haven't deployed in this session — unfamiliar XML structure, unfamiliar CLI command, unfamiliar agent-bundle element.
6. Unfamiliar deployment error message — the error text isn't in the loaded orgs/lessons/ topics (metadata-deploy.md / managed-packages.md) and isn't obvious from the component name. Consult docs BEFORE the retry attempt.
7. SE-referenced concept by name you don't recognise ("is [term] the right fit here?"). One search, one citation, proceed.
8. Agentforce Agent Script capability check — Agent Script ships features monthly; default to consulting docs for any non-trivial agent spec.
9. Capability classification (the autonomy decision) — any spec'd artifact OUTSIDE Scout's known-authorable skill set (the ~25 generation skills). Consult docs to classify it into one of three build dispositions (see CLAUDE.md §Build Boundaries → Docs-Gated): (1) metadata-authorable WITH a build-time signal → build + loop; (2) metadata-authorable with NO signal → attempt + deploy + hand off "needs visual QA"; (3) genuinely UI-only / no Metadata API path → the only hard decline, skip with the citation. Do NOT decline an artifact as "manual" or "too complex" from memory — that verdict must carry a doc citation. Artifacts a known skill already covers are authorable by definition — no classification call needed. Record the disposition + citation in the spec so building honors it.

When to Consult — NO

1. Custom field / object / permission set XML structure — afv-library skills (platform-custom-field-generate, platform-custom-object-generate, platform-permission-set-generate) are authoritative.
2. Standard object structure — org audit is truth. Docs describe a generic org; the SE's org may have managed-package or admin-made variants.
3. Anything you just consulted this session — cache in your head for the session; don't re-fetch.
4. SE-asserted customer fact — customer context is not in Salesforce docs.
5. Known error message already in a loaded orgs/lessons/ topic — the lesson is the answer.

How to Cite

Every consultation produces a citation. Capture:

• URL from the doc result (the documentPath-resolved link)
• Question asked — one line, so the reader can judge relevance later
• Verdict — what the doc confirmed, contradicted, or left ambiguous

Citations land in:

• Spec: Release Notes & Citations section (sparring)
• Change log: Docs Consulted section (building)
• Sub-agent JSON output: docs_consulted array

Degraded Mode

If salesforce_docs_search fails or times out:

• Do NOT block. Docs MCP is optional; Scout degrades gracefully.
• Record the attempt in citations with verdict: "docs unavailable".
• Flag the uncertainty in the spec as [UNVERIFIED — docs MCP unavailable, SE confirm].
• If Docs is persistently unavailable (not a one-off timeout — e.g. the server shows "needs authentication" or publishes no tools), it likely needs re-wiring: tell the SE to run /scout-setup, which registers it at user scope (bare HTTP, no auth) and self-heals any stale tool-name allowlist entry.

Budget Guidance

• Sparring Stage 4 (Platform & Data Model Research): 3–7 consultations for new scenarios, 1–3 for iterations. This is the primary research step — invest here. More than 7 = too broad; anchor on the SE's #1 pain point.
• Sparring Stage 6 (residual feasibility): 0–2 consultations. Stage 4 should have caught most things — this is a safety net for features that emerged during scenario definition.
• Capability classification (trigger 9): fires only for artifacts outside the known-authorable skill set — typically 0 on a standard build (objects / fields / flows / Apex / reports / list views / validation & sharing rules are all known-authorable), 1–2 on an edge-case build (dashboard, orchestration flow, novel platform surface). It folds into the Stage-4/6 budget above — it is a classification, not a research spree: one search, one verdict, cite it.
• Building: 0 consultations is the happy path. Consultations happen on unfamiliar-error recovery, not as a pre-flight check.
• Phase 3 (Agentforce) is the one building exception — expect 1–2 consultations for any non-trivial agent spec (Agent Script surface changes monthly).