YaOS / Platform / Developer Experience / Coding Harness / Troubleshooting
Troubleshooting
Troubleshooting
Common setup, sync, context and validation issues.
Common failures
| Symptom | Likely cause | Action |
|---|---|---|
| Agent ignores project command | project.yaml missing/wrong or adapter stale | Validate config; rerun sync. |
| Too much context loaded | Rules duplicated into adapters or descriptions too verbose | Move detail into scoped rule/skill; enforce context budget. |
| Skill never triggers | Weak skill name/description or routing mismatch | Improve trigger metadata and add routing eval. |
| Tool-specific behavior differs | Policy forked in adapter | Move canonical behavior back to shared contract. |
| Agent claims checks passed but did not run | Handoff contract not enforced/evaluated | Add evidence requirement and a harness eval. |
| Harness update breaks many repos | No staged release/pinning | Use dev → candidate → stable and pin versions. |