@nurix/etna 0.18.19 → 0.18.20

package/data/harnesses/code/skills/design/references/introspect.md

@@ -0,0 +1,100 @@
+# Introspect
+
+The workflow that explains **why** a UI isn't working. Loaded when the front gate routes to introspect. Diagnoses with the shared engine (`diagnosis.md`); hands findings to `improve.md` on consent. Reads code — never edits it.
+
+## The deliverable is understanding
+
+Introspect produces a causal explanation, not a fix. The badness a user reports is always felt in **Perception** — the table looks noisy, the page feels heavy, nothing tells you where to look. Its cause almost always lives one layer down, in **Structure** (how it's built) or **Behavior** (how it responds). The run's job is to walk that chain and name every link, so the reader finishes understanding not just *what* is wrong but *why the thing they felt is produced by the thing they didn't see*.
+
+## The run
+
+1. **Ask the reader.** One question, before anything else (below).
+2. **Diagnose** with `diagnosis.md`: passes run causes-first — Structure → Behavior → Perception — producing severity-ranked canonical findings. Introspect invents no diagnosis of its own.
+3. **Explain** each finding as a causal chain narrated the other way: from where the badness is felt (Perception) down to where its cause lives (Structure or Behavior).
+4. **Render** every finding in the reader's register.
+5. **File** the dated report; **offer** the improve handoff.
+
+## The reader question
+
+Asked at invocation, every run, verbatim:
+
+> Who is reading this — a designer, a developer, or a PM/general reader?
+
+Never inferred from the brief. Never a stored default carried from a prior run — ask again every time. Asking costs a beat and is never wrong; a silent guess about the reader is how one diagnosis turns into the wrong three sentences.
+
+The register is presentation only. It changes how a finding is *said*, never what the finding *is* — it is not an axis on the UI or on the diagnosis.
+
+## The three registers
+
+One diagnosis, three renderings. Same evidence, same fix, same severity — never three different opinions.
+
+- **Designer** — the untranslated finding, in design language: dimensions, hierarchy, the causal chain as-is. No translation; the finding is already in their tongue.
+- **Developer** — the finding compiled to code-speak: the token, the file, the line site, the exact edit, and whether it stays within existing levers.
+- **PM / general reader** — the finding translated to outcomes: what the operator loses today, what changes after the fix, and roughly what it costs.
+
+### Worked example — one finding, three ways
+
+Canonical finding (fields owned by `diagnosis.md`):
+
+- **dimension** · B1 Interactive States  **cause layer** · Behavior  **tier** · within-levers  **severity** · major  **provenance** · B1 Interactive States (states-presence)
+- **felt symptom (Perception)** · on first load the queue renders as an empty, misaligned frame, then snaps into place when rows arrive
+- **evidence** · `src/routes/queue/QueueRoute.tsx:28` — `<QueueTable rows={data}>` renders unconditionally while `data` is `[]` during the fetch
+- **before → after** · no loading state → the lifecycle pattern's skeleton, column-geometry-matched, shown while `isLoading`
+- **consequence** · every visit shows a flash of broken-looking UI and a layout shift; the queue reads as *failing* before it reads as *loading*
+
+Rendered per register:
+
+- **Designer** · "The queue has no loading state: it paints its empty frame before data arrives, so the first thing an operator sees is a broken, misaligned table that then jumps. Give it a skeleton matched to the column geometry, held until rows load. A surface that reads as broken before it reads as loading erodes trust on every visit. (Interactive states; cause in Behavior; major.)"
+- **Developer** · "`src/routes/queue/QueueRoute.tsx:28` — `<QueueTable rows={data}>` renders while `data` is `[]` during the fetch. Branch on `isLoading` and render the lifecycle skeleton (column-width-matched rows) until the query resolves. Within existing levers; no token or manifest change. (B1, Behavior; major.)"
+- **PM** · "The queue looks broken for a moment every time it opens, then jumps into place — it needs a real loading state so it reads as loading, not failing. Low effort; removes a daily 'is this thing working?' flinch for every agent. (Major.)"
+
+The designer hears design, the developer gets the branch and the file, the PM gets the cost and the outcome — one diagnosis underneath all three.
+
+## The findings report
+
+Every run files a dated report — introspection doubles as documentation, so a run that produced understanding doesn't evaporate with the conversation. The path is shared with review reports:
+
+```
+docs/design/findings/YYYY-MM-DD-<slug>.md
+```
+
+`<slug>` names the target (the surface, or the app). The report carries the canonical findings so a consented improve run consumes it directly, topped with a two-line executive summary in the chosen register. It is a deliverable, not runtime state — never read back as design state (code is the cache, floor P8).
+
+### Template
+
+```
+# Introspection — <target> · <YYYY-MM-DD>
+
+Reader: <designer | developer | pm>
+Scope: <surface / dimension / whole app examined>
+
+## Summary
+<two lines, in the chosen register — the shape of what's wrong and what it costs>
+
+## Findings
+<severity-ranked: auto-critical → critical → major → minor; canonical format per diagnosis.md>
+
+### <n>. <one-line title> — <severity>
+- dimension · cause layer · tier · provenance
+- evidence: <file:line / token / value>
+- before → after: <token-cited; numeric where machine-backed>
+- consequence: <what it costs the operator>
+- <the finding rendered in the chosen register>
+
+## Handoff
+Findings share the canonical format. To apply, run improve over this report:
+within-levers findings apply jailed; lever-change findings need lever consent.
+```
+
+Severity is a ranked scale, never a number — no scores, ever.
+
+## The improve handshake
+
+Introspect diagnoses; it never touches app code. When the user wants the findings applied, the same canonical findings feed an improve run (D10's escalation, run in reverse): the report *is* the input — improve reads it directly because both share the finding format. Scope covers what the findings name; depth is apply; authority follows each finding's tier — **within-levers** findings apply jailed to the lever manifest, **lever-change** findings are offered and need lever consent, never changed unbidden. The handoff is offered, never automatic.
+
+## Never
+
+- Never edit code — introspect reads, diagnoses, explains, and files the report; fixes happen only through a consented improve run.
+- Never infer or store the reader — ask, every run.
+- Never let a register become three opinions — it is presentation of one diagnosis.
+- Never emit a numeric score — severity rank only.

package/data/harnesses/code/skills/design/references/lifecycle.md

@@ -0,0 +1,73 @@
+# Lifecycle & microcopy
+
+The states a surface actually lives in, and the microcopy mechanisms that fill them. The brief describes the happy path; production is mostly everything else — loading at 9am, empty for a new tenant, degraded and half-stale at 3am. A surface designed only for the state the brief names is a broken surface.
+
+**Loads** at the create **surfaces** phase (state-shells get filled here) and whenever improve/introspect diagnoses state or copy coverage. Reads the `temporal` facts from `docs/design/structure.md`; the state-presence and copy-shape rules (`sta-*`) are already in boot context via `hard-rules.md` — this file is the design content behind them, not a restatement. Dial defaults come from `personality.md`.
+
+## The seam: mechanisms, not words
+
+Everything here is a **mechanism** — a formula, a required shape, a consistency discipline. The actual words are the business's call (floor P12). The skill enforces that an error names what happened / why / how to fix; it never writes the error text. It enforces one term per concept; it never picks the term. Emit shells and shapes; leave the vocabulary to the domain.
+
+## Required states per surface
+
+Four states are **always** required on every data surface: **loading**, **empty**, **error**, **partial/degraded**. They are not afterthoughts — they are the surface. Beyond the four, these are required **only where the model says they exist**, and the model is `docs/design/structure.md`'s `temporal` block, not a guess:
+
+- **post-action** — an action passes through pending/saving/processing before it resolves.
+- **cancel path** — a long or reversible action can be abandoned mid-flight.
+- **disconnection / timeout** — the surface can lose the backend.
+- **concurrent edit** — two operators can touch one record at once.
+
+The temporal probe (run inside the object pass — see `structure.md`) is what decides which conditional states a surface carries; read its facts, don't invent them.
+
+**States are built into the shell, never bolted on.** The scaffold phase already stubbed every declared state per surface (the state-shell stubs). The surfaces phase composes real content into those stubs. A shell whose `error` or `empty` slot ships as a placeholder is an unfinished surface and fails the phase gate. You are never adding states to a finished surface — you are filling shells that already exist.
+
+## Empty states
+
+An empty state is not one state. Five are distinct, and each earns distinct copy — collapsing them into one generic "No data found" is the defect:
+
+| Kind | It means | The copy teaches |
+| --- | --- | --- |
+| first-time | nothing created yet | what this surface is for, how to make the first thing |
+| user-cleared | they emptied it | that the clear worked, how to undo or add again |
+| no-results | filter/search matched nothing | that data exists, that the filter is the cause |
+| no-access | forbidden, not empty | that it exists but is gated, who to ask |
+| error | the fetch failed | routes to the error formula below, never to "empty" |
+
+**The empty formula: acknowledge → state the value → at most one action.** Text-first (floor P2) — copy plus at most one action, never an illustration showcase. *At most* one, not exactly one: a read-only surface (an audit log) legitimately offers zero. Never a dead-end on an actionable surface. Copy runs one to two sentences.
+
+## Errors
+
+**The error formula: what happened / why / how to fix.** All three parts. "Something went wrong" fails all three — it diagnoses nothing, explains nothing, offers no recovery, and is a named defect.
+
+**Dead ends and silent failures are banned.** Every error is visible and every error has an exit. A failure the operator can't see and a failure they can see but can't act on are the same bug.
+
+**Errors render inline, next to the offending field** — not in a banner divorced from the cause. The exception is genuinely system-wide failure (the backend is down, not one field is invalid), which legitimately banners; that scope is why the inline rule grades warning-tier, not absolute.
+
+## Temporal honesty
+
+Render the read model's lag honestly. When a write isn't yet visible in the read model, show a **pending state** — never paint the optimistic result as settled truth. Pending is not a lie; a premature success is.
+
+- **Skeletons mirror the content's shape**, not a centered spinner — the same columns, rows, and blocks the loaded surface will show. **Delay showing ~150–300ms** so a fast response never flashes a skeleton. The full loading-indicator bands (nothing under the short threshold, skeleton in the mid band, progress bar past the long one) are pinned by `mot-*`.
+- **Optimistic updates only for low-stakes actions, always with a visible rollback surface** — the row reverts and says why when the write loses. High-stakes or irreversible actions wait for the server (pessimistic) and preview before commit.
+- **Distinguish "no data" from "can't get data."** Empty means the query succeeded and found nothing; degraded means the query failed or the data is stale. **Mark staleness honestly** — a panel showing a cached value while its source is unreachable says so.
+
+## Toasts
+
+Toasts acknowledge transient, low-stakes success — nothing that needs action. **Auto-dismiss 3–5s, `aria-live="polite"`, never steal focus** (pinned in `sta-*`). An actionable error never lives only in a toast that vanishes; it goes inline where the operator can act on it. A toast is never the only signal for something the operator must do.
+
+## Copy disciplines
+
+Two disciplines govern every visible string, and they apply to UI copy, help text, and API names alike:
+
+- **One term per concept, one concept per term.** If the thing is a "ticket," it is a ticket in the label, the tooltip, the empty state, the toast, and the endpoint. Two words for one concept, or one word for two, is the defect. Divergence is allowed only when deliberate — a legacy-locked internal name may lag a renamed label — never accidental.
+- **Verb+object action labels.** "Create ticket," "Assign agent," "Archive job" — never bare "Submit," "OK," "Done." The label states the object it acts on.
+
+Both ride **sentence case** (not Title Case, not ALL CAPS outside tracked micro-labels) and **front-loading** — put the information-bearing word first so a scanning eye catches meaning at the left edge. "Payment failed — card declined," not "There was a problem processing your payment." Front-load labels, headings, menu items, and column headers.
+
+## The copy self-audit
+
+A pre-ship mandatory procedure (`proc-*`, fires in the whole-app sweep): **re-read every visible string on every surface and rewrite every flagged one.** This is the pass that kills lorem-slop, fabricated metrics, generic "No data found" empties, and dead-end errors in one sweep — and the pass that verifies one-term-per-concept held across the whole app, not just per file. No surface ships un-audited.
+
+## Dials modulate presentation
+
+Lifecycle presentation is dial-controlled, never per-surface improvisation. `data-verbosity` scales how much status copy renders — `full` spells out pending and progress narration, `expert` compresses it. `data-feedback` scales feedback intensity — how often toasts fire, how much motion a state transition carries. The dials compose *with* density, never instead of it. Their levels, defaults, and wiring live in `personality.md`; this file governs the states, not the knobs.