@salesforce/afv-skills 1.51.0 → 1.52.0

package/skills/field-service-objective-designer-configure/SKILL.md

@@ -6,23 +6,34 @@ owning_team: sfs-setup-experience
 metadata:
   version: "1.0"
   domains: ["Field Service"]
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
 ---
 
+# Managing Sfs Service Objective Designer
+
+## When to Use This Skill
+
+Designs service objectives for a Salesforce Field Service scheduling policy via a structured trade-off interview. Guides the user through objective selection and derives weights by establishing crossover equivalences against Minimize Travel (the anchor). Produces a finalized weight table with penalty-rate interpretation and a plain-English policy summary. Called after work rule design; delegates to sfs-sobject-create for record creation.
+
+## Workflow
+
 # Salesforce Field Service – Service Objective Designer
 
-**Designs the service objectives for a scheduling policy.** Collects objective selection and derives each weight through a structured trade-off interview — one question at a time — and emits a `serviceObjectives[]` block. It creates no Salesforce records; when complete, delegates to `sfs-sobject-create`.
+**Designs the service objectives for a scheduling policy.** This skill collects the objective selection and derives each objective's weight through a structured trade-off interview — one question at a time — and emits a `serviceObjectives[]` block as output. It does not create any Salesforce records. When complete, delegates to `sfs-sobject-create`.
 
 **Interview phases:** Scheduling Policy → Work Rules → **Service Objectives** (this skill) → Record Creation
 
-The `policy` block (from `sfs-scheduling-policy-designer`) and `workRules[]` block (from `sfs-work-rule-designer`) arrive as context; this skill adds `serviceObjectives[]` and hands the complete design to `sfs-sobject-create`.
+This skill covers the service objective phase only. The `policy` block (from `sfs-scheduling-policy-designer`) and the `workRules[]` block (from `sfs-work-rule-designer`) arrive as context; this skill adds `serviceObjectives[]` and hands the complete design to `sfs-sobject-create`.
 
 ---
 
 ## Background: How SFS Scoring Works
 
-The optimizer assigns penalty points to each candidate schedule. Lower total penalty = better schedule. Each objective contributes penalty points based on its weight and its own scale (its worst-case scenario).
+The optimizer assigns penalty points to each candidate schedule. Lower total penalty = better schedule. Each service objective contributes penalty points based on its weight and its own scale (the worst-case scenario for that objective).
 
