@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/modeling-omnistudio-epc-catalog/references/epc-field-guide.md

@@ -1,90 +0,0 @@
-<!-- Parent: modeling-omnistudio-epc-catalog/SKILL.md -->
-
-# EPC Field Guide (Product2 + Bundles + Attributes)
-
-This quick guide captures the minimum field set for creating CME EPC products and offer bundles in DataPack-style metadata.
-
-## Root Template Files (`assets/`)
-
-The skill root `assets/` directory contains a full template set aligned to the Business Internet Essential (VPL) bundle:
-
-- `product2-offer-template.json`
-- `attribute-assignment-template.json`
-- `product-child-item-template.json`
-- `pricebook-entries-template.json`
-- `price-list-entries-template.json`
-- `object-field-attributes-template.json`
-- `orchestration-scenarios-template.json`
-- `decomposition-relationships-template.json`
-- `compiled-attribute-overrides-template.json`
-- `override-definitions-template.json`
-- `parent-keys-template.json`
-
-## Product2: Minimum Recommended EPC Fields
-
-| Field | Purpose | Example |
-|---|---|---|
-| `Name` | Human-readable catalog name | `Business Internet Essential (VPL)` |
-| `ProductCode` | Stable technical identifier | `VEPC_OFFERING_BUSINESS_INTERNET_ESSENTIAL` |
-| `%vlocity_namespace%__GlobalKey__c` | Cross-environment stable key | UUID-like value |
-| `%vlocity_namespace%__SpecificationType__c` | Product classification | `Offer` |
-| `%vlocity_namespace%__SpecificationSubType__c` | Product subtype | `Bundle` |
-| `%vlocity_namespace%__Status__c` | EPC status | `Active` |
-| `%vlocity_namespace%__IsOrderable__c` | Order eligibility | `true` |
-| `IsActive` | Product availability | `true` |
-| `%vlocity_namespace%__SellingStartDate__c` | Sales lifecycle start | `2021-07-31T04:00:00.000Z` |
-
-## Attribute Metadata Blocks
-
-### `%vlocity_namespace%__AttributeMetadata__c`
-
-Contains category/group metadata and product attribute records:
-
-- category `Code__c`, `Name`, `displaySequence`
-- per-attribute `code`, `label`, `inputType`, `required`, `values[]`
-
-### `%vlocity_namespace%__AttributeDefaultValues__c`
-
-Map from attribute code to default value:
-
-```json
-{
-  "VEPC_ATTR_DOWNLOAD_SPEED": "50 Mbps",
-  "VEPC_ATTR_CONTRACT_TERM": "Month-to-Month"
-}
-```
-
-## Product Bundle Modeling (`%vlocity_namespace%__ProductChildItem__c`)
-
-Offer bundles are composed through child item rows:
-
-- one root row: `IsRootProductChildItem = true`
-- child rows: parent and child references + sequence and quantity settings
-
-Key quantity fields:
-
-- `%vlocity_namespace%__MinQuantity__c`
-- `%vlocity_namespace%__MaxQuantity__c`
-- `%vlocity_namespace%__Quantity__c`
-- `%vlocity_namespace%__MinMaxDefaultQty__c` (e.g., `"0, 1, 1"`)
-
-## Common Field Pitfalls
-
-| Pitfall | Impact | Fix |
-|---|---|---|
-| `ProductCode` reused for multiple products | Cart and quote ambiguity | Enforce unique catalog code |
-| Default attribute value missing from values list | Runtime configuration errors | Keep defaults inside valid value set |
-| Missing root ProductChildItem | Broken offer traversal | Always add root row |
-| Direct org-specific IDs in DataPack | Deploy failures across orgs | Use lookup source keys and global keys |
-
-## Included Example Packs
-
-The skill ships with:
-
-- `assets/` (canonical EPC bundle template set)
-- `assets/examples/samsung-galaxy-s22-bundle/` (bundle offer example)
-- `assets/examples/business-internet-premium-fttc-simple-offer/` (simple offer example)
-- `assets/examples/business-internet-pro-vpl-simple-offer/` (simple offer example)
-- `assets/examples/static-ip-simple-offer/` (simple offer example)
-
-The example folders contain related DataPack-style files, including Product2 payloads, attribute assignments, product child items, and pricing artifacts.

package/skills/modeling-omnistudio-epc-catalog/references/naming-conventions.md

