spacexun2/winpitfalls

winpitfalls — agent skill (reference integration)

EXPERIMENTAL reference, not a distribution. This file teaches an agent when and how to consult winpitfalls. It is deliberately thin: the knowledge lives in the rule base, never here. Do not copy rule content into skills — this protocol is the ONLY thing an agent should preload; the cards themselves arrive just-in-time, one action at a time.

When to consult

You are working on Windows (os windows, shells git-bash / powershell / pwsh / cmd / wsl).

1. Before running a shell command whose first token is a native Windows executable you do not know to be MSYS-safe (robocopy, taskkill, …): consult preflight.
2. After a command exits non-zero and the tool is one with documented non-failure exit semantics (e.g. robocopy): consult outcome before declaring failure or retrying.
3. After a real failure with error text available: consult match with as much environment context as you can provide.

How to call

# 1. preflight — before execution
winpitfalls check --phase preflight --os <os> --shell <shell> --runtime <runtime?> --cmd "<command>"

# 2. outcome — after a suspicious exit
winpitfalls check --phase outcome --os <os> --tool <tool> --exit-code <n>

# 3. failure — recovery with evidence
winpitfalls match --stdin --os <os> --shell <shell> < error.txt

Prefer --json when consuming programmatically:

{ "result": "guidance | clear | insufficient", "phase": "preflight", "cards": [ ... ] }

How to interpret

• guidance — act on the cards. For preflight, prefer the card's replacement (machine-usable safer form) and re-check it once: a correct guardrail must answer clear for its own advice. If it warns again, the guardrail is broken — file a misdiagnosis issue instead of looping.
• clear — the declared scope was fully confirmed and nothing applies. Proceed normally.
• insufficient — this is not a clear. Nothing was checked. Supply the missing bounds (--os/--shell/--runtime/--tool/--env) and re-run.

Hard rules

• Never execute a fix automatically. All fixes in cards are manual steps.
• Never kill a process or free a port before identifying the holder, even when a diagnosis looks obvious (see WP-PROC-004).
• Do not retry on ok-nonstandard outcome cards; check the actual goal state instead.
• If winpitfalls is not installed, say so and continue without inventing its output.