-**Minimize Travel weight is the anchor** — set at 1000; all other weights derive relative to it. The general formula, common to every objective (stated once, not re-derived per objective):
+**Minimize Travel weight is the anchor** — its value is set at 1000 and all other weights are derived relative to it. The general formula, common to every objective (stated once — not re-derived per objective):
 
 ```text
 penaltyPerViolation = max( 1, roundingFn( (1000 × weight) / scale ) ) × finalMultiplier
@@ -31,40 +42,37 @@ total_penalty       = ceil( violations / granularity ) × penaltyPerViolation
 
 Two consequences of the shared ×1000 internal multiplier:
 
-- It cancels out of every derivation between two objectives — which is why the interview's continuous approximations stay valid and every "derive weight_X from weight_Y" formula is clean of any ×1000 term. Where the rounding isn't exact for integer weights (ASAP's round, Skill Level/Preference's roundInt), small drift is possible — flagged per objective below.
+- It cancels out of every derivation between two objectives — which is why the continuous approximations used in the interview stay valid and every "derive weight_X from weight_Y" formula is clean of any ×1000 term. Where the rounding function isn't exact for integer weights (ASAP's round, Skill Level/Preference's roundInt), small drift is possible — flagged per objective below.
 - The `max(1, …)` floor guarantees every included objective has some effect even at a very low weight.
 
-**One exception:** Same Site's final multiplier (×0.01) nets to an effective ×10, not ×1000 — the one place the "divide by the other objective's rate" shortcut needs adjustment.
+**One exception:** Same Site's final multiplier (×0.01) nets to an effective ×10, not ×1000 — the one place the "just divide by the other objective's rate" shortcut needs adjustment.
 
 ---
 
 ## Penalty Formulas by Objective
 
-Use these to show math and back-calculate weights. General mechanics (×1000, floor, why derivations stay valid) are above, not repeated.
+Use these to show math and back-calculate weights. General mechanics (×1000, floor, why derivations stay valid) are above and not repeated.
 
 **Minimize Travel (anchor)** — Scale 120 min (2 hr = default `MaxGrade__c`), round5, ×1/60 (per-minute → per-second). `penaltyPerViolation_travel = max(1, round5(1000×weight_travel/120)) × (1/60)`. At weight 1000 → 8333.33333 → 138.88889 pts/sec (whole-second granularity). Continuous: `travel_penalty(X_min) ≈ X × weight_travel/120` — ≈8.333 pts/min at 1000.
-*Precision:* Travel is per-second; Overtime (same scale) is per-minute — a 61-sec trip costs more than a 60-sec one. Floor binds only below ≈0.12.
-
-**ASAP** — Scale 43,200 min (30 days), round. `penaltyPerViolation_asap = max(1, round(1000×weight_asap/43200))`. Whole-minute granularity: `asap_penalty(X_sec) = ceil(X_sec/60) × penaltyPerViolation`. Continuous: `asap_penalty(Y_min) ≈ Y × weight_asap/43200`.
-*Precision:* Weights 1–21 are dead — round(1000×21/43200)=0, clamped to 1, so all give the identical 1 pt/min rate. Above that, drift is small (weight 250 → effective 259.2, 3.7%). Validate with the integer formula when precision matters.
+*Precision:* Travel is per-second; Overtime (same scale) is per-minute — a 61-sec trip costs more than a 60-sec one. Floor binds only below weight ≈0.12.
 
 **Same Site** — Scale 1 (binary), round5, ×0.01 → **effective ×10, the exception**. `penaltyPerViolation_same_site = max(1, round5(1000×weight_same_site)) × 0.01`. At weight 50 → 500 pts/violation.
 *Precision:* round5 exact for integer weights. Flat per-event regardless of time. Effective multiplier is ×10, not ×1000.
 
-**Minimize Overtime** — **Identical mechanics to Minimize Travel** (scale 120, round5, weight 1000 → 8333.33333) **except:** final multiplier is ×1.0 not ×1/60, so the rate is per-**minute** (8333.33333 pts/min); and penalty groups into whole minutes — `overtime_penalty(X_sec) = ceil(X_sec/60) × penaltyPerViolation` — so a 61-sec block costs the same as 120-sec. `penaltyPerViolation_overtime = max(1, round5(1000×weight_overtime/120)) × 1.0`. Continuous: `≈ Z × weight_overtime/120`; comparable to Travel.
-*Precision:* Floor binds below ≈0.12.
+**Minimize Overtime** — **Identical mechanics to Minimize Travel** (scale 120, round5, weight 1000 → 8333.33333) **except two differences:** final multiplier is ×1.0 not ×1/60, so the rate is per-**minute** (8333.33333 pts/min); and penalty groups into whole minutes — `overtime_penalty(X_sec) = ceil(X_sec/60) × penaltyPerViolation` — so a 61-sec block costs the same as a 120-sec one. `penaltyPerViolation_overtime = max(1, round5(1000×weight_overtime/120)) × 1.0`. Continuous: `≈ Z × weight_overtime/120`; comparable to Travel.
+*Precision:* Floor binds below weight ≈0.12.
 
-**Preferred Resource** — Scale 1 (binary), roundInt, ×1.0. `penaltyPerViolation_preferred = max(1, roundInt(100 × 10.0 × weight_preferred)) × 1.0` (100×10.0 = 1000). At weight 375 → 375,000 pts/violation. Derivation: `weight_preferred = T_equiv × (weight_travel/120)` — with weight_travel 1000: `= T_equiv × 8.333`.
+**Preferred Resource** — Scale 1 (binary), roundInt, ×1.0. `penaltyPerViolation_preferred = max(1, roundInt(100 × 10.0 × weight_preferred)) × 1.0` (100×10.0 = 1000, just decomposed). At weight 375 → 375,000 pts/violation. Derivation: `weight_preferred = T_equiv × (weight_travel/120)` — with weight_travel 1000: `= T_equiv × 8.333`.
 *Precision:* Zero rounding error for integer weights (exact form `X_violations × 1000 × weight_preferred`). Floor only below weight 0.001.
 
 **Resource Priority** — Scale 10 (priority 0–10; 0 = best, 10 = lowest), no rounding (raw decimal). `penaltyPerViolation_resource_priority = max(1, (weight_resource_priority/10.0) × 1000)`. At weight 1875 → 187,500 pts/priority point. Total for priority P: `P × penaltyPerViolation`. P=0 → 0; P=10 → max.
 *Precision:* Full float, no rounding. Linear — priority 5 = 50% of max.
 
-**Skill Level** — Scale 10 (10-point scale), roundInt. `penaltyPerViolation_skill_level = max(1, roundInt(1000×weight_skill_level/10))`. Total for skill level S: `S × penaltyPerViolation`.
-*Applicability:* Multiple skill requirements → SFS averages the scores; none → no impact. Least vs. Most Qualified mode (set in the interview) flips the preferred direction but not the formula.
+**Skill Level** — Scale 10 (10-point skill scale), roundInt. `penaltyPerViolation_skill_level = max(1, roundInt(1000×weight_skill_level/10))`. Total for skill level S: `S × penaltyPerViolation`.
+*Applicability:* Multiple skill requirements → SFS averages the scores; no skill requirements → no impact. Least vs. Most Qualified mode (handled in the interview) flips the preferred direction but not the formula.
 *Precision:* Zero rounding error for integer weights. Floor negligible below weight ≈0.01.
 
-**Skill Preference** — Scale 10 (skill priority 1–10; 1 = most preferred, 10 = least; null → 10), roundInt. `penaltyPerViolation_skill_preference = max(1, roundInt(1000×weight_skill_preference/10))`. Total for skill priority SP: `SP × penaltyPerViolation`. Applicability (same Skill Type, OR matching on the companion Match Skills rule) set in the interview.
+**Skill Preference** — Scale 10 (skill priority 1–10; 1 = most preferred, 10 = least; null → 10), roundInt. `penaltyPerViolation_skill_preference = max(1, roundInt(1000×weight_skill_preference/10))`. Total for skill priority SP: `SP × penaltyPerViolation`. Applicability (same Skill Type, OR matching on the companion Match Skills rule) handled in the interview.
 *Precision:* Zero rounding error for integer weights. Linear in SP.
 
 **Group Nearby** — Scale 1 (binary — in cluster or not), round5, ×1.0 (full ×1000, unlike Same Site's ×0.01). `penaltyPerViolation_group_nearby = max(1, round5(1000×weight_group_nearby)) × 1.0`. At weight 167 → 167,000 pts/violation. Derivation: `weight_group_nearby = T_equiv × (weight_travel/120)` — with weight_travel 1000: `= T_equiv × 8.333`.
@@ -79,16 +87,21 @@ Use these to show math and back-calculate weights. General mechanics (×1000, fl
 
 **Two global rules (govern everything below):**
 
-1. **Round every derived weight up to the next whole number** — ceiling, not nearest. SFS policies don't accept decimal weights.
-2. **Never compare raw weight values across objectives** to infer priority — always compute and compare penalty rates per unit, since each has its own scale.
+### Phase 1: **Round every derived weight up to the next...
+
+
+
+### Phase 2: **Never compare raw weight values across objectives** to...
+
+
 
 ---
 
 ### Step 1: Objective Selection
 
-First explain the concept: service objectives are soft scoring criteria that grade candidates who already survived the work rules — unlike work rules, they never reject anyone, they just influence which eligible candidate the optimizer prefers. Note that Minimize Travel is always included automatically as the anchor, fixed weight 1000, that every other weight derives against through trade-off math — the user need not select it.
+First explain the concept: service objectives are soft scoring criteria that grade candidates who already survived the work rules — unlike work rules, objectives never reject anyone, they just influence which eligible candidate the optimizer prefers. Tell the user that Minimize Travel is always included automatically as the anchor objective, with a fixed weight of 1000 that every other objective's weight gets derived against through trade-off math — they don't need to select it.
 
-Then present the remaining nine objectives **one category at a time**, in this fixed order, waiting for the user's selection before the next category:
+Then present and ask about the remaining nine objectives **one category at a time**, in this fixed order, waiting for the user's selection before moving to the next category:
 
 **1. Customer-Experience Objectives** — present these three, ask which (if any):
 - ASAP — Serve customers as early as possible
@@ -108,9 +121,9 @@ Then present the remaining nine objectives **one category at a time**, in this f
 
 **Per-objective follow-up questions** — ask right after the category they belong to is answered, before the next category:
 
-- **Minimize Travel** (always — ask once, at the end of the Cost/Efficiency category): "Should Minimize Travel also count the legs to/from a resource's home base — home to first job, and last job back home — or exclude those from scoring?" Capture as two independent flags: `excludeTravelFromHome` and `excludeTravelToHome` (true = excluded). Default both false.
-- **Same Site** (only if selected): "Should Same Site treat two appointments as the same site only when they share the exact latitude/longitude — useful for campuses or farms — or use the default grouping (within about one second of travel time)?" Capture as `useExactLocation` (true = exact lat/long only). Default false.
-- **Minimize Gaps** (only if selected): Ask the minimum idle duration the company counts as a gap (30 min–24 hr). Capture as `params.minGapMinutes`; default 30. Asking here keeps "what counts as a gap" separate from "how hard to close one."
+- **Minimize Travel** (always — ask once, at the end of the Cost/Efficiency category): "Should Minimize Travel also count the legs to and from a resource's home base — the drive from home to the first job, and from the last job back home — or should those legs be excluded from scoring?" Capture as two independent flags: `excludeTravelFromHome` and `excludeTravelToHome` (true = excluded). Default both false.
+- **Same Site** (only if selected): "Should Same Site treat two appointments as the same site only when they share the exact same latitude/longitude — useful for campuses or farms — or use the default grouping (appointments within about one second of travel time)?" Capture as `useExactLocation` (true = exact lat/long only). Default false.
+- **Minimize Gaps** (only if selected): Ask for the minimum idle duration their company counts as a gap (30 min–24 hr). Capture as `params.minGapMinutes`; default 30. Asking here keeps "what counts as a gap" separate from "how hard to close one."
 
 Once all three categories are answered and follow-ups captured, move to Step 2.
 
@@ -118,9 +131,9 @@ Once all three categories are answered and follow-ups captured, move to Step 2.
 
 ### Step 2: Trade-Off Interview
 
-For each selected objective (other than Minimize Travel), ask a trade-off question. The goal is the crossover point where the user considers the two options equally acceptable — that equivalence lets you calculate the weight. After they answer, solve for the unknown weight by setting the two penalty expressions equal, then round up per the global rules. Always show the math.
+For each selected objective (other than Minimize Travel), ask a trade-off question. The goal is the crossover point where the user considers the two options equally acceptable — that equivalence is what lets you calculate the weight. After the user answers, solve for the unknown weight by setting the two penalty expressions equal, then round up per the global rules. Always show the math.
 
-**Offer concrete preset answers alongside the open question.** After the question template, give a few ready-made crossover points spanning light/medium/strong preference so the user can pick one instead of inventing numbers. Always also invite their own exact trade-off. Presets are a convenience, not a separate calculation path.
+**Offer concrete preset answers alongside the open question.** After the question template, give a small set of ready-made crossover points spanning light/medium/strong preference — so the user can pick one instead of inventing numbers. Always also invite them to describe their own exact trade-off. Presets are a convenience, not a separate calculation path.
 
 #### ASAP Trade-Off
 
@@ -136,12 +149,12 @@ weight_asap = X × weight_travel × 6 / Y
 ```
 With weight_travel = 1000: `weight_asap = X × 6000 / Y`.
 