@@ -1,80 +0,0 @@
-<!-- Parent: modeling-omnistudio-epc-catalog/SKILL.md -->
-
-# CME EPC Naming Conventions
-
-Use deterministic naming across products, attributes, and offer bundles. Names should remain stable across environments and releases.
-
-## Product Name
-
-Format:
-
-```text
-<Business Domain> <Tier/Variant> (<Channel or Variant Tag>)
-```
-
-Examples:
-
-- `Business Internet Essential (VPL)`
-- `Business Internet Premium (FTTC)`
-
-## Product Code
-
-Format:
-
-```text
-<PREFIX>_<ENTITY>_<DOMAIN>_<VARIANT>
-```
-
-Examples:
-
-- `VEPC_OFFERING_BUSINESS_INTERNET_ESSENTIAL`
-- `VEPC_SPEC_BUSINESS_ROUTER_ADVANCED`
-
-Rules:
-
-- Uppercase with underscores only
-- No environment suffixes (`_DEV`, `_UAT`, `_PROD`)
-- Stable after go-live
-
-## Attribute Code
-
-Format:
-
-```text
-VEPC_ATTR_<DOMAIN>_<ATTRIBUTE_NAME>
-```
-
-Examples:
-
-- `VEPC_ATTR_DOWNLOAD_SPEED`
-- `VEPC_ATTR_CONTRACT_TERM`
-
-## Attribute Category Code
-
-Format:
-
-```text
-VEPC_ATTRIBUTE_CATEGORY_<DOMAIN_BLOCK>
-```
-
-Examples:
-
-- `VEPC_ATTRIBUTE_CATEGORY_INTERNET_DETAILS`
-- `VEPC_ATTRIBUTE_CATEGORY_CONTRACT_DETAILS`
-
-## Offer Bundle Composition
-
-When naming bundles and child items:
-
-- Bundle parent `ProductCode` should indicate offering intent (`VEPC_OFFERING_*`)
-- Child product codes should represent reusable specs (`VEPC_SPEC_*` recommended)
-- Sequence values (`SeqNumber`, `ChildLineNumber`) should be unique per parent and spaced for future inserts
-
-## Anti-Patterns
-
-| Bad pattern | Why to avoid |
-|---|---|
-| `Product1`, `Offer_New`, `CatalogItemA` | Non-descriptive and unstable |
-| Mixed abbreviations without glossary | Hard to maintain and search |
-| Date/version in `ProductCode` | Breaks long-term references |
-| Same `ProductCode` in multiple products | Downstream ambiguity |

package/skills/modeling-omnistudio-epc-catalog/references/scoring-model.md

@@ -1,57 +0,0 @@
-# EPC Bundle Scoring Model (120 Points)
-
-Use this rubric when scoring or reviewing an existing EPC offer bundle. Score each category and sum for a total out of 120.
-
-**Thresholds**: `>= 95` Deploy-ready | `70–94` Needs review | `< 70` Block and fix.
-
----
-
-## 1) Catalog Identity and Naming (20 points)
-
-- Product name is clear, unique, and follows naming conventions
-- `ProductCode` follows the deterministic convention (no environment suffixes)
-- `SpecificationType`, `SpecificationSubType`, and `Family` values are coherent
-- Stable keying: `GlobalKey` is a UUID-style value; source key is consistent across files
-
----
-
-## 2) EPC Product Structure (20 points)
-
-- All required `Product2` and EPC fields are present and populated
-- Lifecycle dates (`EffectiveDate`, `SellingStartDate`) are set and logically ordered
-- `IsActive` and `%vlocity_namespace%__IsOrderable__c` flags are coherent with lifecycle status
-- Record type and catalog classification are consistent
-
----
-
-## 3) Attribute Modeling (25 points)
-
-- Attributes are logically grouped by category
-- Every attribute default exists within its `values[]` array
-- Required, read-only, and filterable semantics are correctly set
-- Display sequences are unique within each category and use spaced values (10, 20, 30…)
-
----
-
-## 4) Offer Bundle Composition (25 points)
-
-- Root `%vlocity_namespace%__ProductChildItem__c` row is present with `IsRootProductChildItem=true`
-- All child product references are valid and their sequence/line numbers are unique
-- `MinQuantity`, `MaxQuantity`, and default `Quantity` constraints are set correctly per child
-- Optional vs required semantics are reflected accurately in min/max/default values
-
----
-
-## 5) DataPack Integrity (15 points)
-
-- All namespace placeholders (`%vlocity_namespace%`) are consistent across every file in the bundle
-- Lookup object references use GlobalKey / source key (no hardcoded org-specific IDs)
-- No environment-specific brittle fields (no `_DEV`, `_UAT`, `_PROD` suffixes in ProductCode or keys)
-
----
-
-## 6) Documentation and Handoff (15 points)
-
-- Clear explanation of the modeled intent is included in the handoff block
-- Testing checklist is present (see `scripts/cli-validation-commands.sh`)
-- Risks and assumptions are explicitly called out in the completion block

