docs: add surprise-handling workflow and known-surprises playbook

docs/agent-playbooks/known-surprises.md

@@ -0,0 +1,31 @@
+# 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
+
+```md
+### [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
+
+No confirmed surprises logged yet.