---
name: short-kebab-slug
title: One-line title of the pitfall
severity: medium
area: packages/sync
date: 2026-06-29
tags: [runtime, sockets]
---

# NNNN — One-line title of the pitfall

> Template seed. Copy to `docs/lessons/NNNN-slug.md` (next free number) and fill in.
> `npm run ai:lessons` refreshes the ignored index after capture; the hook only checks.
> Severity: `low | medium | high | critical`. Distinct from an ADR — a lesson is
> *what failed and the takeaway*, NOT *why we chose X over Y* (that's `docs/decisions/`).

## What happened

What was attempted and how it went wrong. Be concrete — the symptom, the wasted path.

## Root cause

The underlying reason it failed (the thing that wasn't obvious up front).

## How to avoid

The takeaway, phrased as a rule for next time. This is what `find_lesson` surfaces.
Link related lessons/decisions: see `docs/decisions/NNNN-*.md`.