@uptimizr/agent-core 1.1.1 → 1.2.0

package/skills/weekly-scene-health/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: weekly_scene_health
+title: Weekly scene health
+description: >-
+  A weekly health check for a scene (or the whole project): a weighted health score with every
+  factor traced back to the metric behind it, what changed against last week, traffic, event mix,
+  performance, and the most-interacted meshes. USE FOR: the recurring "how is the scene doing?"
+  review, a scheduled weekly or monthly report, a first look at a project you do not know yet,
+  deciding which scene to investigate next. Trigger phrases: weekly report, scene health, how is
+  my scene doing, what changed this week, health check, monthly review, status report.
+tools:
+  - insight_scene_health
+  - insight_movers
+  - insight_baseline
+  - insight_significance
+  - insight_anomalies
+  - event_counts
+  - timeseries
+  - perf_summary
+  - top_meshes
+  - list_sessions
+  - query
+capabilities:
+  - query
+args:
+  - name: scene
+    required: false
+    description: Optional scene id to scope the analysis to (see the uptimizr://scenes resource).
+  - name: range
+    required: false
+    default: the last 7 days
+    description: The window to report on, in words — e.g. "the last 7 days", "June".
+---
+
+Give me a weekly health report for {{scope}} covering {{range}}.
+
+Work through the method below with the read-only tools it names, then summarise the findings.
+
+1. **Orient before you ask anything.** Read the `uptimizr://context` resource first: it gives the
+   real scene ids, region ids and custom-event names for this project, and tells you which metrics
+   are empty because their capture channel is off. Use its ids instead of inventing your own, and
+   never report a switched-off channel's zero as a finding.
+
+2. **Start from the score, not the numbers.** Call `insight_scene_health`{{#scene}} with
+   `scene="{{scene}}"`{{/scene}}: it scores each scene 0–100 over six weighted factors — perf
+   stability, jank, errors, dead clicks, coverage and XR abandonment — so you start from _which_
+   scene to look at. Open the lowest-scoring scene first, then the factor whose own score is
+   furthest below 50. Every factor names the `metric` behind it, its `raw` value and the project
+   `baseline` it was compared with, so the sentence you write is already in the row. 50 is the
+   project norm, not a pass mark, and a factor with `score: null` was not counted — its `note`
+   says why.
+
+3. **Find out what moved.** Call `insight_movers`{{#scene}} (`scene="{{scene}}"`){{/scene}}: it
+   compares every comparable metric with the previous equal window and ranks the changes by how
+   unusual each one is, so start from what actually moved instead of re-deriving it. Read
+   `direction` together with the sign of `delta` — a rise in a `down` metric (errors, dead clicks,
+   jank) is a regression — and do not report any row with `aboveMinSample: false`: its delta is
+   real arithmetic but not evidence.
+
+4. **Ask whether the new level is even unusual.** For each metric that moved, call
+   `insight_baseline` and compare the new value with `median` give or take a few `mad`, or with
+   the p10..p90 band. "Down 12 %" means nothing until you know the week-to-week spread.
+
+5. **Before calling any single change real, test it.** `insight_significance` reports the effect,
+   a 95 % interval and a p-value for one metric across the two windows. An interval that straddles
+   0 means you cannot tell yet, whatever the p-value says, and `powerNote` states what this much
+   data could have detected at all.
+
+6. **Put a date on it.** Call `insight_anomalies` (`metric=perf_summary`, then `error_heatmap`{{#scene}},
+   `scene="{{scene}}"`{{/scene}}, `window=28`): it returns the individual days that were out of line
+   (`spike` / `drop`) and the day a level changed and stayed changed (`shift`), with `contributor`
+   naming the mesh, channel or source holding most of the excess. Quote the `bucketStart` and the
+   `contributor` rather than saying "recently".
+
+7. **Fill in the picture.** `event_counts` for the per-event-type mix{{#scene}} (`scene="{{scene}}"`){{/scene}};
+   `timeseries` (`interval` ≈ 86400 s) for day-by-day volume and the average-FPS trend;
+   `perf_summary` for avg/min/p50 FPS; `top_meshes` for the most-interacted meshes; `list_sessions`
+   for how many sessions were recorded.
+
+8. **Drill with the DSL, not with arithmetic.** When a canned tool does not expose the filter you
+   need, use the single `query` tool: pick the `metric`, bound it with `range`, and set
+   `compare: { range: <previous week> }` so the collector returns
+   `{ current, previous, delta, deltaPct }` already joined — never run two queries and subtract
+   them yourself. `dimensions` regroups a portable count (event, mesh, input-source and gesture
+   tallies) without a new tool. Ask for `format: "summary"` on anything long or spatial: it comes
+   back as a bounded digest with shares, a plain-language `reading`, and a `drillQuery` per row you
+   can send straight back. If a result is surprising or empty, re-send it with `explain: true` and
+   read the plan before you report the number.
+
+## What to report
+
+- The score and the two or three factors that drag it down, each with the metric id behind it.
+- What moved, by how much, and whether it is outside the baseline — with the date the anomaly
+  scan put on it.
+- Traffic, event mix, FPS trend and the meshes people actually touch.
+
+Always carry the caveats into the text rather than dropping them: a row below its minimum sample
+(`aboveMinSample: false`), a metric whose capture channel the context document says is off, and any
+`meta.truncated` or `caveats` entry on a result you quoted. Say "not enough data to tell" when that
+is the honest answer.
+
+End with 2–3 concrete recommendations — each naming the scene, the mesh or the day it applies to.
+If an `annotate` tool is available, leave a dated note on the finding you want the next reader to
+see, and if `save_analysis` is available, store the report so next week's run has something to
+compare against. If a `pin_panel` tool is available, pin the panel behind the headline factor.

package/skills/xr-comfort-audit/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: xr_comfort_audit
+title: XR comfort & drop-off audit
+description: >-
+  Audit VR/AR comfort for a scene (or the whole project): rapid head rotation, locomotion style,
+  tracking quality, guardian/boundary contacts, input-source mix, and the short sessions that mean
+  someone took the headset off. USE FOR: motion-sickness complaints, immersive sessions that end
+  early, choosing a locomotion scheme, checking whether a play space is big enough. Trigger phrases:
+  XR comfort, VR motion sickness, why do people quit VR, headset drop-off, teleport vs smooth
+  locomotion, guardian boundary, hand tracking vs controllers.
+tools:
+  - xr_rotation
+  - xr_locomotion
+  - xr_abandonment
+  - xr_sources
+  - xr_tracking_quality
+  - xr_boundary_contacts
+  - boundary_heatmap_stats
+  - insight_scene_health
+  - insight_movers
+  - query
+capabilities:
+  - query
+args:
+  - name: scene
+    required: false
+    description: Optional scene id to scope the audit to (see the uptimizr://scenes resource).
+  - name: range
+    required: false
+    default: the last 7 days
+    description: The window to audit, in words — e.g. "the last 7 days", "since the XR release".
+---
+
+Audit XR/immersive comfort and drop-off for {{scope}} over {{range}}.
+
+Work through the method below with the read-only tools it names{{#scene}}, all scoped with
+`scene="{{scene}}"`{{/scene}}, and correlate the signals — no single one of them is a verdict.
+
+1. **Orient before you ask anything.** Read the `uptimizr://context` resource first. Every metric
+   below is gated on the **XR capture channel**: if the context document says it is off, these
+   tools return empty by design and the honest answer is "XR capture is not enabled here", not
+   "there is no comfort problem".
+
+2. **Rapid head rotation — the motion-sickness proxy.** `xr_rotation`{{#scene}} (`scene="{{scene}}"`){{/scene}}
+   gives the rate of fast head/view turns. High rates are a proxy, not a diagnosis: they can mean
+   discomfort-inducing camera work, or simply a scene that rewards looking around. Read it against
+   the next two signals before calling it.
+
+3. **Locomotion style and session span.** `xr_locomotion`{{#scene}} (`scene="{{scene}}"`){{/scene}}
+   gives the fly / navigate / teleport mix and how long each session lasted. Continuous (smooth)
+   locomotion paired with heavy rapid rotation is the classic uncomfortable combination; teleport
+   is the usual mitigation.
+
+4. **Did they take the headset off?** `xr_abandonment`{{#scene}} (`scene="{{scene}}"`){{/scene}}
+   finds immersive sessions that ended early. Early exits _plus_ one of the two signals above is
+   the finding; early exits on their own may just be a short demo.
+
+5. **Rule out the boring explanations first.** `xr_tracking_quality` catches tracking loss — an
+   exit caused by the headset losing its pose is not a comfort problem.
+   `xr_boundary_contacts` and `boundary_heatmap_stats` catch a play space that is too small or a
+   scene that pushes people into the guardian; that is a layout problem with a layout fix.
+
+6. **Who is playing.** `xr_sources`{{#scene}} (`scene="{{scene}}"`){{/scene}} gives the hand vs.
+   controller vs. gaze input split. Comfort conclusions differ by input source, and a shift in the
+   mix between two windows can move every other number without anything getting worse.
+
+7. **Put it in context.** `insight_scene_health` scores XR abandonment as one of its six weighted
+   factors, so it tells you whether this scene is unusual _for this project_;
+   `insight_movers`{{#scene}} (`scene="{{scene}}"`){{/scene}} tells you whether the comfort signals
+   moved against the previous equal window. Drop any row with `aboveMinSample: false`.
+
+8. **Cut it further with the DSL.** The single `query` tool takes a `metric`, a `range`, that
+   metric's filters, `dimensions` to regroup a portable count, and `compare: { range: <previous
+window> }` for `{ current, previous, delta, deltaPct }` already joined. `format: "summary"`
+   returns a bounded digest with a plain-language `reading`; `explain: true` returns the plan
+   instead of the rows and names every reason the answer might mislead — worth one call before
+   reporting a zero on a channel-gated metric.
+
+## What to report
+
+- The uncomfortable patterns you can actually evidence: heavy rapid rotation or continuous
+  locomotion paired with early exits, named per scene and per input source.
+- The alternatives you ruled out: tracking loss, boundary contacts, a short-by-design experience.
+- Comfort mitigations: teleport or snap-turn options, vignetting during movement, slower or
+  user-controlled camera motion, a larger required play space, or moving interactive content
+  inside the guardian.
+
+Carry the caveats: XR sessions are a small fraction of most projects' traffic, so say the session
+count next to every rate; the rotation and locomotion metrics are sampled (ADR 0012); and a metric
+whose channel is off is not a zero. Never turn one uncomfortable session into a trend.
+
+End with 2–3 concrete comfort changes, each tied to the scene and the locomotion or input mode it
+applies to. If an `annotate` tool is available, leave a note on the scene so the next audit can see
+what was tried; `save_analysis` keeps the before-picture to compare the fix against. If a
+`pin_panel` tool is available, pin the locomotion-comfort panel.