package/skills/modeling-omnistudio-epc-catalog/scripts/cli-validation-commands.sh

@@ -1,19 +0,0 @@
-#!/usr/bin/env bash
-# CLI commands for querying and validating EPC artifacts in a Salesforce org.
-# Usage: replace <org> with your authenticated org alias.
-
-# Query candidate EPC products
-sf data query \
-  -q "SELECT Id,Name,ProductCode,Family,IsActive FROM Product2 ORDER BY LastModifiedDate DESC" \
-  -o <org>
-
-# Query Product Child Items for an offer
-sf data query \
-  -q "SELECT Id,Name,%vlocity_namespace%__ParentProductName__c,%vlocity_namespace%__ChildProductName__c,%vlocity_namespace%__MinMaxDefaultQty__c FROM %vlocity_namespace%__ProductChildItem__c WHERE %vlocity_namespace%__ParentProductName__c='<Offer Name>'" \
-  -o <org>
-
-# Retrieve Product2 metadata package members
-sf project retrieve start -m Product2:<DeveloperNameOrName> -o <org>
-
-# Validate deployment in dry-run mode
-sf project deploy start -x manifest/package.xml --dry-run -o <org>

package/skills/modeling-omnistudio-epc-catalog/scripts/sample-invocations.sh

@@ -1,18 +0,0 @@
-#!/usr/bin/env bash
-# Sample skill invocation commands for common EPC modeling tasks.
-# Replace `cursor-agent` with your local agent command wrapper if different.
-
-# Create a new EPC offer bundle with full companion metadata
-cursor-agent "Create a Product2 offer bundle named Business Internet Plus with ProductCode BIZ-INT-PLUS-01, 3 child products, and generate all companion DataPack JSON files from the assets templates."
-
-# Add configurable attributes to an existing EPC Product2 record
-cursor-agent "Update Product2 Business Internet Essential with attribute metadata/defaults/assignments for Bandwidth, ContractTerm, and StaticIPCount, including valid values and defaults."
-
-# Build ProductChildItem relationships for an offer
-cursor-agent "Create root and child %vlocity_namespace%__ProductChildItem__c records for offer Business Internet Essential VPL with min/max/default quantity rules."
-
-# Review an existing DataPack for EPC modeling quality
-cursor-agent "Review the Product2 bundle JSON files under examples/business-internet-plus-bundle/, score against the 120-point rubric, and return risks plus required fixes."
-
-# Convert a spec product into a bundle-ready offer payload
-cursor-agent "Transform Product2 Dedicated Fiber 1G from spec product to offer bundle (SpecificationType=Offer, SpecificationSubType=Bundle) and generate aligned PCI + pricing artifacts."

package/skills/observing-agentforce/SKILL.md

