5chan/docs/agent-playbooks/known-surprises.md

Known Surprises

This file tracks repository-specific confusion points that caused agent mistakes.

Entry Criteria

Add an entry only if all are true:

• It is specific to this repository (not generic advice).
• It is likely to recur for future agents.
• It has a concrete mitigation that can be followed.

If uncertain, ask the developer before adding an entry.

Entry Template

### [Short title]

- **Date:** YYYY-MM-DD
- **Observed by:** agent name or contributor
- **Context:** where/when it happened
- **What was surprising:** concrete unexpected behavior
- **Impact:** what went wrong or could go wrong
- **Mitigation:** exact step future agents should take
- **Status:** confirmed | superseded

Entries

Portless breaks Windows installs

• Date: 2026-03-04
• Observed by: Codex
• Context: GitHub Actions Test Windows dependency install on windows-2022
• What was surprising: portless@0.5.2 is a local dev-only tool, but keeping it in devDependencies makes yarn install fail on Windows because the package declares win32 unsupported.
• Impact: Windows CI fails before build steps run, even though the app does not need portless there.
• Mitigation: Keep portless in optionalDependencies and make yarn start fall back to direct vite startup when portless is unavailable.
• Status: confirmed