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

package/skills/adia-ui-kit/references/feedback-authoring.md

@@ -0,0 +1,466 @@
+# Reference: Defensible Feedback Authoring (vendored from color-app `.agents/team/skills/`)
+
+**Vendored:** 2026-05-20, from `/Users/kimba/Projects/adia/color-app/.agents/team/skills/feedback-authoring.md`.
+**Original upstream:** `~/.pi/agent/memory/skills/write-defensible-feedback-ticket.md`.
+**Why vendored:** This is the canonical discipline for upstream FEEDBACK tickets to
+`@adia-ai/*` packages. It is the source of truth that the `adia-ui-kit` skill body
+(§FeedbackDiscipline / §AutoCapture / §TicketTooling) routes to. Do not paraphrase
+the body — read it. Updates should flow back upstream (color-app + the `~/.pi` skill
+above), not be patched here in isolation.
+
+**Used by:** `adia-ui-kit` skill, when drafting tickets to upstream maintainers of
+`@adia-ai/*` packages. The skill body's §FeedbackDiscipline section names the
+five core principles + four-bucket classification + sniff tests; this file is the
+full procedural detail behind those names.
+
+**Companion:** `references/response-authoring.md` (the reviewer half of the dyad).
+
+---
+
+## When to Use
+
+- Authoring outbound FEEDBACK to upstream (AdiaUI, partner teams)
+- Writing bug reports, feature requests, or RFCs to projects you don't own
+- Filing upstream tickets that must survive principal-engineer / leadership review
+- **Trigger phrases:** "write feedback to X", "file an issue about Y", "send this upstream"
+
+The goal is a ticket the author can defend **item-by-item** under hostile review. Both **inclusions** and **exclusions** must hold up under "why is this here?" / "why is this not here?" cross-examination.
+
+---
+
+## Core Principles
+
+1. **Every item is evidence-bound.** A claim without a file path, commit hash, version number, or stack trace is a guess.
+2. **Exclusions are first-class.** What you chose NOT to file is as important as what you filed. Future agents reading the ticket will ask "why isn't X here?" — answer it pre-emptively.
+3. **Distinguish four failure modes:** framework bug, framework gap, consumer dogfooding miss, third-party/scope-violation. Only the first two belong in a feedback ticket.
+4. **Verify before claiming "already shipped."** If you exclude an item on those grounds, open the installed source and confirm. Cite the file path.
+5. **Reproducibility is the threshold for P0/P1.** If the recipient can't reproduce the symptom from your description, you've filed an anecdote, not a bug.
+
+---
+
+## Procedure
+
+### 1. Inventory raw findings
+
+Before writing the ticket, list every observation from the session:
+
+```bash
+# Re-read the work that surfaced the feedback
+git log --oneline -20
+git diff HEAD~5..HEAD -- src/ docs/
+cat CHANGELOG.md | sed -n '/^## \[Unreleased\]/,/^## \[/p'
+cat .agents/team/comms/from-agent-*.md 2>/dev/null
+```
+
+Capture EVERY rough edge — don't filter yet. A list of 15 items where half get rejected is healthier than a list of 6 where 3 are weak.
+
+### 2. Classify each finding into one of four buckets
+
+| Bucket | Examples | Action |
+|---|---|---|
+| **Framework bug** | Crash, type-vs-runtime drift, parser mis-classification | File as `P0` if reproducible, `P1` if subtle |
+| **Framework gap** | Missing primitive, missing prop, missing event type | File as `P1`–`P3` based on workaround cost |
+| **Consumer dogfooding miss** | "Primitive X already exists with the exact shape we need; we just didn't use it" | NOT feedback — capture in `.agents/team/comms/` for peer pickup |
+| **Third-party / scope violation** | "Vite cache is stale" / "TypeScript doesn't infer this" | NOT feedback to the recipient — note in related-observations or external doc |
+
+**The classification gate eliminates ~30% of raw findings.** Anything that doesn't survive the bucket-check shouldn't go in.
+
+### 3. Verify "already-shipped" exclusions
+
+For every item you intend to exclude on grounds of "already resolved", prove it by opening the installed source:
+
+```bash
+# Example: claim "<select-ui> event types shipped"
+cat node_modules/<package>/components/select/select.d.ts | grep -E "EventDetail|CustomEvent"
+
+# Example: claim "barrel re-exports element.js helpers"
+grep -n "export.*html\|export.*signal" node_modules/<package>/core/element.d.ts
+
+# Example: claim "phantom event removed"
+grep -n "ToastCloseEvent" node_modules/<package>/components/toast/toast.d.ts
+# Empty output = confirmed removed
+```
+
+Save the file path + line number — you'll cite them in the "Items deliberately NOT included" section.
+
+If you can't verify in <2 minutes, **don't exclude on those grounds** — either include the item (filing a duplicate is cheap) or admit uncertainty in the doc.
+
+### 4. For each surviving finding, produce the four-block structure
+
+```markdown
+## N. <Title> (P<x>)
+
+**Component:** <component name>
+**Versions affected:** <range, with current version explicit>
+
+### What happened
+
+<Concrete observed behavior. Stack trace if a crash. Screenshot path
+if visual. Cite file:line for both consumer code AND framework code.>
+
+### Root cause (verified end-to-end)
+
+<Walk the recipient through HOW you established the cause. If you
+ran a probe, include the probe. If you read framework source, cite
+the function name + line number.>
+
+### Reproduction
+
+<Minimal repro. Code block that the recipient can paste into their
+test harness and see the symptom. If a runtime crash, include the
+exact error message.>
+
+### Request
+
+<Specific ask. Either a code patch sketch, or a concrete API shape
+with props/events/types, or a doc paragraph that should exist.>
+
+### Why this matters
+
+<One paragraph. Who else hits this? What's the workaround cost?
+What's the cost of NOT fixing it?>
+```
+
+Drop sections that don't apply (e.g. a doc ask doesn't need a stack trace), but **every P0 needs every block**.
+
+### 5. Estimate cost honestly
+
+For each ask, include a cost estimate:
+
+```markdown
+| Pri | Item | Estimated cost |
+|---|---|---|
+| **P0** | inTag() skips HTML comments | ~20 LOC + 1 test |
+| P1 | <copy-button-ui> primitive | medium (new component + tests + a2ui example) |
+| P3 | TESTING.md docs | small (docs only) |
+```
+
+Honest cost estimates let the recipient triage. If you don't know, write "unknown — would defer to maintainer judgment" — don't guess.
+
+### 6. Write the "Items deliberately NOT included" section
+
+This is the **defense block**. Structure:
+
+```markdown
+## Items deliberately NOT included (defending the exclusions)
+
+To avoid duplicate filings, the following were considered and
+explicitly left out. Each was verified against the installed
+<package>@<version> source where applicable.
+
+- **<Item>** — <verdict>. <Verification anchor: file path + line
+  number, or release note reference, or RESPONSE-XX cross-ref>.
+  <If a different ask captures the spirit of this item, cite the
+  section number that does.>
+
+- **<Item>** — already exists with the exact shape we need. NOT
+  feedback — this is a **consumer-side dogfooding miss** captured
+  separately in `.agents/team/comms/<dated-handoff>.md`.
+
+- **<Item>** — third-party tool issue. Workaround is <X>. Listed
+  in related-observations for documentation benefit but not a code
+  ask on this recipient.
+
+- **<Item>** — speculative; no concrete pain-point yet. Filing
+  without a use-case would be P3 noise.
+
+If any of the above is wrong or stale relative to a newer release,
+please flag in the response.
+```
+
+Each exclusion must cite either:
+- A specific file/line in the installed package that proves it's shipped, OR
+- A RESPONSE-XX or CHANGELOG entry that resolved it, OR
+- A `.agents/team/comms/` path where the issue is being tracked elsewhere, OR
+- An explicit statement that it's out of scope and why
+
+**"Already shipped — trust me"** is not acceptable. Cite or include.
+
+### 6b. (Optional) Promote exclusions to a companion `--OMISSIONS-DEFENSE.md` file
+
+When the exclusion list is **15+ items, spans 4+ distinct rationale categories, or the ticket will face hostile leadership review**, split the defense block out into a sibling file:
+
+```
+.agents/team/tickets/outbox/
+  FEEDBACK-07--<recipient>--<date>.md            # the asks
+  FEEDBACK-07--OMISSIONS-DEFENSE.md              # the exclusions, expanded
+```
+
+**When to split vs keep inline:**
+
+| Inline (§6 block) | Companion file (§6b) |
+|---|---|
+| <10 exclusions | 15+ exclusions |
+| 1–2 rationale categories | 4+ rationale categories |
+| Routine review | Principal-engineer / leadership audit expected |
+| One-shot ticket | Part of multi-round feedback series where omissions compound |
+
+**Companion file structure** — group omissions by **rationale category**, not by priority. Categories observed to work well in practice:
+
+```markdown
+# FEEDBACK-NN Omissions Defense
+
+**Date:** YYYY-MM-DD
+**Author:** <role / session>
+**Context:** Prepared for leadership + principal engineer review. Every
+item below was considered for inclusion in `FEEDBACK-NN--<recipient>--<date>.md`
+and deliberately excluded.
+
+## Principle Applied
+
+<2–4 sentences naming the scoping rule the ticket used, e.g.
+"current-session, concrete, reproducible friction that blocked or
+significantly slowed v3 UI delivery.">
+
+Items were excluded if they were:
+1. <Category 1, e.g. "Already filed by the peer agent in FEEDBACK-NN-1">
+2. <Category 2, e.g. "Resolved in prior releases">
+3. <Category 3, e.g. "Standard CSS customization, not framework defects">
+4. <Category 4, e.g. "Speculative / not yet encountered in practice">
+5. <Category 5, e.g. "Internal to our adapter architecture">
+
+I will flag items where my confidence is low.
+
+---
+
+## <Category 1> — Correctly Omitted
+
+### Omission 1: <one-line title> (P<x>)
+**<EVIDENCE TAG>** (e.g. PEER FINDING / VERIFIED IN SOURCE / RESOLVED IN vX.Y)
+<1–2 sentences citing the verification anchor.>
+**Defense:** <Why this exclusion is correct.>
+**Confidence:** High | Medium | Low.
+
+### Omission 2: ...
+
+---
+
+## <Category 2> — Correctly Omitted
+...
+```
+
+**Mandatory per-omission fields:**
+- **Evidence tag** (uppercase, scannable: `PEER FINDING`, `VERIFIED IN SOURCE`, `RESOLVED IN v0.5.2`, `OUR INTERNAL API`, etc.)
+- **Defense paragraph** (1–3 sentences — why the exclusion is the right call)
+- **Confidence rating** (`High` / `Medium` / `Low`) — Low or Medium ratings are honesty, not weakness
+
+**Cross-link the companion in the main ticket's front-matter:**
+```yaml
+references:
+  - "FEEDBACK-NN--OMISSIONS-DEFENSE"
+```
+
+…and in §6 of the main ticket, replace the bullet list with a one-line pointer:
+
+> Items considered and deliberately excluded are tracked in
+> `FEEDBACK-NN--OMISSIONS-DEFENSE.md` — 15 omissions across 5 rationale
+> categories, each with verification anchor and confidence rating.
+
+**Why split:** large inline `§6` blocks get skimmed. A standalone file forces both author and reviewer to treat exclusions as first-class artifacts. Principal engineers reviewing the ticket will read the companion file before signing off, because it's labelled as the exclusion defense — they don't have to dig.
+
+**Anti-pattern:** splitting when the count is small. <10 exclusions inline is more readable than two files. Don't manufacture a defense file for ceremony.
+
+### 7. Cross-reference siblings and predecessors
+
+Front-matter `references:` block must list every prior FEEDBACK / RESPONSE that touches the same components or themes. In the body, explicitly call out:
+
+- **Sibling tickets in the same session** — "FEEDBACK-07 §2 is a related `core/template.js` bug" + cross-reference link.
+- **Duplicates** — "Item §4 is the same ask as FEEDBACK-XX §N; recipient can collapse when triaging."
+- **Supersession** — "This obsoletes FEEDBACK-YY §M after the RESPONSE-YY clarification."
+
+A reader who lands on your ticket without context should be able to follow links to the full conversation.
+
+### 8. Set status and front-matter correctly
+
+```yaml
+---
+id: "06"                                              # serial per recipient
+type: feedback                                        # feedback | bug | request | response
+recipient: adia-ui
+date: "2026-05-13"
+author: "<role> (<session-context>)"                  # don't claim a human author
+project: "<project that generated the feedback>"
+status: draft                                         # draft until submitted
+references:
+  - "FEEDBACK-04--adia-ui--2026-05-13"                # every prior touchpoint
+version: "@adia-ai/web-components@0.7.13"              # version verified against
+priority: p0                                          # highest priority in the doc
+---
+```
+
+`status: draft` is the right starting point. Only the human user (or the agent acting under explicit submit instruction) should bump it to `submitted`.
+
+### 9. Update the registry
+
+Add your new file at the bottom of `.agents/team/tickets/REGISTRY.md` with a one-line summary of every priority-tagged item:
+
+```markdown
+| `FEEDBACK-06--adia-ui--2026-05-13.md` | feedback | adia-ui | 2026-05-13 | draft | inTag HTML-comment parse bug (P0), drawer close-reason, sidebar responsive collapse, icon requiredIcons, phantom-event audit, ... |
+```
+
+Don't truncate to a topic — list the actual items so future searches can find them.
+
+If you wrote a §6b companion file, give it its own registry row:
+
+```markdown
+| `FEEDBACK-07--OMISSIONS-DEFENSE.md` | omissions-defense | adia-ui | 2026-05-13 | draft | Companion to FEEDBACK-07 — 15 omissions across 5 rationale categories with confidence ratings |
+```
+
+### 10. Verify the ticket builds and ships
+
+```bash
+# TS / build still passes
+npx tsc --noEmit | grep -v '<peer-owned-paths>'
+
+# Dev server still up
+curl -s -o /dev/null -w "%{http_code}\n" http://localhost:<port>/
+
+# Working tree clean
+git status --short
+
+# Ticket actually parses as markdown (some renderers choke on edge cases)
+markdownlint .agents/team/tickets/outbox/<file>.md 2>/dev/null || true
+
+# Commit with explicit excluded list for peer-agent files
+git commit -m "docs(tickets): FEEDBACK-XX to <recipient> — <topic>
+
+<full narrative>
+
+Excluded — peer-agent in-flight: <named files or 'none'>."
+```
+
+---
+
+## Sniff tests before sending
+
+Walk through each one before declaring the ticket ready:
+
+1. **Reproduction test:** Can a stranger paste your repro code into a fresh project and see the symptom? If not, P0/P1 status is wrong.
+2. **Exclusion test:** Pick one item from "Items deliberately NOT included." Can you defend it in 30 seconds with a file path?
+3. **Cost test:** Can the recipient roughly estimate their effort from your cost block? "Medium — new component + tests + a2ui example" is good. "Some work" is not.
+4. **Duplicate test:** Have you grepped the prior FEEDBACK / RESPONSE files for keywords that overlap with your asks? If you find matches, either cross-reference them or remove your duplicate.
+5. **Scope test:** Is any item really a third-party-tool issue or a consumer-side miss? If yes, move it out of the feedback ticket.
+6. **Pre-mortem test:** If leadership asks "why did you ship this and not item X?" — do you have an answer? If "I didn't think of X" is the honest answer, X probably belongs in the doc.
+
+---
+
+## Pitfalls Specific to Our Workflow
+
+### AdiaUI binding contract — verify before filing as a framework bug
+
+Reactive `*-ui` form controls and template re-renders share a single contract that surfaces as ~4 distinct symptoms; they are ONE root cause, not four:
+
+1. `.value=${() => x.value}` (getter function) silently fails on `slider-ui` / `switch-ui`. The component reads `value` as a plain property at update time; a function reference is stored as-is and never invoked. **Use `.value=${x.value}` (direct expression).**
+2. `style="background:${v}"` renders literal `style="background:{{p:0}}"` in the DOM (partial attribute interpolation is not supported). **Use `style="${precomputed}"` where the entire attribute is one placeholder, or `.style=${expr}` property binding.** v0.5.3+ console.warns.
+3. Template doesn't re-render when an upstream signal changes, even though a nested callback dereferences it. Cause: the *template function itself* never read the signal — only a nested callback did. **Top of every template, read every signal whose change should trigger re-render: `const _doc = doc.value; void _doc`.**
+4. `OKLCHColor.h = NaN` (chromaless source) → `oklchToSRGB().hex = "#NaNNaNNaN"` → `<input type="color">` console-flood: `value does not conform to #rrggbb`. **Sanitize at the conversion boundary, not the binding site.**
+
+Before filing any of these as a framework bug, run the equivalent template through a Playwright probe and confirm the DOM. Symptoms 1–3 are documented in `USAGE.md` § property-binding-patterns; symptom 4 is a consumer bug.
+
+### HTML-comment apostrophes/unmatched `<>` in `html\`\`` templates
+
+Naive `inTag()` quote-tracker mis-classifies placeholders after the comment. Symptom: `Cannot read 'detail' of undefined` from connectedCallback. Fix: reword comments, use ' (U+2019). Fixed framework-side in v0.5.3 — file only if reproducible on current version.
+
+### Phosphor icon name verification is non-optional
+
+`<icon-ui name="X">` warns at runtime if `X` doesn't exist in `@phosphor-icons/core/assets/regular/`. Before using an icon, `ls node_modules/@phosphor-icons/core/assets/regular/ | grep <pattern>`. Common mistakes: `plus` (often wants `plus-circle`), `arrows-counter-clockwise` (use singular `arrow-counter-clockwise`). Don't file as feedback.
+
+### Vite CSS cache is real and silent
+
+When CSS changes don't reach the browser, the file on disk may differ from the served bundle. Symptom: rule exists in `src/style.css` but `curl http://localhost:5173/src/style.css` returns an older version. Fix: `rm -rf node_modules/.vite && pkill -f vite && npm run dev`. Not an AdiaUI bug.
+
+### Don't conflate "didn't find it" with "doesn't exist"
+
+Before claiming a feature is missing, grep the installed package source AND `components/*/USAGE.md` / `README.md` / `.a2ui.json` / `.yaml` sidecars (e.g. `tree-ui` keyboard nav, `slider-ui` decimal step).
+
+### Don't file silent-failure complaints without a runtime symptom
+
+When the template engine renders `{{p:0}}` literally, include the DOM dump as evidence — not "I expected X."
+
+### Don't file workaround-as-bug if USAGE.md prescribes the workaround
+
+`USAGE.md` § property-binding-patterns documents `.foo=${expr}` for property binding; `foo="${expr}"` failing isn't a bug.
+
+### Don't file separate tickets for the same root cause
+
+Slider getter-function, signal-binding stuckness, and partial-attr interpolation all stem from "template re-runs only on direct signal reads." File as ONE root-cause ticket with N symptoms.
+
+### Don't drop omissions
+
+For every issue encountered but NOT filed, write a one-line defense in `--OMISSIONS-DEFENSE.md`. Examples that DON'T merit a ticket: typos in your own code, missing imports, USAGE.md patterns you didn't read.
+
+### Don't promise a CHANGELOG entry without verifying the recipient ships one
+
+Track via `git log` on their main, not via CHANGELOG.
+
+### Lockstep PATCH releases are common
+
+AdiaUI sometimes ships PATCH bumps with no source change (e.g. v0.5.1, v0.5.4 ride-alongs). Before claiming a fix "should have shipped in vX," check `git log` between cuts. Don't file a regression for an issue resolved in the prior MINOR.
+
+### Playwright tests for custom elements have unique gotchas
+
+`<tree-item-ui>` click activation requires the row slot, not the element. `dts-right-panel` may resolve to 2 elements (wide-viewport sidebar + narrow-viewport drawer); use `.first()` or filter by `:visible`. Async-loading sub-components (e.g. `<code-ui>` in drawers): `waitFor({ state: 'attached' })` not `'visible'`.
+
+---
+
+## Example skeleton
+
+```yaml
+---
+id: "XX"
+type: feedback
+recipient: adia-ui
+date: "2026-05-XX"
+author: "<role> (<session>)"
+project: "color-app"
+references:
+  - "FEEDBACK-04--adia-ui--2026-05-13"
+  - "RESPONSE-04--chat-ui--2026-05-13"
+  - "FEEDBACK-07--OMISSIONS-DEFENSE"
+version: "@adia-ai/web-components@0.7.13"
+priority: p0
+---
+
+# FEEDBACK-XX — <Topic summary>
+
+## <N>. <Title> (P<x>)
+
+**Component:** <name>
+**Versions affected:** <range>
+
+### What happened
+...
+
+### Root cause (verified end-to-end)
+...
+
+### Reproduction
+```ts
+// Minimal repro
+```
+
+### Request
+...
+
+### Why this matters
+...
+
+---
+
+## <N+1>. ...
+
+---
+
+## Items deliberately NOT included (defending the exclusions)
+
+To avoid duplicate filings ...
+
+- **<Item>** — <verdict>. <Anchor>.
+- **<Item>** — consumer dogfooding miss. Tracked in `.agents/team/comms/...`
+- **<Item>** — third-party issue. Workaround is ...
+- **<Item>** — speculative.
+
+## Related observations (for documentation benefit only)
+
+- ...
+```