---
id: "{{ID}}"
type: feedback
recipient: {{RECIPIENT}}
date: "{{DATE}}"
author: "{{AGENT}} ({{SESSION_CONTEXT}})"
project: "{{PROJECT}}"
status: draft
references:
  # - "FEEDBACK-NN--{{RECIPIENT}}--YYYY-MM-DD"     # uncomment for prior related touchpoints
  # - "RESPONSE-NN--{{RECIPIENT}}--YYYY-MM-DD"
  # - "FEEDBACK-{{ID}}--OMISSIONS-DEFENSE"          # if you author a companion
version: "@adia-ai/web-components@{{VERSION}}"
priority: {{PRIORITY}}     # p0 | p1 | p2 | p3 — highest priority among the findings
---

# FEEDBACK-{{ID}} — {{TOPIC_HEADLINE}}

## Executive Summary

One paragraph stating the headline problem and net effect. Read like a
maintainer-facing TL;DR — what's broken, what the consumer experiences,
what action you want. Cite the most damning concrete detail (file:line,
DOM symptom, missing prop) here, not buried below.

| Pri | Item | Estimated cost |
|---|---|---|
| **P{{PRIORITY_NUM}}** | <one-line ask for the highest-priority item> | <honest LOC + test count, or "unknown — defer to maintainer judgement"> |
| P{{NEXT}} | <one-line ask for next item> | <estimate> |

Estimate honestly. `unknown — defer to maintainer judgement` is acceptable;
guesses are not.

---

## 1. <Finding title> (P{{PRIORITY_NUM}})

**Component:** `<component name + relevant file:line in the framework>`
**Versions affected:** <range, with the version you measured against 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.

Example phrasing:
> In `src/components/<consumer-file>.ts`, I authored <X using the documented
> pattern Y>. The code compiled, ran, and emitted no console warnings.
> The <symptom> happened because <root reason at the surface level>.

### 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.

```js
// framework code excerpt with file:line annotation
// e.g. core/template.js lines 175-177 (v0.6.6):
} else if (name[0] === '.') {
  n.removeAttribute(name);
  parts[i] = { t: 'p', n, name: name.slice(1), c: undefined, _fx: null };
}
```

Explain why this code produces the observed symptom in the consumer's
case. If there are sibling cases that DON'T trigger the bug, name them
— that's the discrimination that proves you've isolated the cause.

### Reproduction

Minimal repro the recipient can paste into their test harness:

```ts
// Paste into a fresh @adia-ai/web-components@{{VERSION}} project
import { UIElement, html } from '@adia-ai/web-components/core/element'

class Demo extends UIElement {
  static template = () => html`<!-- minimal markup that triggers the bug -->`
}
customElements.define('demo-{{REPRO_TAG}}', Demo)
document.body.append(new Demo())

// Expected: <describe the correct behavior>
// Actual:   <describe what actually happens — be specific about the symptom>
```

Include browser + version if browser-specific.

### Request

Specific ask. Prefer multi-option presentation when there's a trade-off:

#### Option A (preferred) — <approach>

<Code sketch or API shape. Honest LOC estimate.>

```js
// proposed framework patch
```

<N> LOC + 1 test in `<path/to/test>`. Backward-compatible — existing
behavior preserved; only the buggy case changes.

#### Option B — <alternative approach>

<Trade-off vs Option A. When this is preferable.>

#### Option C — Document the trap

If a code fix is out of scope, at minimum a doc paragraph in
`<path/to/USAGE.md>` explaining the constraint and the recommended
consumer pattern.

### Why this matters

One paragraph. Who else hits this? What's the workaround cost? What's
the cost of NOT fixing it?

Example phrasing:
> We hit this in <N> distinct codepaths in <project>. The first cost
> ~<X> minutes of debugging before noticing <discriminating detail>.
> Without a fix, every consumer who <follows the documented path> pays
> the <X>-minute debug tax until they discover the trap. Usage grows
> over time because the framework's docs steer consumers into the
> broken path.

---

<!--
## 2. <Next finding title> (P<x>)

Repeat the 5-block structure for each additional finding. Multi-finding
tickets are normative; single-finding tickets are fine too. When you add
a §2 (or §3, §4, …), copy the 5-block structure from §1 above.

### What happened
...

### Root cause (verified end-to-end)
...

### Reproduction
...

### Request
...

### Why this matters
...

---
-->

## Items deliberately NOT included (defending the exclusions)

To avoid duplicate filings, the following were considered and explicitly
left out. Each was verified against `node_modules/@adia-ai/web-components@{{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**; fix it in the
  consumer codebase instead of filing upstream.

- **<Item>** — third-party tool issue (Vite cache, TS inference, etc.).
  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.

> **Note:** If this exclusion list grows to 15+ items or spans 4+ rationale
> categories, promote it to a companion `FEEDBACK-{{ID}}--OMISSIONS-DEFENSE.md`
> file (see `feedback-authoring.md` §6b). Replace this whole section with
> a one-line pointer to the companion.

---

## Related observations (non-asks, for context)

- <Observation that's useful for the recipient but not a code ask.>
- <Sibling tickets in the same session, with cross-reference links.>
- <Patterns observed across multiple consumer sites that don't rise to
  the level of a separate ticket but inform the maintainer's roadmap.>

---

## Pre-finalize checklist

Verify every box below is ticked before flipping `status: draft` → `submitted`.

- [ ] Executive Summary present and reads as a maintainer-facing TL;DR.
- [ ] Cost-estimate table present with honest estimates.
- [ ] Every numbered finding has all 5 blocks (What / Root cause /
      Reproduction / Request / Why this matters).
- [ ] Every P0/P1 finding has a paste-ready reproduction code block.
- [ ] §Items deliberately NOT included cites a verification anchor for
      every exclusion (file path, version reference, or prior-ticket
      cross-reference).
- [ ] Front-matter `references:` lists every prior FEEDBACK/RESPONSE
      touching the same components.
- [ ] `version:` front-matter matches the actually-installed version
      (verified — not assumed).
- [ ] Sniff tests pass (see `../../references/feedback-discipline.md`):
      reproduction, exclusion, cost, duplicate, scope, pre-mortem.
- [ ] No `TBD`/`TODO`/`???` markers in the body.