shift: Skill for Claude Code

/docs — Update or Create Module Documentation

The goal is documentation that helps agents and contributors understand constraints they cannot discover by reading source code.

Before writing

1. Read docs/architecture/index.md to find the canonical doc for the subsystem
2. Read the current DOCS.md if one exists
3. Read the module's source code to understand what has actually changed
4. If creating a new DOCS.md, confirm with the user first — this skill defaults to updating existing docs

DOCS.md section order

Every DOCS.md follows this structure. Omit empty sections but preserve the order.

# Module Name

One-sentence purpose.

## Architecture Invariants

## Codemap

## Key Types

## How it works

## Workflow recipes

## Gotchas

## Verification

## Related

Writing each section

Architecture Invariants

This is the most valuable section because it captures knowledge that is invisible in code. A contributor can read every line of source and still violate an invariant, because invariants describe absences, performance motivations, and semantic distinctions that only make sense with historical context.

Each invariant states a rule and explains why it exists:

Architecture Invariant: Rust is never touched during the draft preview hot path. SourceEditDraft.previewPositionPatch() applies a sparse patch to local reactive geometry only. Rust sees the final sparse patch once when commit() calls GlyphSource.commitPositionPatch(). This exists because round-tripping full glyph values for thousands of points per frame causes long frames and GC pressure.

Good invariants describe:

• What never happens and why ("X never imports Y because Z")
• Performance-motivated design choices ("uses flat arrays, never JSON, because Y")
• Semantic distinctions invisible in types ("$glyph fires on identity changes, not data changes")

Bad invariants just restate what the code does ("X calls Y", "X extends Z"). If you can see it by reading the source, it does not belong here.