@adia-ai/adia-ui-factory 0.2.2 → 0.2.3

package/skills/adia-ui-kit/references/correction-loop.md

@@ -0,0 +1,462 @@
+---
+name: correction-loop
+load-when: When output is wrong, doesn't match intent, or the user says 'that's not right'. Load before patching surface; the procedure forces root-cause identification before fix.
+load-size-tokens: ~6,200
+required-for:
+  - recovery mode (mode 9)
+  - any time the user says output is wrong
+  - compound-fix avoidance
+---
+
+# §CorrectionLoop — How to reason when output is wrong
+
+This is the third posture, alongside Author and Consultant. It triggers
+whenever something you produced — markup, plan, recipe, diagnostic
+report, ticket, commit, or response — is reported as incorrect, or you
+yourself notice it is wrong before the user does.
+
+**The instinct to fix is the failure mode.** Patching the surface
+without finding the root cause guarantees the bug re-emerges in another
+shape next turn. The Correction Loop is a strict 5-phase recovery
+discipline that pre-empts that instinct.
+
+### The Correction Loop (in strict order)
+
+```
+1. CONTEXT     What is the current state, and what is being said?
+2. REFERENT    What is the user or agent referring to — concretely?
+3. DECOMPOSE   What are the layers of the stack, and where does the
+               symptom originate?
+4. ROOT-CAUSE  First-principles analysis: what is the irreducible
+               source of the wrong output?
+5. CLASSIFY    Which layer owns the fix? Apply the right remediation
+               and route to the right channel.
+```
+
+Skip none. Each phase has a stop-condition that gates the next.
+
+### Phase 1 — CONTEXT — Re-anchor before reacting
+
+Before any analysis, restate the current context to yourself in plain
+English:
+
+- **What turn is this?** (greeting, mid-task, post-task review, error
+  report.)
+- **What did I just produce?** (markup file, diagnostic report, plan,
+  commit, conversation reply.)
+- **What did the user just say?** (the literal words; do not paraphrase
+  defensively.)
+- **What other context is live?** (peer agent commits since last turn,
+  uncommitted working-tree state, stale memory entries that may now be
+  wrong — AGENTS.md hard rule: memory is "as of last write", trust
+  `git log` + filesystem over memory.)
+
+**Stop-condition:** you can write two sentences summarizing the current
+state without assumption or interpretation. If you can't, re-read the
+last 3 user messages + `git log --oneline -5` + `git status` before
+proceeding to Phase 2.
+
+**Anti-pattern:** reacting to the most recent user message in isolation.
+Almost every "wrong output" report has 2–3 turns of prior context that
+shapes the correct fix. Re-anchor first.
+
+### Phase 2 — REFERENT — What are they actually pointing at?
+
+User feedback on wrong output is rarely precise. You must resolve the
+referent before you can analyze:
+
+- **Concrete artifact** — which file / URL / component / spec / commit
+  is the user pointing at? Quote them or extract the exact reference.
+- **Comparison anchor** — what is the user comparing against? ("this
+  doesn't match the reference shell at /site/examples/admin-dashboard"
+  has two referents: the produced output AND the comparison anchor.)
+- **Failure mode** — what specifically is wrong? Wrong markup, wrong
+  styling, wrong intent, wrong primitive choice, wrong spec citation,
+  wrong file location, wrong version. Each maps to a different
+  remediation path.
+- **Implicit reference** — what is the user *assuming* you know? (A
+  spec, an ADR, a journal entry, a prior conversation.) If the
+  assumption is unstated and you can't verify it, ask before fixing.
+
+**Stop-condition:** you can name (a) the artifact, (b) the comparison
+anchor (if any), (c) the failure mode, and (d) any implicit references
+the user is invoking. If any of (a)–(d) is fuzzy, ask one targeted
+clarifying question — do not guess.
+
+**Anti-pattern:** taking the user's diagnosis ("the table is broken")
+as the root cause. The user is reporting a symptom from their
+perspective; your job is to translate that into a verifiable referent.
+Their diagnosis is a hint, not a specification.
+
+### Phase 3 — DECOMPOSE — Locate the layer of origin
+
+Map the symptom to the stack layer it originates from. AdiaUI's stack:
+
+```
+Layer                          Owner            Fix shape
+─────────────────────────────  ──────────────   ──────────────────────
+1. User intent / spec          User             Clarify, restate, plan
+2. Skill content (this file)   Skill author     Patch SKILL.md
+3. Consumer codebase           Consumer repo    PR / commit
+4. AdiaUI substrate            chat-ui repo     Substrate fix + release
+5. Substrate spec / ADR        chat-ui repo     ADR amendment + sweep
+6. Tooling / harness / MCP     chat-ui repo     Script / config fix
+7. Browser / runtime           Browser vendor   Workaround + report
+```
+
+For the symptom: walk **downward** from layer 1. Find the *first*
+layer at which the symptom is *not yet caused*. The symptom originates
+at the *next* layer down. This is the layer of origin.
+
+Worked example A — **tag-swap class** ("the produced admin shell uses
+`<main>` instead of `<admin-content>`"):
+
+- Layer 1 (intent): User asked for an admin shell. Intent is fine.
+- Layer 2 (skill): Did the skill teach `<main>`? Grep SKILL.md. If
+  yes → the skill is the layer of origin. If no → continue.
+- Layer 3 (codebase): Did the codebase have `<main>` examples I
+  cargo-culted? Grep the consumer repo. If yes → consumer-codebase
+  inheritance was the layer of origin.
+- Layer 4 (substrate): Does `<admin-content>` exist in the substrate?
+  Check `node_modules/@adia-ai/web-modules/shell/admin-content/`. If
+  no → substrate is the layer of origin (substrate missing primitive).
+- Layer 5 (spec): Does an ADR mandate the `<main>` → `<admin-content>`
+  swap? Check `.brain/adrs/`. If the spec is silent → spec gap.
+
+Worked example B — **slot-omission class, with the substrate-mechanics
+trap** ("the admin shell renders but the topbar appears mispositioned"):
+
+This class is what tag-swap looks like *after* the consumer already
+adopted the canonical vocabulary. The bug is now an attribute (slot,
+variant, name, mode) — right tag, wrong attribute. The diagnosis flow
+below ends with **a discipline rule that pre-empts the failure that
+produced this example.** Read it through before generalizing.
+
+- Layer 1 (intent): User asked for canonical admin chrome. Intent
+  is fine.
+- **Substrate-mechanics check FIRST, symptom probe second.** Before
+  measuring anything with `getBoundingClientRect()`, verify your
+  *mental model* matches how the affected components actually
+  render. For AdiaUI shell components specifically:
+    - `<admin-shell>`, `<admin-sidebar>`, `<admin-content>` are
+      **CSS-only light-DOM** (per ADR-0033,
+      the canonical Light-DOM substrate stance; surfaced in `AGENTS.md`
+      L50 — "Light-DOM
+      web components"). They have **no shadow root**.
+    - A `slot=` attribute on a child of a light-DOM parent is
+      **inert**. There is no `<slot>` element to project into.
+    - Positioning is done by CSS rules matching **tag + ancestor
+      + DOM order + sibling structure** (e.g. `admin-content >
+      admin-topbar:first-child`), NOT by named-slot projection.
+    - Therefore: `slot="header"` on `<admin-topbar>` inside
+      `<admin-content>` is **decorative** — it does nothing to
+      positioning. Adding or removing it leaves the layout
+      identical.
+  Light-DOM vs Shadow-DOM is the irreducible rate-limiting
+  mechanic. Misidentifying it short-circuits everything below.
+- **Symptom probe second.** Run `getBoundingClientRect()` on the
+  affected element + its parent + its siblings. But interpret
+  carefully:
+    - A sidebar's topbar IS expected to span only the sidebar's
+      column width (not the viewport). `(0, 0, 200, 48)` inside
+      a 200-px sidebar is correct, not broken.
+    - A content's topbar IS expected to span the content area's
+      width. `(200, 0, 1080, 48)` inside a 1080-px content area
+      is correct.
+    - Missing elements (no boundingClientRect at all) point at
+      a real bug — not at slot-projection failure but at DOM
+      construction or CSS-not-loaded.
+- Layer 2 (skill): Does SKILL.md teach the missing attribute? Grep.
+  *But also:* does the skill's diagnostic guidance assume Shadow-DOM
+  slot mechanics when the affected components are Light-DOM? If yes
+  → the skill is teaching a wrong substrate model, which is a more
+  serious finding than a missing attribute.
+- Layer 3 (codebase): Does the consumer's source actually differ
+  from the canonical references? Diff against `apps/saas/` /
+  `*.examples.html` / `site/index.html`. A genuine difference that
+  correlates with the visual symptom is the immediate origin;
+  cosmetic differences (slot attributes on light-DOM components)
+  are NOT the cause even when they look like they could be.
+- Layer 4 (substrate): Could the bug be substrate-side? Check
+  whether the affected component has shipped fixes in recent
+  CHANGELOG entries; check for CSS-load-order bugs, missing
+  imports, or framework regressions.
+- Layer 5 (spec): Is the substrate-mechanics distinction documented?
+  AGENTS.md hard rule states Light-DOM but Light-vs-Shadow per
+  component is not always called out at the component level. Worth
+  promoting to component yaml.
+
+> **Real-world arc — and the failure mode this example documents:**
+> Worked example B was extracted from a §CorrectionLoop session
+> against `claims-ui-v4` where the agent (this skill, running in
+> chat-ui) **misdiagnosed** a layout symptom as slot-omission and
+> filed FEEDBACK-37 requesting a substrate `console.warn` for
+> missing `slot="header"` on `<admin-topbar>`. The substrate
+> maintainer shipped the warn in v0.6.20 (`d32e34b4f`), then
+> reverted it 27 minutes later in `664cb3f55` after audit revealed
+> the warn fired on correct markup with a factually wrong message:
+> `<admin-content>` / `<admin-sidebar>` are Light-DOM, the slot
+> attribute is inert there, positioning is by tag + DOM order, and
+> the bars render identically with or without the slot.
+>
+> Root cause of the misdiagnosis: the agent ran
+> `getBoundingClientRect()` and interpreted `(0, 0, 200, 48)` for
+> the sidebar's topbar as "broken (only 200 px wide instead of
+> viewport-spanning)" — but 200 px is the correct sidebar-column
+> width and the topbar correctly spans it. The "missing
+> content-topbar from normal flow" was a separate symptom with a
+> different cause, conflated with the first under one wrong
+> diagnosis.
+>
+> **The discipline this teaches:** verify your mental model of the
+> substrate's rendering mechanism (Light-DOM vs Shadow-DOM,
+> CSS-projection vs slot-projection) *before* the symptom probe.
+> A wrong mental model turns correct measurements into wrong
+> conclusions. The `getBoundingClientRect()` probe is only as good
+> as the model interpreting its output.
+>
+> The compound-fix rule still holds — but here the "fix" turned
+> out to be: Layer 3 was already correct; Layer 4 needed no
+> change; Layer 2 (this skill) needed the substrate-mechanics
+> check at the top of the diagnostic flow; Layer 5 (spec) is the
+> Light-DOM-vs-Shadow-DOM clarity that AGENTS.md mentions but
+> component yamls don't always surface.
+>
+> **Pedagogical value: a misdiagnosis ticket that shipped + got
+> reverted is more useful than a clean diagnosis would have been.**
+> The post-mortem captures a discipline gap (substrate-mechanics
+> assumption) that a clean case would have hidden.
+
+### Bug-shape taxonomy (what to expect at Phase 3)
+
+Real bugs cluster into a small number of shapes. Recognizing the shape
+narrows the layer hunt:
+
+| Shape | Symptom | Most common origin layer |
+|---|---|---|
+| **Tag swap** | Wrong tag entirely (`<main>` for `<admin-content>`) | Layer 2 (skill stale) or Layer 3 (codebase predates ADR) |
+| **Slot misdiagnosis** (the Light-DOM trap) | Looks like missing `slot=` attribute; actually the parent is Light-DOM and slot is inert | Layer 2 (agent's wrong substrate model) — NOT a real slot bug |
+| **Attribute-shape misuse** | Right tag/slot, wrong value type (string for array, object for primitive) | Layer 4 (substrate silent on bad shape) + Layer 2 (skill missing shape contract) |
+| **Composition violation** | Right primitives, wrong nesting (`<button-ui>` inside `<button-ui>`, `<field-ui>` containing a self-labeling widget) | Layer 5 (composition rules not in ADR) + Layer 4 (no nest-check warn) |
+| **Token override** | Right styling, wrong cascade source (`--a-fg` set in `:root` shadowing variant scope) | Layer 3 (consumer global overrides) + Layer 2 (skill missing scope-discipline note) |
+| **Version-trailing** | Right code, behavior matches older substrate version | Layer 3 (declared range too loose) + Layer 6 (no version-check gate) |
+| **Doc-stale** | Right code matching old spec, spec since superseded | Layer 5 (ADR/spec/journal contradicts itself) |
+
+When the bug shape is one of the four lower rows, **expect a compound
+layer-3 + layer-4-or-5 fix**. Single-layer fixes for these shapes
+re-emerge as the next agent hits the same silent trap.
+
+The layer of origin determines the remediation channel. Misidentify
+the layer, and you patch the wrong artifact.
+
+**Stop-condition:** you can name the layer and cite one piece of
+evidence supporting that assignment.
+
+**Anti-pattern:** assuming the symptom's surface layer is its origin.
+"The markup is wrong" → "patch the markup" is wrong 80% of the time;
+the markup is a *symptom* of a deeper layer (skill, consumer
+inheritance, substrate gap, spec silence).
+
+### Phase 4 — ROOT-CAUSE — First-principles analysis at the layer of origin
+
+Once you know the layer, run first-principles analysis *at that layer*.
+The questions are layer-specific:
+
+**Zeroth question (asked at every layer, not just one):** *Does my
+mental model of the substrate's rendering mechanism match how it
+actually renders?* For AdiaUI specifically, the recurring trap is
+Light-DOM vs Shadow-DOM:
+
+- AdiaUI ships **Light-DOM web components** (canonical reference:
+  ADR-0033; surfaced
+  in `AGENTS.md` L50).
+  Shell-tier components (`<admin-shell>`, `<admin-sidebar>`,
+  `<admin-content>`, plus most primitives) have **no shadow root**.
+- A `slot=` attribute on a child of a Light-DOM parent is **inert**.
+  There is no `<slot>` element to project into. The attribute is
+  decorative and changing it does nothing to positioning.
+- Light-DOM positioning is done by CSS rules matching tag + ancestor +
+  DOM order + sibling structure (e.g. `admin-content > admin-topbar`),
+  NOT by named-slot projection.
+- Components that DO use Shadow-DOM (rare in this substrate) document
+  it explicitly in their class.js. When in doubt, grep for
+  `attachShadow` / `createShadowRoot` in the component source.
+
+**If you skip this check, every measurement you take will be
+interpreted against the wrong model**, and your root cause will be
+plausibly-shaped but factually wrong. The FB-37 misdiagnosis (the
+arc that produced Worked Example B) is the archetype: correct
+`getBoundingClientRect()` measurements were interpreted against a
+Shadow-DOM mental model when the components are Light-DOM, and the
+resulting ticket asked the substrate to enforce a contract that
+doesn't exist.
+
+After the zeroth question, the layer-specific questions:
+
+**If layer 2 (skill):**
+- What exact section of SKILL.md taught the wrong shape?
+- Why was it phrased that way? (predates SoT change? cargo-culted from
+  legacy doc? autocompleted from memory?)
+- What's the irreducible fix? (patch the exact paragraph; the failure
+  mode is "skill teaches stale shape" — fix at source, not in markup.)
+
+**If layer 3 (consumer codebase):**
+- Does the codebase have an AGENTS.md / convention doc that
+  *contradicts* the SoT?
+- Is the codebase predates an ADR adoption that should have happened?
+- Is the codebase deliberately carved-out from the convention? (Check
+  the journal / commit log for a "we chose to keep X because Y" note.)
+
+**If layer 4 (substrate):**
+- Does the substrate primitive *exist*? (yaml exists, JS class exists,
+  examples render?)
+- Does it work correctly? (run the demo locally; check the latest
+  CHANGELOG for a fix in flight.)
+- Is the consumer's installed version *behind* the fix? (3-tuple check
+  from §GapDetection.)
+
+**If layer 5 (spec / ADR):**
+- Is there an ADR for this concern? If no → spec gap; propose one.
+- Is the ADR ambiguous? Quote the ambiguous sentence; propose a
+  clarifying patch.
+- Is the ADR contradicted by a more recent journal/spec entry? Trust
+  the more recent + flag the contradiction for resolution.
+
+**If layer 6 (tooling):**
+- Did a verification gate miss this? (check:lockstep, check:skills,
+  check:skill-patterns-sot.) If yes → gate is incomplete; propose a
+  gate extension.
+- Did a generation script produce wrong output? (harvester, MCP
+  generator.) Trace upstream to the script bug.
+
+**Stop-condition:** you can state the root cause in one sentence in the
+shape "**The wrong output happened because <Layer-N artifact> says/does
+<X>, when it should say/do <Y> because of <first-principles reason>.**"
+
+If you can't write that sentence, you don't have the root cause yet —
+go back to Phase 3 and recheck the layer assignment.
+
+**Anti-pattern:** "the fix is to change the markup" — that's a *patch*,
+not a *root cause*. Markup is layer 3 output; the root cause is in
+layer 2 or 4 or 5. Patching markup without fixing the source layer
+means the next agent will hit the same bug.
+
+### Phase 5 — CLASSIFY — Route the fix to the right channel
+
+Every layer of origin has a canonical remediation channel. Apply the
+right one — and frequently, *more than one* (the immediate patch +
+the upstream fix + the prevention gate).
+
+| Layer of origin | Immediate fix | Upstream remediation | Prevention gate |
+|---|---|---|---|
+| 1. Intent | Clarify with user, restate plan | n/a | §0 Reasoning Gate (catches at next surface) |
+| 2. Skill | `patch SKILL.md`, bump version | `skill_manage(action='patch')` | check:skills + check:skill-patterns-sot |
+| 3. Consumer codebase | PR / commit to consumer repo | Add convention to AGENTS.md | Consumer-side `check:` script |
+| 4. Substrate | Patch substrate file, lockstep cut | npm release + CHANGELOG | substrate `npm run check` |
+| 5. Spec / ADR | Amend ADR, sweep affected surfaces | Journal entry capturing change | `check:skill-patterns-sot` + spec-INDEX update |
+| 6. Tooling | Patch script / harness / MCP | Add to `npm run check` | CI gate |
+| 7. Runtime | Document workaround, file upstream | Vendor bug report | Catch in §3 Validation |
+
+**Compound fixes are common.** A symptom that surfaces in markup
+(layer 3) often has its root in the skill (layer 2) AND a missing
+substrate gate (layer 4) AND a stale spec (layer 5). All three need
+addressing — the markup patch alone leaves the door open.
+
+**Ticket submission is layer-routing, not effort-routing.** Don't
+file a ticket "because the fix is big"; file a ticket because the
+layer of origin is owned by someone else, or because the fix needs
+cross-version coordination. The §FeedbackDiscipline four-bucket
+classification + §Team Tickets pipeline cover this.
+
+**Stop-condition:** you have a written list of (a) immediate fixes
+landed, (b) upstream remediations queued (with channel: PR, ticket,
+ADR amendment), and (c) prevention gates added or extended. The
+correction is complete when all three are addressed *or* explicitly
+deferred with rationale.
+
+**Anti-pattern:** landing only the immediate fix. The next agent re-
+hits the bug in 3 turns. Compound fixes prevent recurrence; that's
+the whole point of root-cause-before-patching.
+
+### When the user reports the wrong output (the conversational shape)
+
+When a user message reports incorrect output ("this is wrong",
+"that's not what I asked for", "the X doesn't match Y"), your reply
+shape is:
+
+1. **Acknowledge** without defensive framing. ("You're right — let me
+   trace this.")
+2. **Restate the referent** (Phase 2 output, one sentence).
+3. **Walk the decomposition** (Phase 3, one sentence — "this came from
+   layer N because <evidence>").
+4. **Name the root cause** (Phase 4, one sentence — the irreducible
+   reason).
+5. **Propose the compound fix** (Phase 5 list — immediate + upstream +
+   prevention).
+6. **Wait for confirmation** before executing — *unless* the immediate
+   fix is trivial and obviously correct, in which case land it and
+   surface the upstream items for approval.
+
+The user gets to see your reasoning chain, which lets them correct any
+layer-assignment mistake before you act on it.
+
+### When the agent (you) notices the wrong output before the user
+
+Same loop, same shape. Do not silently swap the fix in — surface the
+correction with the same 5-step chain. Silent correction destroys the
+trail and trains the user to distrust your output.
+
+The exception: trivial in-the-moment typo or formatting fix during
+the same turn. Anything load-bearing (markup, plan, spec citation,
+commit content) goes through the full loop with explicit surfacing.
+
+### Sniff tests before declaring root cause
+
+Before committing to a layer assignment + root cause, run these
+sniff tests:
+
+1. **Could this symptom occur in a clean repo with the same skill and
+   same substrate version?** If yes → root cause is in skill or
+   substrate or spec, not consumer codebase. If no → consumer
+   codebase carries state that triggers it.
+
+2. **Did this symptom exist before the most recent change I or a peer
+   made?** Check `git log -p <file>` for the section in question. The
+   commit that introduced the bug is usually the layer of origin.
+
+3. **Does a verification gate exist that *should have* caught this?**
+   If yes → gate has a hole; that's a layer-6 finding alongside the
+   primary layer. If no → propose adding one.
+
+4. **Is this the same shape of bug I've seen before in this session?**
+   If yes → there's a deeper pattern; the layer may be one up from
+   where you think. (Example: three wrong markup outputs in a row
+   probably means the skill teaches a wrong pattern, not three
+   independent markup mistakes.)
+
+5. **Am I about to fix the symptom or the cause?** If you can answer
+   "fix" in one verb (`patch markup`, `delete file`, `rename
+   attribute`), you're probably surface-patching. If the fix has
+   multiple steps across multiple layers, you're addressing the
+   cause.
+
+### Correction Loop pitfalls
+
+- **Defensive framing.** "Actually, the output is correct because…"
+  blocks the loop at Phase 1. Drop the defense; verify the referent.
+- **Authority deference.** "The user says X, so X." Users report
+  symptoms; you classify root causes. Take their words as evidence,
+  not as the diagnosis.
+- **Skipping Phase 2.** Jumping from "user said wrong" to "I'll fix"
+  skips referent resolution and produces fixes for the wrong thing.
+- **Layer mis-assignment.** Patching markup when the skill is the
+  origin. Patching the skill when the substrate is the origin.
+  Re-run Phase 3 if a fix doesn't hold.
+- **Single-layer fixes for compound problems.** The bug emerges from
+  layer 3 because of layer 2 and a missing layer 6 gate. Fixing only
+  3 means it comes back.
+- **Silent correction.** Swapping in the right output without
+  surfacing the loop. Train the user to trust your reasoning, not
+  your luck.
+
+---