From add550e9af7de42be8b580842a85120db81d8e4d Mon Sep 17 00:00:00 2001 From: Dylan Piercey Date: Tue, 21 Jul 2026 13:40:39 -0700 Subject: [PATCH] Add agent-feedback setup --- AGENTS.md | 7 +++++++ CLAUDE.md | 1 + agent-feedback/README.md | 39 +++++++++++++++++++++++++++++++++++++++ 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, 62 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md create mode 100644 agent-feedback/README.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/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8d53d39 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,7 @@ +# htmljs-parser + +An HTML parser recognizes content and string placeholders and allows JavaScript expressions as attribute values + +## Agent feedback + +Anything actionable but out of scope for the current task — a suspected bug, 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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/agent-feedback/README.md b/agent-feedback/README.md new file mode 100644 index 0000000..c79150a --- /dev/null +++ b/agent-feedback/README.md @@ -0,0 +1,39 @@ +# 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 you couldn't pursue → `bugs.md` +- duplication, dead code, inconsistency, refactor opportunities → `cleanup.md` +- runtime speed or bundle size opportunities → `perf.md` +- friction in builds, tests, tooling, 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 if you have new information. +2. **Be self-contained.** Include enough detail (paths, symbols, reasoning) that someone can act without re-discovering your analysis. 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 (exported function, class, variable, or a heading for docs). A line number may appear in the body as a secondary hint. +4. **Append to the end** of the category file. +5. Entries are **removed when resolved** (delete, don't mark done; git history is the archive). +6. **Verify before recording.** A guess is not feedback. + +## 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 your own initiative. + +## Entry format + +```md +## + +`` › `` | 2026-07-02 | 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.> +``` diff --git a/agent-feedback/bugs.md b/agent-feedback/bugs.md new file mode 100644 index 0000000..b95fa68 --- /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 0000000..588eb76 --- /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 0000000..19e09a2 --- /dev/null +++ b/agent-feedback/dx.md @@ -0,0 +1,3 @@ +# Developer Experience + +Friction in builds, tests, tooling, 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 0000000..6afb16b --- /dev/null +++ b/agent-feedback/perf.md @@ -0,0 +1,3 @@ +# Performance + +Runtime speed and bundle 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 0000000..445cebc --- /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).