From 17bd31b8a392bf9d6c18d89133cd96105fa91cf4 Mon Sep 17 00:00:00 2001 From: LuLaValva Date: Fri, 14 Aug 2026 13:25:24 -0700 Subject: [PATCH 1/2] docs: add agent-feedback system Record actionable observations that are out of scope for the task that surfaced them, instead of dropping them or widening an unrelated diff. Ported from the marko repo, with an a11y category and a rule requiring entries to name which framework packages a defect reaches. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 7 +++++++ agent-feedback/README.md | 44 +++++++++++++++++++++++++++++++++++++++ agent-feedback/a11y.md | 3 +++ agent-feedback/bugs.md | 3 +++ agent-feedback/cleanup.md | 3 +++ agent-feedback/dx.md | 3 +++ agent-feedback/perf.md | 3 +++ agent-feedback/unclear.md | 3 +++ 8 files changed, 69 insertions(+) create mode 100644 agent-feedback/README.md create mode 100644 agent-feedback/a11y.md create mode 100644 agent-feedback/bugs.md create mode 100644 agent-feedback/cleanup.md create mode 100644 agent-feedback/dx.md create mode 100644 agent-feedback/perf.md create mode 100644 agent-feedback/unclear.md diff --git a/CLAUDE.md b/CLAUDE.md index abfca576d72..c2004cc046a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,6 +10,7 @@ AI configuration for eBay's evo-web components monorepo. - Always run `npm run build` before marking component work complete - Prefer reading existing patterns over introducing new ones - Never manually edit auto-generated files (they should typically have a comment indicating they are generated) +- Never widen a task's diff with out-of-scope fixes — record them in `agent-feedback/` instead (see below) ## @@ -280,6 +281,12 @@ npx vitest run packages/ebayui-core/src/components/ebay-button/test/test.browser --- +## Agent Feedback + +Anything actionable but out of scope for the current task — a suspected bug, an a11y gap, cleanup, a perf/size win, tooling friction, or code that was confusing — must be recorded in [`agent-feedback/`](agent-feedback/README.md) before finishing. Don't silently drop it, and don't fix it inside an unrelated diff. Read that README for the entry format; resolved entries are deleted in the same PR as the fix. + +--- + ## Skills For specialized workflows: diff --git a/agent-feedback/README.md b/agent-feedback/README.md new file mode 100644 index 00000000000..254707fc861 --- /dev/null +++ b/agent-feedback/README.md @@ -0,0 +1,44 @@ +# Agent Feedback + +Actionable observations that were **out of scope for the task that surfaced them**. If something is in scope, fix it instead. Do not expand a task's diff to fix issues recorded here. + +## When to add an entry + +While working on any task, record anything a future contributor should act on: + +- a suspected bug left unpursued → `bugs.md` +- a WCAG 2.2 AA / ARIA / keyboard / RTL / dark-mode gap → `a11y.md` +- duplication, dead code, inconsistency, refactor opportunities → `cleanup.md` +- runtime speed, bundle size, or CSS output size opportunities → `perf.md` +- friction in builds, tests, Storybook, or repo workflows → `dx.md` +- code or docs that were confusing, and what would have clarified them → `unclear.md` + +## Rules + +1. **Search the category file first.** If an entry already covers it, don't duplicate; append a corroborating sentence only when it adds new information. +2. **Be self-contained.** Include enough detail (paths, symbols, reasoning) that someone can act without re-discovering the analysis behind it. Never reference "my earlier analysis" or conversation context. +3. **Cite by stable symbol, not line number.** Line numbers rot with the next edit; anchor the primary citation to the nearest enclosing stable symbol — an exported component or function, a `` in a `.marko` template, a BEM selector or mixin in SCSS, or a heading for docs. A line number may appear in the body as a secondary hint. +4. **Note every package the entry spans.** A component usually exists in `skin`, `ebayui-core`, `evo-marko`, `ebayui-core-react` and `evo-react`; say which of them the defect reaches and which you actually checked. +5. **Append to the end** of the category file. +6. Entries are **removed when resolved** (delete, don't mark done; git history is the archive), in **the same PR as the fix**, never a follow-up PR. A partial fix rewrites the entry to what remains. +7. **Verify before recording.** A guess is not feedback. +8. **An entry is work to do, not documentation.** State the defect and the check that proves it. Never describe what already works, and never narrate what a landed fix changed. + +## Resolving a "won't fix" item + +When a maintainer has explicitly deemed an item "won't fix" / "not worth it", resolve it by adding a brief inline comment at the code site that captures the decision (so it is not re-filed), then remove the entry. Only on such an explicit call, never on an agent's own initiative. + +## Entry format + +```md +## + +`` › `` | 2026-08-14 | impact: | effort: + +<2-6 sentences: the problem, why it matters, and a concrete suggested direction, +ending with the check that re-verifies the claim (a command, input, or +observation). Cut evidence beyond what a fixer needs to act; further detail is +re-derived from the citation. Additional file paths inline as needed.> +``` + +A re-verification check is a command someone else can run — `npx vitest run `, `npm run build`, `npm run lint`, a Storybook story plus the interaction that exposes it, or a rendered-markup/computed-style observation. "Read the code and you'll see" is not a check. diff --git a/agent-feedback/a11y.md b/agent-feedback/a11y.md new file mode 100644 index 00000000000..f89956299ef --- /dev/null +++ b/agent-feedback/a11y.md @@ -0,0 +1,3 @@ +# Accessibility + +WCAG 2.2 AA gaps: ARIA misuse, keyboard operability, focus states, contrast, zoom to 400%, RTL, dark mode. Format and rules: [README.md](README.md). diff --git a/agent-feedback/bugs.md b/agent-feedback/bugs.md new file mode 100644 index 00000000000..b95fa687fbe --- /dev/null +++ b/agent-feedback/bugs.md @@ -0,0 +1,3 @@ +# Suspected Bugs + +Out-of-scope defects noticed while working on something else. Format and rules: [README.md](README.md). diff --git a/agent-feedback/cleanup.md b/agent-feedback/cleanup.md new file mode 100644 index 00000000000..588eb766796 --- /dev/null +++ b/agent-feedback/cleanup.md @@ -0,0 +1,3 @@ +# Cleanup + +Duplication, dead code, inconsistencies, refactor opportunities. Format and rules: [README.md](README.md). diff --git a/agent-feedback/dx.md b/agent-feedback/dx.md new file mode 100644 index 00000000000..72069a0b3e9 --- /dev/null +++ b/agent-feedback/dx.md @@ -0,0 +1,3 @@ +# Developer Experience + +Friction in builds, tests, Storybook, or repo workflows. Format and rules: [README.md](README.md). diff --git a/agent-feedback/perf.md b/agent-feedback/perf.md new file mode 100644 index 00000000000..37624403a95 --- /dev/null +++ b/agent-feedback/perf.md @@ -0,0 +1,3 @@ +# Performance + +Runtime speed, bundle size, and CSS output size opportunities. Format and rules: [README.md](README.md). diff --git a/agent-feedback/unclear.md b/agent-feedback/unclear.md new file mode 100644 index 00000000000..445cebc46e1 --- /dev/null +++ b/agent-feedback/unclear.md @@ -0,0 +1,3 @@ +# Unclear Code & Docs + +Things that were hard to understand, and what would have clarified them. Format and rules: [README.md](README.md). From de0867c9ff21a875c3997154d3442872ce8a6a43 Mon Sep 17 00:00:00 2001 From: Luke LaValva Date: Fri, 14 Aug 2026 13:37:33 -0700 Subject: [PATCH 2/2] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- agent-feedback/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agent-feedback/README.md b/agent-feedback/README.md index 254707fc861..810bd6a7644 100644 --- a/agent-feedback/README.md +++ b/agent-feedback/README.md @@ -33,7 +33,7 @@ When a maintainer has explicitly deemed an item "won't fix" / "not worth it", re ```md ## -`` › `` | 2026-08-14 | impact: | effort: +`` › `` | | impact: | effort: <2-6 sentences: the problem, why it matters, and a concrete suggested direction, ending with the check that re-verifies the claim (a command, input, or