pattern-doc

Act as a UX researcher documenting a reusable design pattern.

Goal: Document a recurring UX pattern that solves a common problem across multiple screens or projects. The pattern spec should be general enough to reuse in future projects but specific enough to guide implementation. Follows templates/PATTERN_SPEC.md.

Mandatory context bootstrap (before any output):

• Read these sections in WORKFLOW_OPERATING_SYSTEM.md first:
  • ## LLM execution contract
  • ## Editor mode policy (mode definitions only; the tool mapping table is lazy-loaded in wos/editor-mode-mappings.md and needed only for non-Claude-Code tools)
  • ## Global output contract (including Adaptive handoff and Mode selection rule)
  • ## Cross-cutting workflow guardrails
• Bootstrap tiers (ADR-0025): the light-weight commands (branch-commit, what-next, where-we-at, slice-closure, compact-task-memory) may skip ## Editor mode policy good-fits lists and ## Cross-cutting workflow guardrails sequencing heuristics, reading only the mode definitions and the core guardrail rules (routing memory, command-less input triage, official command names, material change, no-op). The full tier is measured at 10530 tokens: the combined size of the four always-read WORKFLOW_OPERATING_SYSTEM.md sections listed above. That figure is asserted here in prose and no gate recomputes it, so it drifts every time the spec grows: it was declared at 9610 and measured at 10530 on 2026-08-10, a 9.6 per cent gap, and it will drift again unless re-measured with the same method (sum the four ^## sections, chars over 4). The reduced tier is a self-declared estimate of about 3,500 tokens for the trimmed subset above; it has not been independently re-measured by the same method, and should be read as an estimate rather than a fresh figure. The same reduced tier extends to the high-frequency execution commands implement-approved-slice and sync-task-state (v3 wave1 item D: the most-invoked commands pay the bootstrap most often; state-reconcile deliberately stays on the full tier, cross-artifact judgment needs the full guardrail context).
• Cache-amortized layer (ADR-0006): this bootstrap floor was DESIGNED as a cache-amortized cost rather than a per-command tax. ADR-0139 measured that the amortization is real but NOT controllable from here: the harness manages caching itself, there is no per-file or per-segment caching, and a command body is injected as a user message after the cached prefix. Whether this floor is cached is a property of the host, not of anything this repository can mark. Treat the figure below as a real per-invocation cost when reasoning about what a command carries. It sits in the prompt cache for the session and is paid at write cost once per cache TTL window, then at roughly 0.1x on cached reads inside that window. Account for it separately from any per-skill Load budget (the generated .claude/skills/<name>/SKILL.md body); the two are different layers and should not be summed into one figure.
• Session bootstrap reuse (skip-if-unchanged; v3 wave1 item D): WHEN this same conversation already performed this bootstrap read in an earlier turn that is still VISIBLE in the current context window AND WORKFLOW_OPERATING_SYSTEM.md has not changed since, the command MAY skip the re-read and cite the earlier one instead, emitting one Command transcript line: Bootstrap: reusing turn <N> read, WOS unchanged. This is a scoped exception to the context-budget re-fetch rule (wos/context-budget.md, "The re-fetch rule"), justified because the bootstrap sections are one large, static, byte-identical read repeated every turn rather than a variable tool result; the re-fetch rule still governs every other tool result without exception. VISIBLE means the bootstrap section text itself is still present and quotable in the window right now, not merely that the record of an earlier read exists. On a harness that clears, a tool result can be emptied while the record that the tool ran survives (ADR-0114); a command that finds only that record, without the section text still readable, has not satisfied VISIBLE and must re-read. Self-declared memory after a compaction never qualifies (re-read instead), and a stateless-per-turn harness is excluded. The auditable-skip rule applies: the transcript line is mandatory; a silent skip is invalid output.
• Resolving a relative wos/<topic>.md. Try the canonical workflow repository root FIRST, then the installed docs directory (~/.claude/workflow-docs/wos/ or ~/.cursor/workflow-docs/wos/). Name the root you resolved against in ### Command transcript, and say so explicitly when NEITHER resolved rather than continuing silently: several of these loads are declared MANDATORY, and a lazy load that resolved nowhere is otherwise indistinguishable in the output from one that was never needed. Repository first, because the installed copy is a snapshot that no sync prunes: preferring it would make an edit to wos/ invisible to every command until someone re-ran the installer.
• Read additional sections only when relevant to this command's role.
• Read the commands/ directory command inventory to ensure command names and availability are current.
• Align all routing recommendations and next-command suggestions with the current command set.
• Official next-command names only: every recommended next command (including the handoff Run now line) MUST be the basename of an existing commands/<name>.md file in this workflow repository. Never invent names. One exception: Run now: none with Mode: N/A declares that the chain has ended and no following command would be honest, defined in ## Global output contract (ADR-0126); use it only when nothing honest remains, never to end a chain that has a real next step.