seaworthy

seaworthy

!checklist init ${CLAUDE_SKILL_DIR} --force

A seaworthy ship isn't one that sails in calm water — every hull does that — it's one that keeps the crew alive in the storm. A feature is the same: anyone can write the happy path; its real quality is entirely in how it catches the user when the system breaks, returns nothing, runs slow, or gets mis-clicked. seaworthy is the fourth skill of the surface suite, the lens you hold while building, and it carries one inverted discipline — the happy path is about 40% done, not 90%, so you design the unhappy paths first. Its product is feature slices that are each complete: data → state → view → and the loading / error / empty / edge states, with accessibility and a performance budget built in. It runs across gated stages and will not advance past a GATE until the checklist tool clears it — order enforced, substance yours.

The reversal that governs everything here: what you ship is a maintained illusion, not a correct program. "Direct manipulation" — that you are dragging the file, flipping the switch — is a lie; you are sending a message to a possibly-distant, possibly-failing, thoroughly asynchronous system. The real craft of the frontend is maintaining a coherent causal story in the user's head against the machine's true asynchronous, failure-prone nature. Seen that way, a whole class of "best practices" stops being polish and becomes illusion-maintenance: optimistic updates tell the user the likely truth before it's confirmed, so "I clicked → nothing → then it moved" never happens; animation is causal narrative, telling the user this new thing came from that click; honest loading and error states are the confession when the illusion can't hold. So the unhappy paths are not a TODO list for later — they are the product, and they are designed first, because the polish pass that's supposed to add them never gets the time, and when the deadline bites, it's the unhappy paths that get cut.

This is where the agent era bites:

• The agent ships the happy path and calls it done. It writes the fetch-and-render, the tests pass on the data case, and it stops — leaving loading/error/empty/edge as // TODO, because the happy path turns green and the failure states earn no reward. But the failure states are where the user's trust is won or lost. The agent's "done" is the 40% mark.
• The agent fakes nothing about failure honestly. A silent optimistic update with no rollback is a trust-eroding lie; an error that drops the user's input is a betrayal it won't feel. It treats animation as decoration (adding motion that lies about causality) and leaves accessibility for "later" (a cost multiple of building it in).
• The agent never feels "janky." Perception performance lives in a nervous system the agent has no access to — a spinner that flashes for 50ms, a list that re-sorts on every keystroke, a layout that shifts — so a perf budget must be a hard CI number, not a feeling it's trusted to have.

Read references/the-membrane.md first — the heart; for seaworthy, lean on the mind axis (the membrane: direct-manipulation-is-a-lie, the product as maintained illusion, the two conflicting "corrects" — machine-correct wants no unconfirmed data, mind-correct wants the reassuring optimistic lie). Load at the start, re-check at every gate.

Speak the user's language. The calls here are the user's — is this action safe to fake optimistically, is this animation honest, what does "feels right" mean for this interaction. Read their fluency and gloss a term on first use (optimistic UI / rollback, skeleton screen, stale-while-revalidate, causal animation, prefers-reduced-motion, focus management, INP/LCP/CLS, a performance budget). A judgment about "feel" the user can't weigh in on is taste imposed, not shared.