Skill: workspace-troubleshooting

4. Keep SKILL.md as routing guidance; put detailed runbooks in references

• Keep core rules high-level and stable.
• Put command-level recovery steps (including shell/cwd procedures) in references/* and link them from this file.

5. Use short recovery checklists for repeated failure patterns

• Prefer explicit, ordered mini-checklists (symptom → checks → safe remediation → validation rerun).
• Keep checklist steps minimal and reversible; avoid mixing multiple failure classes in one checklist.

Progressive disclosure (read only what you need)

If npm install/ci fails on Windows with EPERM/EBUSY and locked native modules:

• Read references/windows-npm-eperm-locks.md

If you see “external changes” (formatter/user/tool edits) and need to decide whether to pause:

• Read references/external-changes-triage.md

If the user reports missing changes or your view doesn’t match theirs:

• Read references/stale-view-or-branch-mismatch.md

If failures might be caused by persistent shell cwd drift:

• Read references/persistent-shell-cwd-normalization.md

How to contribute new troubleshooting knowledge

When you discover a reusable troubleshooting tip, propose it in this format (staged repo-locally):

• Title:
• Symptoms:
• Likely causes:
• Safe steps (ordered):
• Evidence to capture:
• Caveats / rollback:
• Scope (OS/toolchain/repo type):