---
name: defensible-feedback
load-when: turning audit/diagnosis findings into upstream framework feedback — a bug report or feature request against @adia-ai
load-size: ~0.8k tokens
required-for: [app-audit — feedback path]
---

# Defensible feedback — filing framework findings that survive scrutiny

Findings leave the audit as `gh issue`s on the framework repo (ADR-0042 — never ticket
files). What makes one *defensible* is the discipline below; a ticket that skips it wastes
two sessions — yours writing it, the maintainer's dismissing it.

## Five principles

1. **Every item is evidence-bound** — a claim without a file:line, version, or stack trace is a guess.
2. **Exclusions are first-class** — what you chose NOT to file, and why, is part of the deliverable; answer "why isn't X here?" pre-emptively.
3. **Four buckets; only two are feedback.**
4. **Verify before claiming "already shipped"** — open the installed source and cite it.
5. **Reproducibility is the threshold for high priority** — an irreproducible symptom is an anecdote, not a bug.

## The four-bucket classification gate

| Bucket | Smell | Action |
| --- | --- | --- |
| **Framework bug** | crash, type-vs-runtime drift, mis-render from correct usage | file — P0 if reproducible, P1 if subtle |
| **Framework gap** | missing primitive/prop/event that forces a workaround | file — P1–P3 by workaround cost |
| **Consumer dogfooding miss** | the primitive exists; the app didn't use it | NOT feedback — fix the app (route back to the builder) |
| **Third-party / scope** | Vite cache, TS inference, browser quirk | NOT feedback — related-observations note at most |

Expect the gate to kill ~30% of raw findings. Inventory *everything* first, filter second —
a 15-item list where half die is healthier than a pre-filtered 6 with 3 weak entries.

## Verify exclusions against the installed source

Excluding an item as "already shipped/fixed" requires opening
`node_modules/@adia-ai/...` and citing file:line (or the empty grep proving removal). Can't
verify inside two minutes → don't exclude on those grounds: file the possible duplicate
(cheap) or state the uncertainty.

## Per-finding structure (every block for a P0; drop inapplicable blocks below that)

`What happened` (observed behavior, both consumer AND framework file:line) → `Root cause,
verified end-to-end` (how you established it — probe output or framework source citation) →
`Reproduction` (paste-into-fresh-project minimal) → `Request` (patch sketch, concrete API
shape, or the doc paragraph that should exist) → `Why this matters` (who else hits it;
workaround cost). Add an honest cost estimate per ask — "unknown — maintainer judgment" beats
a guess.

## Sniff tests before filing

1. **Reproduction** — could a stranger paste the repro into a fresh project and see it?
2. **Exclusion** — can you defend any given exclusion in 30 seconds with a file path?
3. **Cost** — can the maintainer triage from your estimate?
4. **Duplicate** — searched existing issues (`gh issue list --search`) for overlapping asks?
5. **Scope** — is any item really bucket 3 or 4? Move it out.
6. **Pre-mortem** — "why did you file this and not X?" has an answer better than "didn't think of X".