diff --git a/CLAUDE.md b/CLAUDE.md index abfca576d7..c2004cc046 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 0000000000..810bd6a764 --- /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 +## + +`` › `` | | 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 0000000000..f89956299e --- /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 0000000000..b95fa687fb --- /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 0000000000..588eb76679 --- /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 0000000000..72069a0b3e --- /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 0000000000..37624403a9 --- /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 0000000000..445cebc46e --- /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).