-**Integer-formula validation:** confirm `penaltyPerViolation = max(1, round(1000 × weight_asap / 43200))`, then `effective_weight = penaltyPerViolation × 43200 / 1000`. If it differs meaningfully (>5% drift), note it.
-**Low-weight warning:** if derived weight < 22, warn that SFS clamps the per-minute penalty to 1 (the floor) — any weight 1–21 produces identical behavior.
+**Integer-formula validation:** confirm `penaltyPerViolation = max(1, round(1000 × weight_asap / 43200))`, then `effective_weight = penaltyPerViolation × 43200 / 1000`. If effective_weight differs meaningfully (>5% drift), note it.
+**Low-weight warning:** if derived weight < 22, warn that SFS clamps the per-minute penalty to 1 (the floor) — any weight 1–21 produces identical optimizer behavior.
 
 #### Same Site Trade-Off
 
-**Framing note:** Do NOT compare Same Site to travel time — same-site appointments are already at the same location. Compare against ASAP or Preferred Resource (if selected).
+**Framing note:** Do NOT compare Same Site to travel time — same-site appointments are already at the same location. Compare against ASAP (if selected) or Preferred Resource (if selected).
 
 **If ASAP is selected — Same Site vs. ASAP:**
 > "Imagine two appointments at the same site. The optimizer can either: (A) Assign both to the same resource, but they get scheduled [H] hours later than they could be. (B) Split them so they're scheduled right now. At what scheduling delay would you say 'just split them'?"
@@ -174,20 +187,20 @@ Z × (weight_overtime / 120) = (H × 60) × (weight_asap / 43200)
 weight_overtime = weight_asap × H / (Z × 6)
 ```
 *Requires weight_asap calculated first if ASAP is selected.*
-**Overtime vs. Travel fallback (if ASAP not selected):** `weight_overtime = T_equiv × weight_travel / Z`, where T is the equivalent minutes of travel the user would accept over Z minutes of overtime.
+**Overtime vs. Travel fallback (if ASAP not selected):** `weight_overtime = T_equiv × weight_travel / Z`, where T is the equivalent minutes of travel the user would rather have than Z minutes of overtime.
 
 #### Preferred Resource Trade-Off
 
-> "If an appointment has a preferred resource assigned, how important is honoring it? Imagine the preferred resource is available but would require [X] extra minutes of travel — at what point would you say 'just use the closer resource'?"
+> "If an appointment has a preferred resource assigned, how important is it to honor that preference? Imagine the preferred resource is available but would require [X] extra minutes of travel — at what point would you say 'just use the closer resource'?"
 
 Presets: "15 extra minutes" (light), "30 extra minutes" (moderate), "60 extra minutes" (strong).
 Math (travel threshold T_equiv): `weight_preferred = T_equiv × (weight_travel / 120)`
 
 #### Group Nearby Trade-Off
 
-**Framing note:** Group Nearby and Minimize Travel are natural competitors — keeping a cluster intact may cost more total travel than breaking it. The trade-off: the maximum additional overall travel the user will spend to keep a cluster together.
+**Framing note:** Group Nearby and Minimize Travel are natural competitors — keeping a cluster intact may cost more total travel than breaking it. The trade-off: what is the maximum additional overall travel the user will spend to keep a cluster together?
 
-> "What is the maximum additional overall travel you'd add to the schedule to keep all appointments in a cluster together? If maintaining the cluster costs more than that, the optimizer should break it and save the travel instead."
+> "What is the maximum amount of additional overall travel you'd be willing to add to the schedule to keep all appointments in a cluster together? If maintaining the cluster costs more than that, the optimizer should break it and save the travel instead."
 
 Presets: "10 extra minutes" (weak), "20 extra minutes" (moderate), "30 extra minutes" (strong).
 Math (T_equiv): `weight_group_nearby = T_equiv × (weight_travel / 120)`
@@ -195,7 +208,7 @@ Math (T_equiv): `weight_group_nearby = T_equiv × (weight_travel / 120)`
 #### Resource Priority Trade-Off
 
 Background to share:
-> "The Resource Priority objective ranks service resources on a scale of 0–10, where 0 = highest priority (best candidate) and 10 = lowest. For example, assign internal staff priority 1 and contractors 5+. The optimizer applies a penalty proportional to priority — a priority 5 resource incurs 50% of the full weight as penalty, a priority 0 resource none."
+> "The Resource Priority objective lets you rank service resources on a scale of 0–10, where 0 means highest priority (best candidate) and 10 means lowest priority. For example, you might assign internal staff a priority of 1 and contractors a priority of 5 or higher. The optimizer applies a penalty proportional to a resource's priority value — a priority 5 resource incurs 50% of the full objective weight as a penalty, while a priority 0 resource incurs no penalty at all."
 
 > "Imagine two available resources: Resource A is a staff technician (priority 1) but is [X] minutes further away. Resource B is a contractor (priority [P]) and is the closer option. At what point would you say 'just use the contractor'?"
 
@@ -206,12 +219,12 @@ Example (staff 1, contractor 5, T_equiv = 90): `= 90 × 1000 / (12 × 4) = 1,875
 #### Skill Level Trade-Off
 
 Background to share:
-> "The Skill Level objective steers the optimizer toward either the least or most qualified resource that meets an appointment's skill requirements. Penalty = the resource's raw skill level × the objective weight — so a skill level 8 resource incurs 8× the penalty of a skill level 1 resource."
+> "The Skill Level objective steers the optimizer toward either the least or most qualified resource that meets an appointment's skill requirements. The penalty is calculated as the resource's raw skill level value multiplied by the objective weight — so a resource with skill level 8 incurs 8× the weight as penalty compared to a skill level 1 resource."
 
 **Step 1 — Ask which mode they want:**
-> "Which mode would you like?
+> "Which mode would you like to use?
 > - **Least Qualified** — prefers the lowest-skilled resource that still meets the requirement. Good for preserving senior resources for complex jobs, or keeping costs down.