@@ -1,366 +0,0 @@
----
-name: observing-agentforce
-description: "Analyze production Agentforce agent behavior using session traces and Data Cloud. TRIGGER when: user queries STDM session data or Data Cloud trace records; investigates production agent failures, regressions, or performance issues; asks about session traces, conversation logs, or agent metrics; wants to reproduce a reported production issue in preview; runs findSessions or trace analysis queries. DO NOT TRIGGER when: user creates, modifies, or debugs .agent files during development (use developing-agentforce); writes or runs test specs (use testing-agentforce); uses sf agent preview for local development iteration; deploys or publishes agents."
-allowed-tools: Bash Read Write Edit Glob Grep
-metadata:
-  version: "1.0"
-  argument-hint: "<org-alias> [--agent-file <path>] [--session-id <id>] [--days <n>]"
-  compatibility: claude-code
----
-
-
-# Agentforce Observability
-
-Improve Agentforce agents using session trace data and live preview testing.
-
-**Three-phase workflow:**
-- **Observe** -- Query STDM sessions from Data Cloud (if available), OR run test suites + preview with local traces as fallback
-- **Reproduce** -- Use `sf agent preview` to simulate problematic conversations live
-- **Improve** -- Edit the `.agent` file directly, validate, publish, verify
-
----
-
-## Platform Notes
-
-- Shell examples below use bash syntax. On Windows, use PowerShell equivalents or Git Bash.
-- Replace `python3` with `python` on Windows.
-- Replace `/tmp/` with `$env:TEMP\` (PowerShell) or `%TEMP%\` (cmd).
-- Replace `jq` with `python -c "import json,sys; ..."` if jq is not installed.
-
----
-
-## Routing
-
-Gather these inputs before starting:
-
-- **Org alias** (required)
-- **Agent API name** (required for preview and deploy; ask if not provided)
-- **Agent file path** (optional) -- path to the `.agent` file, typically `force-app/main/default/aiAuthoringBundles/<AgentName>/<AgentName>.agent`. Auto-detect if not provided.
-- **Session IDs** (optional) -- analyze specific sessions; if absent, query last 7 days
-- **Days to look back** (optional, default 7)
-
-Determine intent from user input:
-
-- **No specific action** -> run all three phases: Observe -> surface issues -> ask if user wants to Reproduce and/or Improve
-- **"analyze" / "sessions" / "what's wrong"** -> Phase 1 only, then suggest next steps
-- **"reproduce" / "test" / "preview"** -> Phase 2 (run Phase 1 first if no issues in hand)
-- **"fix" / "improve" / "update"** -> Phase 3 (run Phase 1 first if no issues in hand)
-
-### Resolve agent name
-
-Before any STDM query, resolve the user-provided agent name against the org to get the exact `MasterLabel` and `DeveloperName`:
-
-```bash
-sf data query --json \
-  --query "SELECT Id, MasterLabel, DeveloperName FROM GenAiPlannerDefinition WHERE MasterLabel LIKE '%<user-provided-name>%' OR DeveloperName LIKE '%<user-provided-name>%'" \
-  -o <org>
-```
-
-- `MasterLabel` = display name used by STDM `findSessions` and Agent Builder UI (e.g. "Order Service")
-- `DeveloperName` = API name with version suffix used in metadata (e.g. "OrderService_v9")
-- The `--api-name` flag for `sf agent preview/activate/publish` uses `DeveloperName` **without** the `_vN` suffix (e.g. "OrderService")
-
-Store these values:
-- `AGENT_MASTER_LABEL` -- for `findSessions()` agent filter
-- `AGENT_API_NAME` -- `DeveloperName` without `_vN` suffix, for `sf agent` CLI commands
-- `PLANNER_ID` -- the Salesforce record ID for this agent
-
-### Locate the .agent file
-
-**Step 1 -- Search locally:**
-
-```bash
-find <project-root>/force-app/main/default/aiAuthoringBundles -name "*.agent" 2>/dev/null
-```
-
-If the user provided an agent file path, use that directly. Otherwise, search for files matching `AGENT_API_NAME`.
-
-**Step 2 -- If not found locally, retrieve from the org:**
-
-```bash
-sf project retrieve start --json --metadata "AiAuthoringBundle:<AGENT_API_NAME>" -o <org>
-```
-
-> **Known bug:** `sf project retrieve start` creates a double-nested path: `force-app/main/default/main/default/aiAuthoringBundles/...`. Fix it immediately after retrieve:
-
-```bash
-if [ -d "force-app/main/default/main/default/aiAuthoringBundles" ]; then
-  mkdir -p force-app/main/default/aiAuthoringBundles
-  cp -r force-app/main/default/main/default/aiAuthoringBundles/* \
-    force-app/main/default/aiAuthoringBundles/
-  rm -rf force-app/main/default/main
-fi
-```
-
-**Step 3 -- Validate the retrieved file:**
-
-Read the `.agent` file and verify it has proper Agent Script structure:
-- `system:` block with `instructions:`
-- `config:` block with `developer_name:`
-- `start_agent` or `subagent` blocks with `reasoning: instructions:`
-- Each subagent should have distinct `instructions:` content (not identical across subagents)
-
-Store the resolved path as `AGENT_FILE` for Phase 3.
-
----
-
-## Phase 0: Discover Data Space
-
-Before running any STDM query, determine the correct Data Cloud Data Space API name.
-
-```bash
-sf api request rest "/services/data/v63.0/ssot/data-spaces" -o <org>
-```
-
-Note: `sf api request rest` is a beta command -- do not add `--json` (that flag is unsupported and causes an error).
-
-The response shape is:
-```json
-{
-  "dataSpaces": [
-    {
-      "id": "0vhKh000000g3DjIAI",
-      "label": "default",
-      "name": "default",
-      "status": "Active",
-      "description": "Your org's default data space."
-    }
-  ],
-  "totalSize": 1
-}
-```
-
-The `name` field is the API name to pass to `AgentforceOptimizeService`.
-
-**Decision logic:**
-- If the command fails (e.g. 404 or permission error), fall back to `'default'` and note it as an assumption.
-- Filter to only `status: "Active"` entries.
-- If exactly one active Data Space exists, use it automatically and confirm to the user: "Using Data Space: `<name>`".
-- If multiple active Data Spaces exist, show the list (label + name) and ask the user which to use.
-
-Store the selected `name` value as `DATA_SPACE` for all subsequent steps.
-
-### Prerequisite check: STDM DMOs
-
-After deploying the helper class (step 1.0), run a quick probe to verify the STDM Data Model Objects exist in Data Cloud:
-
-```bash
-sf apex run -o <org> -f /dev/stdin << 'APEX'
-ConnectApi.CdpQueryInput qi = new ConnectApi.CdpQueryInput();
-qi.sql = 'SELECT ssot__Id__c FROM "ssot__AiAgentSession__dlm" LIMIT 1';
-try {
-    ConnectApi.CdpQueryOutputV2 out = ConnectApi.CdpQuery.queryAnsiSqlV2(qi, '<DATA_SPACE>');
-    System.debug('STDM_CHECK:OK rows=' + (out.data != null ? out.data.size() : 0));
-} catch (Exception e) {
-    System.debug('STDM_CHECK:FAIL ' + e.getMessage());
-}
-APEX
-```
-
-**If `STDM_CHECK:FAIL`:** STDM is not activated. Inform the user and switch to **Phase 1-ALT**:
-
-> STDM (Session Trace Data Model) is not available in this org. To enable: Setup -> Data Cloud -> Data Streams and verify "Agentforce Activity" is active. **Proceeding with fallback: test suites + local traces.**
-
-**If `STDM_CHECK:OK`**, proceed to Phase 1 (STDM path).
-
----
-
-## Phase 1-ALT: Observe Without STDM (Fallback Path)
-
-When STDM is not available, use test suites and `sf agent preview --authoring-bundle` with local trace analysis.
-
-| Data source | When to use | Pros | Cons |
-|---|---|---|---|
-| STDM (Phase 1) | Historical production analysis | Real user data, volume | Requires Data Cloud, 15-min lag |
-| Test suites + local traces (Phase 1-ALT) | Dev iteration, orgs without STDM | Instant, full LLM prompt, variable state | Preview only, no real user data |
-
-### 1-ALT.1 Run existing test suite (if available)
-
-```bash
-sf agent test list --json -o <org>
-sf agent test run --json --api-name <TestSuiteName> --wait 10 --result-format json -o <org> | tee /tmp/test_run.json
-JOB_ID=$(python3 -c "import json; print(json.load(open('/tmp/test_run.json'))['result']['runId'])")
-sf agent test results --json --job-id "$JOB_ID" --result-format json -o <org>
-```
-
-### 1-ALT.2 Derive test utterances from .agent file (if no test suite)
-
-If no test suite exists, derive utterances: one per non-entry subagent (from `description:` keywords), one per key action, one guardrail test, one multi-turn test.
-
-### 1-ALT.3 Preview with `--authoring-bundle` (local traces)
-
-Run each test utterance through preview to generate local trace files:
-
-```bash
-sf agent preview start --json --authoring-bundle <BundleName> -o <org> | tee /tmp/preview_start.json
-SESSION_ID=$(python3 -c "import json; print(json.load(open('/tmp/preview_start.json'))['result']['sessionId'])")
-
-sf agent preview send --json --session-id "$SESSION_ID" --authoring-bundle <BundleName> \
-  --utterance "$UTT" -o <org> | tee /tmp/preview_response.json
-
-sf agent preview end --json --session-id "$SESSION_ID" --authoring-bundle <BundleName> -o <org>
-```
-
-**Trace file location:** `.sfdx/agents/{BundleName}/sessions/{sessionId}/traces/{planId}.json`
-
-### 1-ALT.4 Local trace diagnosis
-
-| Issue type | Trace command |
-|---|---|
-| Subagent misroute | `jq -r '.plan[] \| select(.type=="NodeEntryStateStep") \| .data.agent_name' "$TRACE"` |
-| Action not called | `jq -r '.plan[] \| select(.type=="EnabledToolsStep") \| .data.enabled_tools[]' "$TRACE"` |
-| LOW adherence | `jq -r '.plan[] \| select(.type=="ReasoningStep") \| {category, reason}' "$TRACE"` |
-| Variable capture fail | `jq -r '.plan[] \| select(.type=="VariableUpdateStep") \| .data.variable_updates[]' "$TRACE"` |
-| Vague instructions | `jq -r '.plan[] \| select(.type=="LLMStep") \| .data.messages_sent[0].content' "$TRACE"` |
-
-**DefaultTopic trace quirk:** With `--authoring-bundle`, the root `.topic` field often shows `"DefaultTopic"` even when routing works. Always use `NodeEntryStateStep.data.agent_name` for the real subagent chain.
-
-**Entry answering directly (SMALL_TALK pattern):** If `start_agent` trace shows `SMALL_TALK` grounding and transition tools visible but none invoked, add "You are a router only. Do NOT answer questions directly." to `start_agent` instructions.
-
-### 1-ALT.5 Classify and present
-
-Classify issues using the categories in `references/issue-classification.md`. After presenting findings, automatically proceed to agent config evidence analysis.
-
----
-
-## Phase 1: Observe -- Query STDM
-
-> Full STDM query details, Apex service deployment, and response parsing: see `references/stdm-queries.md`
-
-### 1.0 Deploy helper class (once per org)
-
-Deploy `AgentforceOptimizeService` Apex class to the org. Check if already deployed first:
-
-```bash
-sf data query --json --query "SELECT Id, Name FROM ApexClass WHERE Name = 'AgentforceOptimizeService'" -o <org>
-```
-
-If not deployed, copy from skill directory and deploy. See `references/stdm-queries.md` for full steps.
-
-### 1.1 Find sessions
-
-Query recent sessions using `findSessions()`. Parse `DEBUG|STDM_RESULT:` from the Apex debug log. If `findSessions` returns empty, switch to Phase 1-ALT.
-
-### 1.2 Get conversation details
-
-Use `getMultipleConversationDetails()` for up to 5 sessions (most recent first). Returns turn-by-turn data with messages, steps, topics, and action results.
-
-### 1.2b Get LLM prompt/response (optional)
-
-When LOW adherence detected, use `getLlmStepDetails()` to get the actual LLM prompt and response.
-
-### 1.2c Get aggregated metrics (recommended first step)
-
-Use `getAggregatedMetrics()` for high-level health dashboard: session rates, top intents, quality distribution, RAG averages.
-
-### 1.2d Get moment insights (per-session detail)
-
-Use `getMomentInsights()` for intent summaries, quality scores (1-5), and retriever metrics per session.
-
-### 1.2e Run observability queries (RAG deep-dive)
-
-Use `runObservabilityQuery()` for targeted RAG analysis: KnowledgeGap, Hallucination, RetrievalQuality, AnswerRelevancy, Leaderboard.
-
-### 1.3 Reconstruct conversations
-
-Render turn-by-turn timeline from `ConversationData` JSON for each session.
-
-### 1.4 Identify issues
-
-> Full issue pattern table and classification categories: see `references/issue-classification.md`
-
-Check each session for: action errors, subagent misroutes, missing actions, wrong inputs, variable capture failures, no transitions, slow actions, LOW adherence, abandoned sessions, dead subagents, publish drift, dead hub anti-pattern, entry answering directly, and safety issues.
-
-Priority: P1 = action errors, misroutes, LOW adherence; P2 = missing actions, variable bugs, knowledge gaps; P3 = performance, abandoned sessions.
-
-### 1.5 Present findings and agent config evidence
-
-Present sessions analyzed, issues grouped by root cause category, and uplift estimate. Then automatically proceed to analyze the `.agent` file to confirm root causes.
-
-> Full structural analysis checks, cross-reference procedures, and publish drift detection: see `references/issue-classification.md`
-
-Retrieve the `.agent` file from the org, run automated checks (subagent count vs action blocks, dead hub detection, orphan actions, cross-subagent variable dependencies), and cross-reference STDM symptoms against the file structure.
-
----
-
-## Phase 2: Reproduce -- Live Preview
-
-> Full preview procedures, trace diagnosis commands, and classification criteria: see `references/reproduce-reference.md`
-
-Build one test scenario per confirmed issue from Phase 1. Run each through `sf agent preview` with `--authoring-bundle` (generates local traces). Run each scenario **3 times** and classify:
-
-| Verdict | Criteria |
-|---|---|
-| `[CONFIRMED]` | Same failure in 3/3 runs |
-| `[INTERMITTENT]` | Failure in 1-2 of 3 runs |
-| `[NOT REPRODUCED]` | Passes in 3/3 runs |
-
-Only `[CONFIRMED]` and `[INTERMITTENT]` issues proceed to Phase 3.
-
-**Key commands:**
-
-```bash
-sf agent preview start --json --authoring-bundle <Name> -o <org>
-sf agent preview send --json --session-id "$SID" --utterance "<text>" --authoring-bundle <Name> -o <org>
-sf agent preview end --json --session-id "$SID" --authoring-bundle <Name> -o <org>
-```
-
-**Trace location:** `.sfdx/agents/{Name}/sessions/{sessionId}/traces/{planId}.json`
-
----
-
-## Phase 3: Improve -- Edit .agent File Directly
-
-> Full procedures for pre-flight checks, fix mapping, instruction principles, regression prevention, deployment chain, verification, safety re-verification, and test case creation: see `references/improve-reference.md`
-
-### 3.0 Pre-flight
-
-Verify all action targets exist and are registered in the org before editing. If targets are missing, present options: deploy stubs, remove actions, register via UI, or proceed with routing-only fixes.
-
-### 3.1-3.3 Map issue, edit, and follow instruction principles
-
-Map each confirmed issue to a fix location in the `.agent` file (description, instructions, actions, bindings, transitions). Use the Edit tool for targeted changes. Follow instruction principles: name actions explicitly, state pre-conditions, scope tightly, keep persona in `system:` only.
-
-### 3.4 Regression prevention
-
-Establish baseline before editing. Make minimal edits. Test immediately after each edit. One fix per publish cycle. Check cross-subagent dependencies. Test adjacent subagents.
-
-### 3.5 Apply fixes
-
-Read the `.agent` file, edit with the Edit tool (tabs for indentation), show the diff.
-
-### 3.6 Validate, deploy, publish, activate
-
-```bash
-# Validate (dry run)
-sf agent validate authoring-bundle --json --api-name <AGENT_API_NAME> -o <org>
-
-# Publish (compile + deploy + activate)
-sf agent publish authoring-bundle --json --api-name <AGENT_API_NAME> -o <org>
-```
-
-If publish fails, use deploy + activate fallback (note: incomplete -- does not propagate `reasoning: actions:` to live metadata).
-
-### 3.7 Verify
-
-Run Phase 2 scenarios post-fix. Check trace for correct routing, grounding, tools, and variables. After 24-48 hours, re-run Phase 1 to compare against baseline.
-
-### 3.7b Safety re-verification (required)
-
-Re-run safety review (`Section 15 of /developing-agentforce`) on the modified `.agent` file. Revert any changes that introduce BLOCK findings.
-
-### 3.8 Update Testing Center test cases
-
-Create regression test cases from confirmed issues in Testing Center YAML format. Deploy with `sf agent test create` and verify all previously-broken scenarios pass.
-
----
-
-## Reference Files
-
-| Reference | Contents |
-|---|---|
-| `references/stdm-queries.md` | STDM query procedures, Apex service deployment, response parsing |
-| `references/issue-classification.md` | Issue pattern table, root cause categories, structural analysis checks |
-| `references/reproduce-reference.md` | Phase 2 preview procedures, trace diagnosis, classification criteria |
-| `references/improve-reference.md` | Phase 3 editing, deployment chain, verification, safety, test cases |
-| `references/stdm-schema.md` | DMO field schemas, data hierarchy, quality notes, agent name resolution |