Update to Unity Essentials

{
  "description": "Investigate, reproduce, isolate, explain, and validate bugs in an existing Unity project. Use when the user reports exceptions, incorrect behavior, regressions, visual glitches, multiplayer desync, input problems, scene or prefab issues, build failures, performance regressions, save corruption, intermittent failures, or other Unity defects. Gather evidence before editing, distinguish symptoms from causes, test hypotheses one at a time, apply the smallest justified fix, and validate the root cause.",
  "included_files": [
    {
      "relative_path": "FILE-INVENTORY.md",
      "size_in_bytes": 1220
    },
    {
      "relative_path": "README.md",
      "size_in_bytes": 681
    },
    {
      "relative_path": "foundations/change-safety.md",
      "size_in_bytes": 1014
    },
    {
      "relative_path": "foundations/evidence-first-debugging.md",
      "size_in_bytes": 1474
    },
    {
      "relative_path": "foundations/hypothesis-management.md",
      "size_in_bytes": 1411
    },
    {
      "relative_path": "foundations/instrumentation.md",
      "size_in_bytes": 1097
    },
    {
      "relative_path": "foundations/reproduction-and-baselines.md",
      "size_in_bytes": 1298
    },
    {
      "relative_path": "frameworks/networking/fishnet.md",
      "size_in_bytes": 332
    },
    {
      "relative_path": "frameworks/networking/fusion.md",
      "size_in_bytes": 644
    },
    {
      "relative_path": "frameworks/networking/mirror.md",
      "size_in_bytes": 392
    },
    {
      "relative_path": "frameworks/networking/netcode-for-gameobjects.md",
      "size_in_bytes": 497
    },
    {
      "relative_path": "frameworks/rendering/hdrp.md",
      "size_in_bytes": 395
    },
    {
      "relative_path": "frameworks/rendering/urp.md",
      "size_in_bytes": 440
    },
    {
      "relative_path": "references/capability-requirements.md",
      "size_in_bytes": 1014
    },
    {
      "relative_path": "references/hypothesis-log-template.md",
      "size_in_bytes": 750
    },
    {
      "relative_path": "references/reproduction-template.md",
      "size_in_bytes": 328
    },
    {
      "relative_path": "references/root-cause-report-template.md",
      "size_in_bytes": 388
    },
    {
      "relative_path": "references/validation-strategy.md",
      "size_in_bytes": 1148
    },
    {
      "relative_path": "specializations/build-and-platform.md",
      "size_in_bytes": 539
    },
    {
      "relative_path": "specializations/editor-and-imports.md",
      "size_in_bytes": 551
    },
    {
      "relative_path": "specializations/exceptions-and-crashes.md",
      "size_in_bytes": 698
    },
    {
      "relative_path": "specializations/gameplay-and-state.md",
      "size_in_bytes": 549
    },
    {
      "relative_path": "specializations/input.md",
      "size_in_bytes": 506
    },
    {
      "relative_path": "specializations/intermittent-and-timing.md",
      "size_in_bytes": 764
    },
    {
      "relative_path": "specializations/multiplayer.md",
      "size_in_bytes": 633
    },
    {
      "relative_path": "specializations/performance.md",
      "size_in_bytes": 558
    },
    {
      "relative_path": "specializations/physics-and-movement.md",
      "size_in_bytes": 621
    },
    {
      "relative_path": "specializations/rendering-and-vfx.md",
      "size_in_bytes": 596
    },
    {
      "relative_path": "specializations/save-and-persistence.md",
      "size_in_bytes": 513
    },
    {
      "relative_path": "specializations/scenes-prefabs-serialization.md",
      "size_in_bytes": 554
    },
    {
      "relative_path": "specializations/ui-and-localization.md",
      "size_in_bytes": 556
    }
  ],
  "name": "unity-bug-investigation",
  "skill_md_contents": "---\nname: unity-bug-investigation\ndescription: Investigate, reproduce, isolate, explain, and validate bugs in an existing Unity project. Use when the user reports exceptions, incorrect behavior, regressions, visual glitches, multiplayer desync, input problems, scene or prefab issues, build failures, performance regressions, save corruption, intermittent failures, or other Unity defects. Gather evidence before editing, distinguish symptoms from causes, test hypotheses one at a time, apply the smallest justified fix, and validate the root cause.\n---\n\n# Unity Bug Investigation\n\nInvestigate Unity defects systematically and with evidence.\n\nDo not begin by guessing a fix from the symptom alone. Establish the baseline,\nreproduce the issue when possible, collect relevant evidence, formulate a small\nset of hypotheses, test them one at a time, and only then implement the smallest\njustified correction.\n\n## Surface Limits\n\nIf the current surface is Chat mode without an attached workspace, repository files, logs, screenshots, or local filesystem access, do not claim that you investigated the project. Explain that Unity Essentials can help reason from evidence the user provides, but real bug investigation requires Codex with the Unity project folder open or enough logs/files pasted into chat.\n\nIf Codex has a workspace or local files available, collect project evidence before forming a root-cause claim.\n\n## Primary outcome\n\nProduce one of these outcomes:\n\n1. A confirmed root cause and validated fix.\n2. A narrowed cause with strong supporting evidence and a safe next experiment.\n3. A documented blocker explaining why the issue could not be reproduced or\n   verified.\n\nDo not claim a root cause unless evidence supports it.\n\n## Relationship with project onboarding\n\nLook for current project context before investigating:\n\n- `Docs/AI/UnityProjectContext.md`\n- `Docs/UnityProjectContext.md`\n- architecture documentation\n- repository instructions\n- recent change notes\n\nIf the project is unfamiliar and context is missing, use the\n`unity-project-onboarding` workflow first, but keep the onboarding focused on\nthe systems relevant to the defect.\n\n## Knowledge routing\n\nThe skill contains:\n\n- `foundations/`: investigation principles used across bug types\n- `specializations/`: defect-area guidance\n- `frameworks/`: framework-specific debugging guidance\n- `references/`: templates, evidence standards, validation, and safety\n\nRead only the guidance that materially applies.\n\n### Mandatory foundations\n\nFor every investigation, read:\n\n- `foundations/evidence-first-debugging.md`\n- `foundations/hypothesis-management.md`\n- `foundations/reproduction-and-baselines.md`\n\nRead `foundations/instrumentation.md` when adding logs, probes, captures, or\ntemporary diagnostics.\n\nRead `foundations/change-safety.md` before modifying serialized assets,\nproject settings, packages, scenes, prefabs, or save formats.\n\n### Specialization routing\n\n| Defect area | File |\n|---|---|\n| Exceptions and crashes | `specializations/exceptions-and-crashes.md` |\n| Gameplay and state bugs | `specializations/gameplay-and-state.md` |\n| Input issues | `specializations/input.md` |\n| UI and localization | `specializations/ui-and-localization.md` |\n| Multiplayer and desync | `specializations/multiplayer.md` |\n| Physics and movement | `specializations/physics-and-movement.md` |\n| Rendering, shaders, and VFX | `specializations/rendering-and-vfx.md` |\n| Performance regressions | `specializations/performance.md` |\n| Save and persistence issues | `specializations/save-and-persistence.md` |\n| Scenes, prefabs, and serialization | `specializations/scenes-prefabs-serialization.md` |\n| Build and platform failures | `specializations/build-and-platform.md` |\n| Editor tooling and imports | `specializations/editor-and-imports.md` |\n| Intermittent or timing bugs | `specializations/intermittent-and-timing.md` |\n\nA defect may require more than one specialization.\n\n### Framework routing\n\nRead framework guidance only when the project actively uses it.\n\n| Framework | File |\n|---|---|\n| Photon Fusion | `frameworks/networking/fusion.md` |\n| Netcode for GameObjects | `frameworks/networking/netcode-for-gameobjects.md` |\n| Mirror | `frameworks/networking/mirror.md` |\n| FishNet | `frameworks/networking/fishnet.md` |\n| URP | `frameworks/rendering/urp.md` |\n| HDRP | `frameworks/rendering/hdrp.md` |\n\n### Resolution priority\n\nWhen guidance conflicts:\n\n1. Explicit user constraints\n2. Repository instructions\n3. Evidence and reproducibility\n4. Data integrity and safety\n5. Framework-specific guidance\n6. Defect specialization\n7. Generic investigation guidance\n\n## Core principles\n\n1. Reproduce before fixing when practical.\n2. Distinguish symptoms from causes.\n3. Prefer direct evidence over intuition.\n4. Record the current baseline.\n5. Change one meaningful variable at a time.\n6. Keep temporary diagnostics narrow and removable.\n7. Avoid speculative broad refactors.\n8. Preserve user data and project assets.\n9. Verify the fix against the original reproduction.\n10. Check for regressions around the corrected behavior.\n11. Do not hide uncertainty.\n12. Do not claim success from compilation alone.\n\n## Phase 1: Convert the report into a defect contract\n\nExtract:\n\n- observed behavior\n- expected behavior\n- affected user or system\n- frequency\n- first known occurrence\n- environment\n- platform\n- scene or mode\n- steps already attempted\n- error messages\n- stack traces\n- recent related changes\n- severity\n- data-loss or crash risk\n\nWhen the report is incomplete, infer only the smallest missing context.\n\nDo not treat a vague report such as “movement is broken” as a complete\nreproduction.\n\n## Phase 2: Establish the baseline\n\nBefore editing:\n\n- inspect current Console messages\n- identify pre-existing failing tests\n- inspect the relevant current code\n- inspect recent changes when Git history is available\n- record relevant project and package versions\n- confirm the active scene, prefab, platform, and Editor instance\n- preserve representative failing data or save files when relevant\n\nDo not clear the Console before recording useful baseline evidence.\n\n## Phase 3: Reproduce\n\nAttempt the narrowest reliable reproduction.\n\nPrefer:\n\n1. Existing automated failing test\n2. Minimal EditMode or PlayMode test\n3. Existing reproduction scene\n4. Existing gameplay scene with exact steps\n5. Target platform or device reproduction\n6. Controlled synthetic reproduction\n\nRecord:\n\n- exact steps\n- observed result\n- frequency\n- required timing\n- required data\n- platform differences\n- Console output\n- screenshots or captures when relevant\n\nIf reproduction fails, do not immediately modify code. Compare environment,\nstate, configuration, and version differences first.\n\n## Phase 4: Classify the defect\n\nClassify the issue by likely mechanism:\n\n- deterministic logic error\n- invalid state transition\n- missing reference\n- lifecycle or initialization order\n- serialization mismatch\n- asset configuration\n- timing or race condition\n- physics-step mismatch\n- authority or replication error\n- stale cache\n- data migration\n- rendering pipeline incompatibility\n- platform-specific API\n- package or version regression\n- performance saturation\n- user configuration\n- external service failure\n\nClassification guides evidence gathering. It does not confirm the cause.\n\n## Phase 5: Build hypotheses\n\nUse `references/hypothesis-log-template.md`.\n\nKeep a small ranked set of plausible hypotheses.\n\nEach hypothesis must include:\n\n- claim\n- supporting evidence\n- contradicting evidence\n- predicted observation\n- cheapest discriminating test\n- current status\n\nPrefer tests that distinguish between multiple hypotheses.\n\nAvoid collecting large amounts of data without a decision it can inform.\n\n## Phase 6: Inspect the execution path\n\nTrace the relevant flow:\n\n- entry point\n- initialization\n- state owner\n- dependencies\n- input or event source\n- transformations\n- side effects\n- presentation\n- cleanup\n\nIdentify where expected and observed behavior diverge.\n\nUse representative code and object inspection rather than reading the whole\nproject.\n\n## Phase 7: Instrument narrowly\n\nAdd temporary instrumentation only when existing evidence is insufficient.\n\nGood instrumentation:\n\n- records state transitions\n- identifies ownership\n- timestamps key events\n- records object identity\n- records scene and lifecycle state\n- captures authority and network tick\n- captures input values\n- captures serialized configuration\n- records exact branch decisions\n\nAvoid:\n\n- logs every frame without filtering\n- broad exception swallowing\n- permanent debug flags scattered across production code\n- instrumentation that changes timing significantly\n- logging secrets or personal data\n\nMark temporary diagnostics clearly and remove them before completion unless the\nproject benefits from retaining them.\n\n## Phase 8: Test hypotheses one at a time\n\nFor each hypothesis:\n\n1. Predict the result.\n2. Run the smallest discriminating experiment.\n3. Record the actual result.\n4. Update the hypothesis status.\n5. Do not change unrelated variables.\n6. Stop pursuing contradicted hypotheses.\n7. Add a new hypothesis only when evidence warrants it.\n\nA successful workaround does not automatically prove the root cause.\n\n## Phase 9: Confirm the root cause\n\nA root cause is confirmed when:\n\n- evidence explains the original symptom\n- the mechanism is understood\n- a targeted change removes the reproduction\n- reversing or isolating the change restores the failure when practical\n- nearby scenarios remain valid\n- competing plausible hypotheses are sufficiently ruled out\n\nWhen full confirmation is impossible, report the strongest supported cause as\nlikely, not confirmed.\n\n## Phase 10: Implement the smallest justified fix\n\nThe fix should:\n\n- address the cause, not only mask the symptom\n- follow project architecture\n- preserve serialized data\n- avoid unrelated refactoring\n- include guards only at meaningful boundaries\n- include migration when data formats changed\n- maintain multiplayer authority\n- preserve existing public behavior unless the bug itself is that behavior\n\nDo not add broad null checks merely to suppress an invalid state.\n\nDo not catch and ignore exceptions to make the Console quiet.\n\n## Phase 11: Add regression coverage\n\nPrefer a regression test that fails before the fix and passes after it.\n\nChoose:\n\n- EditMode for deterministic logic\n- PlayMode for lifecycle, scene, physics, and engine behavior\n- multi-peer or framework tests for multiplayer\n- representative old data for save migration\n- platform build or device tests for environment-specific failures\n\nIf automated regression coverage is impractical, create an exact manual\nverification procedure.\n\n## Phase 12: Validate the fix\n\nValidate:\n\n1. Original reproduction no longer fails.\n2. Relevant tests pass.\n3. Unity compiles without new errors.\n4. Console has no new related warnings.\n5. Nearby behavior still works.\n6. Repeated execution remains stable.\n7. Scene reload, disable, destruction, or despawn works when relevant.\n8. Target platform behavior is checked when required.\n\nUse `references/validation-strategy.md`.\n\n## Phase 13: Review diagnostics and diff\n\nBefore completion:\n\n- remove temporary logging\n- remove experimental branches\n- remove test assets not intended for commit\n- inspect all changed files\n- confirm no unrelated serialization changes\n- confirm no tests were disabled\n- confirm no warnings were hidden\n- preserve useful permanent assertions or diagnostics only when justified\n\n## Prohibited behavior\n\nDo not:\n\n- guess a root cause from one symptom\n- make broad refactors before reproduction\n- clear evidence before recording it\n- disable failing tests\n- swallow exceptions\n- add retries without understanding failure\n- add delays to hide timing problems without evidence\n- reset user data as the default fix\n- regenerate scenes or prefabs wholesale\n- change package versions casually\n- blame Unity, a package, or a platform without evidence\n- claim a multiplayer fix from one local instance\n- claim a performance fix without measurement\n- leave excessive logs in hot paths\n- expose secrets in bug reports\n\n## Definition of done\n\nThe investigation is complete when:\n\n- observed and expected behavior are documented\n- reproduction status is known\n- baseline evidence is recorded\n- relevant hypotheses were tested\n- root cause is confirmed or uncertainty is explicit\n- the smallest justified fix is applied when possible\n- regression coverage exists or manual verification is precise\n- original reproduction is retested\n- nearby behavior is checked\n- temporary diagnostics are removed\n- changed files are reviewed\n- remaining risk is documented\n\n## Final response\n\nReturn:\n\n### Symptom\n\nState the observed and expected behavior.\n\n### Root cause\n\nState confirmed, likely, or unresolved cause with evidence.\n\n### Fix\n\nSummarize the smallest applied correction.\n\n### Changed files\n\nList important changed files and purpose.\n\n### Validation\n\nState exact reproduction, tests, compilation, runtime, and platform checks.\n\n### Remaining risks\n\nList unresolved uncertainty or follow-up checks.\n"
}