-> - **Most Qualified** — prefers the highest-skilled resource available. Good for first-time fix rates or when outcome quality is the priority."
+> - **Most Qualified** — prefers the highest-skilled resource available. Good for maximising first-time fix rates or when quality of outcome is the priority."
 
 **If Least Qualified:**
 > "Imagine two eligible resources: a junior technician (skill level [S_low]) and a senior technician (skill level [S_high]). The senior tech is closer. In Least Qualified mode, the optimizer prefers the junior tech to preserve the senior for harder jobs. How many extra minutes of travel would you accept to route the junior tech?"
@@ -226,12 +239,12 @@ Example — Least Qualified (S_low=4, S_high=8, T_equiv=30): `= 30 × 1000 / (12
 #### Skill Preference Trade-Off
 
 Background to share:
-> "The Skill Preference objective applies when a work order has multiple skill requirements of the same Skill Type and a preference exists for one over another. Each requirement has a Skill Priority from 1 to 10 — 1 = most preferred, 10 = least. The optimizer assigns a penalty proportional to that priority."
+> "The Skill Preference objective applies when a work order has multiple skill requirements of the same Skill Type, and a preference exists for one skill over another. Each skill requirement has a Skill Priority value from 1 to 10 — where 1 is the most preferred and 10 is the least preferred. The optimizer assigns a penalty proportional to that priority value."
 
-Also capture the **Skill Type** (required for this objective to function). Skill Preference operates on one Skill Type — the family of skills (e.g. Language) evaluated by a companion Match Skills rule with "At Least One Skill Matches (OR)." Ask:
-> "Which Skill Type does this preference rank within? Give me its Developer Name — it must match a Match Skills work rule set to At Least One Skill Matches (OR), since Skill Preference has no effect under AND matching."
+Also capture the **Skill Type** (required for this objective to function). Skill Preference operates on one Skill Type — the family of skills (e.g. Language) evaluated by a companion Match Skills work rule with "At Least One Skill Matches (OR)." Ask:
+> "Which Skill Type does this preference rank within? Give me its Developer Name — it must be the same Skill Type used by a Match Skills work rule set to At Least One Skill Matches (OR), since Skill Preference has no effect under AND matching."
 
-Record as `skillType` param (Skill Type Developer Name, maps to `{ns}Skill_Type__c` on the goal). Flag if no Match Skills rule with OR logic exists for that Skill Type.
+Record as `skillType` param (a Skill Type Developer Name, maps to `{ns}Skill_Type__c` on the goal). Flag if the user hasn't defined a Match Skills rule for that Skill Type with OR logic.
 
 > "Imagine a work order where the customer can be served by either a [Skill A]-speaking technician (skill priority [SP_high_pref]) or a [Skill B]-speaking technician (skill priority [SP_low_pref]), but they prefer [Skill A]. The [Skill A] technician is further away. How many extra minutes of travel would you accept to assign the [Skill A] technician?"
 
@@ -241,7 +254,7 @@ Example (Spanish priority 1, English priority 6, T_equiv = 45): `= 45 × 1000 /
 
 #### Minimize Gaps Trade-Off
 
-*Minimum gap duration was captured in Step 1 as `params.minGapMinutes` (default 30). Don't re-ask it. This section covers the weight math only.*
+*Minimum gap duration was already captured in Step 1 as `params.minGapMinutes` (default 30). Don't re-ask it. This section covers the weight math only.*
 
 **If ASAP is selected — Minimize Gaps vs. ASAP:**
 > "The optimizer can either: (A) Leave a gap in a technician's schedule and schedule a new appointment [H] hours earlier. (B) Compress the schedule to eliminate the gap, but that appointment gets scheduled [H] hours later. At what scheduling delay would you say 'just leave the gap and schedule earlier'?"
