{Documentation} Project Aria Plugins - Add mandatory troubleshooting gates to client-sdk and mps skills

Summary:
Agents tend to ignore official troubleshooting documentation when encountering errors, instead trying to debug from first principles or training data. This leads to misdiagnosis of Aria-specific issues like sandbox blocks, cert mismatches, thermal shutdowns, and health check rejections.

Added mandatory troubleshooting gates to both client-sdk and mps skills using the same proven MANDATORY + anti-pattern format from the Client SDK pre-flight checklist. Each gate requires the agent to consult the troubleshooting section and official docs before attempting its own diagnosis, with explicit anti-patterns to prevent rationalization.

Also linked the correct official troubleshooting pages: client-sdk to https://facebookresearch.github.io/projectaria_tools/gen2/ark/support/sdk, mps to https://facebookresearch.github.io/projectaria_tools/gen2/ark/support/mps (previously mps had the wrong URL pointing to the sdk page).

___

Differential Revision: D106732348

fbshipit-source-id: bd1dfa22cf3d220db8413ecaeead7b2f8a5ba30c

Author: kongchen1992

projectaria_ark_plugin/skills/client-sdk/SKILL.md

@@ -109,15 +109,24 @@ The CLI `aria_gen2 streaming start` auto-installs a persistent cert if none exis
 - **Streaming before viewer**: The viewer connects to an active stream — start streaming first.
 - **Viewer requires persistent certs**: The viewer only loads certs from `~/.aria/streaming-certs/persistent/`. Streaming with ephemeral certs will silently fail to display in the viewer.
 - **Guest WiFi won't work**: Guest networks block peer-to-peer communication required for streaming.
+- **Errors → Troubleshooting section FIRST**: When any SDK command fails or returns unexpected output, you MUST check the Troubleshooting section below and the official troubleshooting page before attempting your own diagnosis. Do not guess root causes from training data — Aria errors have Aria-specific causes that generic debugging will miss.
 
 ## Gen1 vs Gen2
 
 The pip package includes both. Gen1 uses `aria` CLI and `import aria.sdk`. Gen2 uses `aria_gen2` CLI and `import aria.sdk_gen2`. Type stubs: `sdk.pyi` (Gen1), `sdk_gen2.pyi` (Gen2). Gen1 and Gen2 SDK are **NOT interchangeable**.
 
-## Troubleshooting
+## ⛔ MANDATORY: Troubleshooting
 
-- **First step**: `aria_doctor` — configures ports and diagnoses connectivity.
-- **More**: https://facebookresearch.github.io/projectaria_tools/gen2/ark/support/sdk
+**When any Client SDK command fails or returns unexpected output, you MUST consult this section and the official troubleshooting page BEFORE attempting your own diagnosis.** This is not optional. Aria failures have Aria-specific root causes (sandbox blocks, cert mismatches, thermal shutdowns, mDNS issues) that generic debugging will misdiagnose.
+
+Anti-patterns:
+- ❌ "I think I know what's wrong" — check the table first; your guess wastes the user's time when the documented fix is one row away.
+- ❌ "Let me try a different approach" — the documented fix exists for a reason. Try it before improvising.
+- ❌ "This looks like a generic Python/network error" — it almost certainly has an Aria-specific cause.
+
+**Resources**:
+- **First step always**: `aria_doctor` — configures ports and diagnoses connectivity.
+- **Official troubleshooting page**: https://facebookresearch.github.io/projectaria_tools/gen2/ark/support/sdk — covers symptoms not listed below.
 
 ### Common Issues
 

projectaria_ark_plugin/skills/mps/SKILL.md

@@ -76,10 +76,20 @@ See the data formats docs for exact CSV column definitions, coordinate conventio
 
 On-device eye gaze and VIO are embedded in the VRS during recording (accessible via PAT Tutorial_4 and Tutorial_5). Cloud MPS produces substantially better results using offline algorithms — higher accuracy for both SLAM and hand tracking. See the benchmarks page for quantitative comparisons.
 
-## Troubleshooting
+## ⛔ MANDATORY: Troubleshooting
+
+**When any MPS command fails, returns unexpected output, or produces low-quality results, you MUST consult this section and the official troubleshooting page BEFORE attempting your own diagnosis.** This is not optional. MPS failures have MPS-specific root causes (health check rejections, insufficient recording length, coordinate frame mismatches) that generic debugging will misdiagnose.
+
+Anti-patterns:
+- ❌ "I think I know what's wrong" — check the list below and the official page first; your guess wastes the user's time when the documented fix is right here.
+- ❌ "Let me try reprocessing" — understand WHY it failed first. Blindly rerunning with `--force` wastes upload time and quota.
+- ❌ "This looks like a generic upload/network error" — MPS has specific retry and resumable upload logic. Check the CLI guide before improvising.
+
+**Official troubleshooting page**: https://facebookresearch.github.io/projectaria_tools/gen2/ark/support/mps — covers symptoms not listed below.
+
+### Common Issues
 
 - Check `summary.json` for per-service status (SUCCESS/WARNING/ERROR) and quality metrics
 - MPS requires a valid VRS health check — fix health check issues first
 - Short recordings (<30s) may lack enough data for SLAM loop closure
 - Featureless environments, pure rotation, or extreme motion blur degrade SLAM quality
-- Docs: https://facebookresearch.github.io/projectaria_tools/gen2/ark/support/sdk