@@ -256,32 +269,43 @@ Example (weight_asap = 250, D_equiv = 240 min): `= 240 × 250 / 43200 = 1.389
 Presets: "10 extra minutes", "20 extra minutes", "30 extra minutes".
 Math: `weight_gaps = T_equiv × weight_travel / 7200`
 
-**Integer-formula validation:** confirm `penaltyPerViolation = max(1, round(1000 × weight_gaps))`. For very small weights (below ~1), warn that the max(1,…) floor clamps the penalty to a fixed minimum.
+**Integer-formula validation:** confirm `penaltyPerViolation = max(1, round(1000 × weight_gaps))`. For very small derived weights (below ~1), warn that the max(1,…) floor clamps the penalty to a fixed minimum.
 
 ---
 
 ### Step 3: Output the Results
 
-After all trade-off questions are answered, present a table with one row per included objective, showing its **weight** and a one-line **rationale** grounded in the trade-off the user stated (e.g. for ASAP, the "X min travel ≈ Y hours delay" crossover; for Same Site, "1 split ≈ D min of ASAP delay"). Minimize Travel is always the anchor at 1000.
+After all trade-off questions are answered, present a clean summary in a table with one row per included objective, showing its **weight** and a one-line **rationale** grounded in the trade-off the user stated (e.g. for ASAP, the "X min travel ≈ Y hours delay" crossover they gave; for Same Site, "1 split ≈ D min of ASAP delay"; and so on). Minimize Travel is always the anchor at 1000.
 
-Then describe **relative priority** using penalty points per unit — not raw weights, since the multiplier differs per objective. Compute each rate: Travel `weight_travel / 120` per minute; ASAP `weight_asap / 43200` per minute of delay; Overtime `weight_overtime / 120` per minute; Same Site `weight_same_site × 10` per event (×10, not ×1000); Preferred Resource and Group Nearby `weight × 1000` per event; Resource Priority `weight × (P / 10)` per resource (show a couple priority tiers); Skill Level `S × weight × 100` per resource (show relevant tiers); Skill Preference `weight × (SP / 10)` per skill assignment (show relevant priorities); Minimize Gaps `weight_gaps × 1000` per gap (flat).
+Then describe **relative priority** using penalty points per unit — not raw weights, since the multiplier differs per objective. Compute each rate as: Travel `weight_travel / 120` per minute; ASAP `weight_asap / 43200` per minute of delay; Overtime `weight_overtime / 120` per minute; Same Site `weight_same_site × 10` per event (×10, not ×1000); Preferred Resource and Group Nearby `weight × 1000` per event; Resource Priority `weight × (P / 10)` per resource (show a couple of relevant priority tiers); Skill Level `S × weight × 100` per resource (show relevant skill tiers); Skill Preference `weight × (SP / 10)` per skill assignment (show relevant priorities); Minimize Gaps `weight_gaps × 1000` per gap (flat).
 
-Use these rates to explain relative priority in plain English, grounded in the trade-offs the user stated — e.g. "This reflects your stated preference that 30 minutes of travel equals 12 hours of delay." Offer to re-run any trade-off if the implied priority doesn't match expectations.
+Use these rates to explain relative priority in plain English, grounded in the original trade-offs the user stated — e.g. "This reflects your stated preference that 30 minutes of travel is equivalent to 12 hours of delay." Offer to re-run any trade-off question if the implied priority doesn't match the user's expectations.
 
 ---
 
 ### Policy at a Glance (2–3 sentence business summary)
 
-After presenting the weights and penalty rates, generate a 2–3 sentence business summary of what this policy is optimized for — an executive soundbite for stakeholders who don't care about the math.
+After presenting the weights and penalty rates, generate a 2–3 sentence high-level business summary describing what this scheduling policy is optimized for — an executive soundbite for stakeholders who don't care about the math.
 
 **How to generate it:**
 
-1. Classify objectives by category: Customer-experience (ASAP, Same Site, Group Nearby); Cost/efficiency (Minimize Travel, Gaps, Overtime); Workforce/assignment-quality (Preferred Resource, Resource Priority, Skill Level, Skill Preference).
-2. Determine which category dominates by comparing penalty rates across objectives — the one generating the largest penalties is the dominant focus.
-3. Identify key trade-off tensions from the crossover values stated — these reveal what the policy will sacrifice for what.
-4. Write 2–3 sentences naming a primary and secondary focus, what the optimizer prioritizes in plain terms, and what it's willing to sacrifice up to what threshold. If one category's penalties are 5×+ higher, call it out; if two are close, name them co-primary. Only call the policy "Balanced" if all three categories are within ~2× of each other.
+### Phase 3: Classify objectives by category
+
+Customer-experience (ASAP, Same Site, Group Nearby); Cost/efficiency (Minimize Travel, Minimize Gaps, Minimize Overtime); Workforce/assignment-quality (Preferred Resource, Resource Priority, Skill Level, Skill Preference).
+
+### Phase 4: Determine which category dominates by comparing penalty rates...
+
 
-Use business language grounded in the user's stated values (e.g. "drive up to 2 hours," "wait up to 24 hours") — not penalty math. This summary is also a good candidate for the scheduling policy record's Description field — suggest it at handoff.
+
+### Phase 5: Identify the key trade-off tensions from the crossover...
+
+
+
+### Phase 6: Write 2–3 sentences naming a primary and secondary...
+
+
+
+Use business language grounded in the user's actual stated values (e.g. "drive up to 2 hours," "wait up to 24 hours") — not penalty math. This summary is also a good candidate for the Description field of the scheduling policy record — suggest it to the user when handing off.
 
 ---
 
@@ -289,7 +313,7 @@ Use business language grounded in the user's stated values (e.g. "drive up to 2
 
 The skill's final deliverable and sole contract with `sfs-sobject-create`. Once the design is settled (policy settings, work rules, relevance groups, weights), emit **one** structured build spec as a JSON object. `sfs-sobject-create` consumes it verbatim and never re-derives intent, so it must be complete and self-contained.
 
-**Hard boundary:** emit **design values only** — no Salesforce object names, field API names, record IDs, composite-API reference syntax, or creation ordering (those belong to the data-layer skill). Describe rules/objectives by their canonical type name (exactly as used here: e.g. Match Skills, Minimize Travel, Resource Priority) plus business parameters. Unknown parameter → omit or mark null; never invent an API field name.
+**Hard boundary:** emit **design values only**. No Salesforce object names, field API names, record IDs, composite-API reference syntax, or creation ordering — those belong to the data-layer skill. Describe rules/objectives by their canonical type name (exactly as used here: e.g. Match Skills, Minimize Travel, Resource Priority) plus business parameters. Unknown parameter → omit or mark null; never invent an API field name.
 
 ```jsonc
 {
@@ -322,21 +346,314 @@ The skill's final deliverable and sole contract with `sfs-sobject-create`. Once
 
 **Rules for emitting:**
 
-1. **Naming convention** (every rule and objective): `name` = canonical type name + abbreviated policy name, separated by `" - "` — e.g. policy "First test on shorter" → "Match Skills - First test", "Minimize Travel - First test". Abbreviate the policy name (drop filler like "on shorter"/"policy"); don't append it verbatim. *Exception:* the two Arrival Window Match Time rules keep their own names — append the abbreviated policy name rather than replacing with the type: "Arrival Window Start - First test", "Arrival Window End - First test".
-2. **Always include** Minimize Travel at weight 1000 and exactly one Service Resource Availability rule with `"mandatory": true`, even if never discussed. Never emit Earliest Start Permitted or Due Date.
-3. **One instance per subset** — if a rule/objective was split across relevance groups, emit a separate entry per group, each with its own `relevanceGroup`.
-4. **Weights are whole numbers**, already ceiling-rounded per the Conversation Flow rules.
-5. **Parameters are business values, not field mappings** — "a 30-min break between 12:00 and 15:00" goes in as durations/times; the field mapping lives in the data-layer skill.
-6. **Surface prerequisites explicitly** — any relevance-group Boolean field, custom priority field, or skill-type dependency the design assumes goes in `prerequisites` so the user and data-layer skill know it must pre-exist.
-7. **Show the spec and get approval before handing off.** Present the complete build spec as a JSON code block and ask plainly whether it looks good (e.g. "Here's the full build spec — does this look right, or would you like to change anything?"). Wait for explicit confirmation; apply requested edits and re-show. Only after approval proceed to handoff.
-8. **Don't create anything.** Once approved, tell the user it's ready for `sfs-sobject-create`. If asked to "build/deploy/create it," finalize the spec — don't perform CRUD.
+### Phase 7: **Naming convention** (every rule and objective)
+
+`name` = the canonical type name + the abbreviated policy name, separated by `" - "` — e.g. policy "First test on shorter" → "Match Skills - First test", "Minimize Travel - First test". Abbreviate the policy name (drop filler like "on shorter"/"policy"); don't append it verbatim. *Exception:* the two Arrival Window Match Time rules keep their own names (Arrival Window Start, Arrival Window End) — append the abbreviated policy name to those rather than replacing with the type: "Arrival Window Start - First test", "Arrival Window End - First test".
+
+### Phase 8: **Always include** Minimize Travel at weight 1000 and exactly one Service Resource Availability rule with `"mandatory"
+
+true`, even if never discussed. Never emit Earliest Start Permitted or Due Date.
+
+### Phase 9: **One instance per subset** — if a rule/objective...
+
+
+
+### Phase 10: **Weights are whole numbers**, already ceiling-rounded per the...
+
+
+
+### Phase 11: **Parameters are business values, not field mappings** — "a 30-min break between 12
+
+00 and 15:00" goes in as durations/times; the field-layout mapping lives in the data-layer skill.
+
+### Phase 12: **Surface prerequisites explicitly** — any relevance-group Boolean field...
+
+
+
+### Phase 13: **Don't create anything.** After emitting, tell the user...
+
+
 
 ---
 
 ## Handoff
 
-When the user confirms the weights and summary, the objective design phase is complete. **Delegate to `sfs-sobject-create`**, passing the build spec above (with the `policy` from `sfs-scheduling-policy-designer`, `workRules` from `sfs-work-rule-designer`, and `serviceObjectives` from this skill) so it can create the scheduling policy, work rules, and service objectives in dependency order.
-
-Do not create records here or start the creation flow — `sfs-sobject-create` owns all Salesforce API calls. Transition message:
+When the user confirms the weights and summary, the objective design phase is complete. **Delegate to `sfs-sobject-create`**, passing the build spec above (with the `policy` block from `sfs-scheduling-policy-designer`, the `workRules` from `sfs-work-rule-designer`, and the `serviceObjectives` from this skill) so it can create the scheduling policy, its work rules, and its service objectives in dependency order.
 
 > "Objective design is complete. Next, I'll hand off to record creation, which will create all the Salesforce records — the scheduling policy, work rules, and service objectives — in the correct order. Ready to proceed?"
+
+─────
+**Runtime context (Headless 360 / agentic):** When this skill runs in the Headless 360 / agentic context, prefer the ``dispatch`` tool over CLI tools (``sf project deploy``, ``sfdx``, shell commands) when possible. The operations available to you are listed below in ``steps:``; each has been verified against the live org. Use ``dispatch`` against the canonical paths. CLI fallback is acceptable only when no API path exists for a given capability.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- FSL managed package installed on the org. (check: `Tooling API: GET /services/data/v68.0/tooling/query with q=SELECT SubscriberPackage.NamespacePrefix FROM InstalledSubscriberPackage. Filter client-side for a NamespacePrefix starting with FSL (matches FSL, FSLQA, FSLMPTEST, FSLMPPERF). No FSL* record — abort: this skill cannot design objectives for an org without FSL.`)
+- The Skill Preference objective requires at least one SkillType record to exist on the org before deployment. The skill body asks the user for a Skill Type Developer Name; if SkillType has zero records, warn the user that they must create the target Skill Type before sfs-sobject-create writes the objective. (check: `SOQL: SELECT COUNT() FROM SkillType. Zero → surface in the interview if the user selects Skill Preference; the emitted spec should add a prerequisites[] entry naming the Skill Type Developer Name the user needs to create.`)
+- For Relevance Groups whose basis is Service Territory Member, the intended scoping Boolean field must already exist as a boolean-type custom field on ServiceTerritoryMember (only IsDeleted is standard). If the user names a Boolean field for STM-basis scoping, the emitted prerequisites[] entry names the field so a metadata workflow can add it before deployment. (check: `Global describe on ServiceTerritoryMember; filter fields whose type equals boolean. On a fresh FSL install, only IsDeleted is present. Any STM-basis Relevance Group requires customer-authored Booleans; surface the dependency in the emitted prerequisites[] rather than blocking.`)
+
+**Operational rules:**
+
+- **ASAP** — Scale 43,200 min (30 days), round. `penaltyPerViolation_asap = max(1, round(1000×weight_asap/43200))`. Whole-minute granularity: `asap_penalty(X_sec) = ceil(X_sec/60) × penaltyPerViolation`. Continuous: `asap_penalty(Y_min) ≈ Y × weight_asap/43200`.
+*Precision:* Weights 1–21 are dead — round(1000×21/43200)=0, clamped to 1, so all produce the identical 1 pt/min rate. Above that, drift is small (weight 250 → effective 259.2, 3.7%). Validate with the integer formula when precision matters.
+- Do not create any Salesforce records here, and do not start the creation flow — `sfs-sobject-create` owns all Salesforce API calls. Transition message:
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `resolve-fsl-namespace` | validate | — | `GET /services/data/v68.0/tooling/query` | — |
+| `enumerate-service-objective-record-types` | read | — | `GET /services/data/v68.0/query` | `resolve-fsl-namespace` |
+| `describe-service-goal-schema` | read | — | `GET /services/data/v68.0/sobjects/FSLMPPERF__Service_Goal__c/describe` | `resolve-fsl-namespace` |
+| `list-scheduling-policy-goal-junction` | read | — | `GET /services/data/v68.0/sobjects/FSLMPPERF__Scheduling_Policy_Goal__c/describe` | `resolve-fsl-namespace` |
+| `list-skill-types` | read | — | `GET /services/data/v68.0/query` | — |
+| `list-service-appointment-boolean-fields` | read | — | `GET /services/data/v68.0/sobjects/ServiceAppointment/describe` | — |
+| `list-service-territory-member-boolean-fields` | read | — | `GET /services/data/v68.0/sobjects/ServiceTerritoryMember/describe` | — |
+| `list-existing-service-goals` | read | — | `GET /services/data/v68.0/query` | `resolve-fsl-namespace` |
+| `emit-service-objectives-block` | write | — | — | `enumerate-service-objective-record-types`, `describe-service-goal-schema`, `list-scheduling-policy-goal-junction`, `list-skill-types`, `list-service-appointment-boolean-fields`, `list-service-territory-member-boolean-fields` |
+| `handoff-to-sobject-create` | delegate | — | — | `emit-service-objectives-block` |
+
+### Dependency graph
+
+```mermaid
+graph TD
+  resolve_fsl_namespace["resolve-fsl-namespace (validate)"]
+  enumerate_service_objective_record_types["enumerate-service-objective-record-types (read)"]
+  describe_service_goal_schema["describe-service-goal-schema (read)"]
+  list_scheduling_policy_goal_junction["list-scheduling-policy-goal-junction (read)"]
+  list_skill_types["list-skill-types (read)"]
+  list_service_appointment_boolean_fields["list-service-appointment-boolean-fields (read)"]
+  list_service_territory_member_boolean_fields["list-service-territory-member-boolean-fields (read)"]
+  list_existing_service_goals["list-existing-service-goals (read)"]
+  emit_service_objectives_block["emit-service-objectives-block (write)"]
+  handoff_to_sobject_create["handoff-to-sobject-create (delegate)"]
+  resolve_fsl_namespace --> enumerate_service_objective_record_types
+  resolve_fsl_namespace --> describe_service_goal_schema
+  resolve_fsl_namespace --> list_scheduling_policy_goal_junction
+  resolve_fsl_namespace --> list_existing_service_goals
+  enumerate_service_objective_record_types --> emit_service_objectives_block
+  describe_service_goal_schema --> emit_service_objectives_block
+  list_scheduling_policy_goal_junction --> emit_service_objectives_block
+  list_skill_types --> emit_service_objectives_block
+  list_service_appointment_boolean_fields --> emit_service_objectives_block
+  list_service_territory_member_boolean_fields --> emit_service_objectives_block
+  emit_service_objectives_block --> handoff_to_sobject_create
+```
+
+### Read operations
+
+#### `enumerate-service-objective-record-types`
+
+Enumerate active RecordType.DeveloperName values on `<NS>__Service_Goal__c`. This is the canonical enumeration of the service-objective types the org exposes. Every emitted objective in the serviceObjectives[] JSON block must map onto a DeveloperName from this set — sfs-sobject-create depends on it to write the correct RecordTypeId. Group Nearby is NOT a distinct RecordType on the target org; if the interview asks about it, the skill should confirm the org exposes it before offering the option.
+
+**Call:** `GET /services/data/v68.0/query`
+
+**Inputs:**
+
+- `q` *(`String`)* — SOQL: `SELECT Id, DeveloperName, Name, IsActive FROM RecordType WHERE SObjectType='<NS>__Service_Goal__c' AND IsActive = true ORDER BY DeveloperName`. Substitute the namespace discovered by resolve-fsl-namespace.
+
+**Depends on:** `resolve-fsl-namespace`
+
+**Output:** Records list with DeveloperName (e.g., Objective_Asap, Objective_Minimize_Travel, Objective_Same_Site, Objective_Skill_Level, Objective_Skill_Preferences, Objective_PreferredEngineer, Objective_Resource_Priority, Objective_Minimize_Gaps, Objective_Minimize_Overtime, Objective_Custom_Logic), Name (human-readable Field Service label), and Id. Skill maps the user's conversational objective choice onto DeveloperName. Expect 10 active records on target org sfs-headless-skill-building.
+
+**Notes:** Probe-verified 10 active DeveloperName values on target org. Objective
+types not surfaced by the skill interview (Objective_Custom_Logic) are
+still enumerated so the skill can decline them explicitly rather than
+being silently blocked at deploy time.
+
+#### `describe-service-goal-schema`
+
+Introspect the Service_Goal__c sObject to expose the config fields the interview drives. Loads picklist enums (Custom_Type__c has 14 values; Prioritize_Resource__c has Least Qualified / Most Qualified for the Skill Level mode question), the string columns backing skill params (Skill_Type__c, Resource_Priority_Field__c, Object_Group_Field__c, Resource_Group_Field__c), and the numeric/boolean columns for parameters such as Gap_Duration__c and Ignore_Home_Base_Coordinates__c. sObject path uses discovered namespace prefix — path shown is for the target org sfs-headless-skill-building; substitute the resolved <NS> at runtime.
+
+**Call:** `GET /services/data/v68.0/sobjects/FSLMPPERF__Service_Goal__c/describe`
+
+**Depends on:** `resolve-fsl-namespace`
+
+**Output:** From describe.fields[] extract by name: Custom_Type__c (picklist domain — 14 values covering the objective types), Prioritize_Resource__c (picklist "Least Qualified" default vs "Most Qualified"), Gap_Duration__c (double, minutes; params.minGapMinutes target), Ignore_Home_Base_Coordinates__c (boolean; travel-home flag target), Skill_Type__c (string; Skill Preference target), Resource_Priority_Field__c (string, default "fsl__priority__c"; Resource Priority target), Object_Group_Field__c and Resource_Group_Field__c (strings; Relevance Group scoping fields), Custom_Logic_Data__c (long textarea; Objective_Custom_Logic only).
+
+**Notes:** The describe response also carries all 10 RecordTypeIds. Consumers can
+source RecordTypeId from either this describe or the SOQL query in
+step enumerate-service-objective-record-types — the two are consistent
+on a healthy install.
+
+#### `list-scheduling-policy-goal-junction`
+
+Introspect the Scheduling_Policy_Goal__c junction that binds a Service_Goal to a Scheduling_Policy with a Weight. Downstream sfs-sobject-create writes rows to this junction — one per (policy, objective, weight) triple in the emitted serviceObjectives[] block. Key columns: FSLMPPERF__Scheduling_Policy__c (Master-Detail), Service_Goal__c (Master-Detail), Weight__c (Number(9,0), NOT nillable). The (9,0) precision enforces the skill's Global Rule #1 (whole-number weights) at the schema layer. sObject path uses discovered namespace prefix.
+
+**Call:** `GET /services/data/v68.0/sobjects/FSLMPPERF__Scheduling_Policy_Goal__c/describe`
+
+**Depends on:** `resolve-fsl-namespace`
+
+**Output:** From describe.fields[] confirm: FSLMPPERF__Weight__c has type=double, precision=9, scale=0, nillable=false; the two Master-Detail lookups exist and target Scheduling_Policy__c + Service_Goal__c. If Weight__c nillable turns out true on a non-target org, note the drift — the skill's ceiling-to-whole-number rule remains correct but the schema-level enforcement isn't there.
+
+**Notes:** This describe is a schema-visibility read for the design skill; the
+actual junction-row write happens in sfs-sobject-create. Surfacing the
+Weight__c(9,0) constraint here catches any future skill drift that
+forgets to ceiling-round.
+
+#### `list-skill-types`
+
+Read existing SkillType records. The Skill Preference objective requires a Skill Type Developer Name; the interview must be able to offer the enumerated set or warn the user when none exist. On the target org sfs-headless-skill-building, SkillType has zero records — Skill Preference is offerable per platform metadata but non-functional until the user creates SkillType records.
+
+**Call:** `GET /services/data/v68.0/query`
+
+**Inputs:**
+
+- `q` *(`String`)* — SOQL: `SELECT Id, DeveloperName, MasterLabel FROM SkillType ORDER BY DeveloperName`. Standard sObject — no namespace substitution needed.
+
+**Output:** Records list of SkillType with DeveloperName + MasterLabel. Empty means the interview should still capture the user's intended Developer Name string but surface it in the emitted prerequisites[] block so sfs-sobject-create can flag or defer the write.
+
+**Notes:** Skill body explicitly asks: "Which Skill Type does this preference rank
+within? Give me its Developer Name". This step lets the interview
+auto-complete against real records when they exist.
+
+#### `list-service-appointment-boolean-fields`
+
+List all Boolean fields on the ServiceAppointment sObject. Used by the interview for Relevance Groups whose basis is Service Appointment: the group's scoping Boolean must exist on this object. Filter response fields to those with `type == "boolean"`; expose both custom (`__c`) and standard names. Same probe as sibling sfs-work-rule-designer; both skills share the SA-boolean domain.
+
+**Call:** `GET /services/data/v68.0/sobjects/ServiceAppointment/describe`
+
+**Output:** From the describe response, take `fields[] where type == "boolean"`; project name + label + custom + defaultValue. Baseline on the target org: 18 boolean fields, 13 custom (all FSLMPPERF__-prefixed: Auto_Schedule__c, Emergency__c, InJeopardy__c, IsFillInCandidate__c, IsMultiDay__c, Pinned__c, Prevent_Geocoding_For_Chatter_Actions__c, Same_Day__c, Same_Resource__c, Schedule_over_lower_priority_appointment__c, UpdatedByOptimization__c, Use_Async_Logic__c, Virtual_Service_For_Chatter_Action__c) plus 5 standard (IsBundle, IsBundleMember, IsDeleted, IsManuallyBundled, IsOffsiteAppointment).
+
+**Notes:** Relevance Group scoped by Service Appointment requires the named
+Boolean to already exist here. If the interview participant names a
+field not in this set, prompt them to create it (via a metadata
+workflow) before continuing, or surface the missing field in the
+emitted prerequisites[] block.
+
+#### `list-service-territory-member-boolean-fields`
+
+List all Boolean fields on the ServiceTerritoryMember sObject. Used only by Relevance Groups whose basis is Service Territory Member: the group's scoping Boolean must exist on this object. Filter response fields to `type == "boolean"`. Same probe as sibling sfs-work-rule-designer.
+
+**Call:** `GET /services/data/v68.0/sobjects/ServiceTerritoryMember/describe`
+
+**Output:** A fresh FSL install has NO custom Boolean fields on ServiceTerritoryMember (only the standard IsDeleted). Every ServiceTerritoryMember-basis Relevance Group therefore depends on a customer-authored Boolean the user must create first. Empty custom-Boolean result means the skill must surface the dependency in the emitted prerequisites[] block (skill body example: "Create Boolean field Break_Group_France__c on Service Territory Member and set it true for French resources.").
+
+**Notes:** Contrast with ServiceAppointment (probe-confirmed 13 custom Booleans on
+target org from FSL package). Relevance Groups scoped by
+ServiceTerritoryMember are entirely user-authored.
+
+#### `list-existing-service-goals`
+
+Read existing `<NS>__Service_Goal__c` records to serve as reference examples during the interview. Useful when the upstream sfs-scheduling-policy-designer indicated a modification entry point — the interview can echo the current objectives on a policy as the baseline and let the user modify from there.
+
+**Call:** `GET /services/data/v68.0/query`
+
+**Inputs:**
+
+- `q` *(`String`)* — SOQL: `SELECT Id, Name, RecordType.DeveloperName FROM <NS>__Service_Goal__c ORDER BY RecordType.DeveloperName`. Substitute the namespace discovered by resolve-fsl-namespace.
+
+**Depends on:** `resolve-fsl-namespace`
+
+**Output:** A list of existing objectives. On the target org: 9 seed records covering all 10 RecordTypes except Objective_Custom_Logic. Use as reference material only; the emitted serviceObjectives[] block should reflect the interview's design, not blind-copy this list.
+
+**Notes:** Type discrimination is RecordType.DeveloperName; there is no
+FSLMPPERF__Type__c field on Service_Goal__c (parallels the sibling
+Work_Rule__c pattern).
+
+### Write operations
+
+#### `emit-service-objectives-block`
+
+Terminal step of the interview. Once the user confirms the objective
+set and weights, this skill emits a JSON block on the conversation
+channel of the form `{ serviceObjectives: [ { type, name, weight,
+params, relevanceGroup, rationale } ] }` plus the top-level
+`prerequisites[]` list carrying any user-authored dependencies (custom
+Booleans for STM-basis relevance groups, SkillType Developer Names,
+custom Resource Priority fields). Consumed by the delegate skill
+(sfs-sobject-create) to write the corresponding Service_Goal +
+Scheduling_Policy_Goal junction rows. This is a client-side workflow
+boundary, not an API call.
+
+**Depends on:** `enumerate-service-objective-record-types`, `describe-service-goal-schema`, `list-scheduling-policy-goal-junction`, `list-skill-types`, `list-service-appointment-boolean-fields`, `list-service-territory-member-boolean-fields`
+
+### Other operations
+
+#### `resolve-fsl-namespace`
+
+Resolve the installed FSL managed-package namespace prefix. The prefix is FSL in production and FSLQA / FSLMPTEST / FSLMPPERF in internal orgs. Every subsequent SOQL, describe, and JSON-block emit in this skill must use `<NS>__Service_Goal__c` and `<NS>__Scheduling_Policy_Goal__c` with the discovered prefix — do not hardcode FSLMPPERF.
+
+**Call:** `GET /services/data/v68.0/tooling/query`
+
+**Inputs:**
+
+- `q` *(`String`)* — SOQL: `SELECT SubscriberPackage.NamespacePrefix, SubscriberPackage.Name FROM InstalledSubscriberPackage`. No WHERE clause — the Tooling API rejects filters on NamespacePrefix. Query unfiltered; filter client-side.
+
+**Output:** From the records array, pick the first record whose SubscriberPackage.NamespacePrefix starts with `FSL` (case-sensitive). That NamespacePrefix is the runtime `<NS>` for this org. Empty result means FSL is not installed — abort with a message telling the user to install the FSL package.
+
+**Notes:** Pattern proven in siblings sfs-scheduling-policy-designer and
+sfs-work-rule-designer. On the current target org
+sfs-headless-skill-building, the discovered prefix is FSLMPPERF.
+
+#### `handoff-to-sobject-create`
+
+After emit-service-objectives-block, hand off to sfs-sobject-create.
+The delegate carries forward the accumulated design context: the parent
+policy from sfs-scheduling-policy-designer, the workRules[] block from
+sfs-work-rule-designer, and the serviceObjectives[] block from this
+skill, plus the discovered FSL namespace so the eventual writes use
+the right prefix. sfs-sobject-create owns all Salesforce API calls —
+this skill emits design values only and never creates records itself.
+
+**Depends on:** `emit-service-objectives-block`
+
+## Notes
+
+- **composition:** This is the third designer in a 3-designer + 1-deployer chain:
+  sfs-scheduling-policy-designer → sfs-work-rule-designer → THIS → sfs-sobject-create
+Each designer emits a JSON sub-block; the deployer writes the Salesforce
+records once the full chain is complete and the user approves. This
+skill's sub-block is serviceObjectives[], accompanied by any
+prerequisites[] entries the design implies.
+- **authority:** The 10 objective types the interview offers come from the RecordType
+DeveloperName values enumerated in step
+enumerate-service-objective-record-types. If an org customized its FSL
+install with additional record types (e.g. Group Nearby on newer
+versions), the interview should surface them; if an org disabled some,
+the interview should hide them.
+- **idempotency:** This skill emits data but does not write. Any downstream idempotency
+concerns are owned by sfs-sobject-create's write path (Service_Goal
+dedup by (policy, RecordType) or by name; Scheduling_Policy_Goal
+junction dedup by (Scheduling_Policy, Service_Goal)). The
+Weight__c(9,0) NOT NULL constraint in the junction schema forces the
+write path to supply an integer weight — the skill's Global Rule #1
+(ceiling-round every derived weight) ensures compliance.
+- **weight_derivation:** All weight-derivation math (Minimize Travel as anchor at 1000, ASAP
+crossover, Same Site vs ASAP / Preferred Resource, ×0.01 exception for
+Same Site's effective ×10 multiplier, etc.) is deterministic client-side
+arithmetic performed by the agent — no wire operation is involved.
+Ceiling-rounding to whole numbers is applied before emit so the
+Scheduling_Policy_Goal.Weight__c(9,0) NOT NULL constraint is satisfied
+at deploy time.
+- **wire_shape_reference:** Field-shape truths the interview + downstream deploy must respect,
+as read from the current sObject describes for these types:
+- FSLMPPERF__Service_Goal__c.FSLMPPERF__Custom_Type__c — picklist with
+  14 active values. The 10 objectives the skill offers map by
+  RecordType.DeveloperName; the picklist domain is a superset that also
+  includes Objective_Task_Priority and a legacy priority-by-distance
+  value whose stored string contains a non-ASCII combining character
+  (do NOT hand-type; read from describe if needed).
+- FSLMPPERF__Service_Goal__c.FSLMPPERF__Prioritize_Resource__c —
+  picklist(2), values `Least Qualified` (default) and `Most Qualified`.
+  Backs Skill Level objective's `mode` param.
+- FSLMPPERF__Service_Goal__c.FSLMPPERF__Gap_Duration__c — Number(4,0),
+  nillable=true. Skill's `minGapMinutes`.
+- FSLMPPERF__Service_Goal__c.FSLMPPERF__Resource_Priority_Field__c —
+  String(255), default formula `"fsl__priority__c"`.
+- FSLMPPERF__Scheduling_Policy_Goal__c.FSLMPPERF__Weight__c —
+  Number(9,0) NOT NULL. Upper bound therefore 999,999,999. The
+  anchor-relative weight math the skill computes stays well under this.
+- **junction_immutability:** FSLMPPERF__Scheduling_Policy_Goal__c has BOTH master-detail lookups
+(FSLMPPERF__Service_Goal__c and FSLMPPERF__Scheduling_Policy__c)
+marked updateable=false. A junction row's parent bindings are
+immutable post-create: to re-target an objective at a different policy
+or swap policy/objective the deployer must DELETE and re-CREATE the
+junction row. Cascade-delete=true on both lookups means deleting either
+parent removes the junction; FSLMPPERF__Weight__c itself is updateable
+and can be tuned in place after create.