diff --git a/AGENTS.md b/AGENTS.md index 18f1d73..de66db8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,4 +4,4 @@ A Prettier plugin for parsing and printing Marko files. ## 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. +Anything actionable but out of scope for the current task (suspected bug, cleanup, perf or size win, tooling friction, confusing code) must be filed in [`agent-feedback/`](agent-feedback/README.md) before finishing. Never drop it silently. Never fix it inside an unrelated diff. diff --git a/agent-feedback/README.md b/agent-feedback/README.md index c79150a..79735b3 100644 --- a/agent-feedback/README.md +++ b/agent-feedback/README.md @@ -1,39 +1,66 @@ # 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. +Actionable observations that were out of scope for the task that surfaced them. In scope: fix it. Out of scope: file it here. Never expand a task's diff to fix an item recorded here. -## When to add an entry +One item per file in `items/`, named `YYYY-MM-DD-.md`. -While working on any task, record anything a future contributor should act on: +## When to file -- 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` +Anything a future contributor should act on: -## Rules +- `bug`: a suspected defect left unpursued +- `cleanup`: duplication, dead code, inconsistency, refactor opportunity +- `perf`: speed, memory, payload or bundle size, build time +- `dx`: friction in builds, tests, tooling, or repo workflows +- `unclear`: code or docs that were confusing, and what would have clarified them -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. +## Rules -## Resolving a "won't fix" item +1. **Verify first.** A guess is not feedback. Every item ends with a check that reproduces the claim. +2. **Dedupe first.** `grep -ril '' agent-feedback/items`. If a file covers it, edit that file only when you add new information. +3. **Check the code site.** An intent comment there means the behavior is deliberate. Do not file it. +4. **Self-contained.** Paths, symbols, reasoning. Never reference conversation context or "earlier analysis". +5. **Cite by stable symbol**, never line number. +6. **State the defect and the check.** Never describe what works. Never narrate a landed fix. +7. **Direction is preventive for `unclear` and `dx`.** Name what would have stopped the trip: a comment, a doc line, a lint rule, a compile error, a debug-only warning. The goal is that the next agent does not hit it. +8. **Resolve by deleting the file in the same PR as the fix.** A partial fix rewrites the file to what remains. +9. **Won't-fix is a maintainer's call, never an agent's.** Add a comment (two lines max) at the code site stating the behavior and why it is deliberate, then delete the file. The comment is what stops re-filing. Never consult git history to learn whether something was resolved; if it is not in `items/` and not commented at the site, it is unresolved. -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. +## Item format -## Entry format +`items/YYYY-MM-DD-.md`: ```md -## +--- +type: bug | cleanup | perf | dx | unclear +impact: high | med | low +effort: high | med | low +site: › +--- -`` › `` | 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.> +<2-6 sentences: the problem, why it matters, a concrete direction. Cut evidence a fixer can re-derive from the site.> + +Check: ``` + +`impact`: what breaks or is lost if ignored. `effort`: expected size of the fix. Both are the filer's estimate; triage re-judges. + +## Repo notes + +Single package, pnpm, vitest. Prints Marko files through prettier; parsing is delegated to `htmljs-parser`. + +**Reproduce a claim.** Format a snippet through the plugin: + +```sh +pnpm exec prettier --plugin ./src/index.ts --parser marko +``` + +For a defect in the printed output, the smallest reproduction is the input template plus the expected output. + +**Guard tests.** `vitest run`. Fixtures live under `src/__tests__/`; snapshots are updated with `pnpm test:update`. Prefer adding a case to an existing fixture suite over a new file. Idempotence matters: formatting the output again must be a no-op, so assert that too when a change touches printing. + +**Pre-ship.** `pnpm run build` (tsc + rolldown), `pnpm run @ci:lint` (eslint + prettier check), `pnpm test`. Add a changeset with `pnpm run change`. + +**Gotchas.** Behavior is coupled to the installed `htmljs-parser` version; a parse-level defect is usually filed there, not here. Prettier's own AST invariants (comments must attach, every node must print) surface as runtime throws rather than wrong output. diff --git a/agent-feedback/bugs.md b/agent-feedback/bugs.md deleted file mode 100644 index b95fa68..0000000 --- a/agent-feedback/bugs.md +++ /dev/null @@ -1,3 +0,0 @@ -# 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 deleted file mode 100644 index 588eb76..0000000 --- a/agent-feedback/cleanup.md +++ /dev/null @@ -1,3 +0,0 @@ -# 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 deleted file mode 100644 index 19e09a2..0000000 --- a/agent-feedback/dx.md +++ /dev/null @@ -1,3 +0,0 @@ -# Developer Experience - -Friction in builds, tests, tooling, or repo workflows. Format and rules: [README.md](README.md). diff --git a/agent-feedback/items/.gitkeep b/agent-feedback/items/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/agent-feedback/perf.md b/agent-feedback/perf.md deleted file mode 100644 index 6afb16b..0000000 --- a/agent-feedback/perf.md +++ /dev/null @@ -1,3 +0,0 @@ -# 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 deleted file mode 100644 index 445cebc..0000000 --- a/agent-feedback/unclear.md +++ /dev/null @@ -1,3 +0,0 @@ -# Unclear Code & Docs - -Things that were hard to understand, and what would have clarified them. Format and rules: [README.md](README.md).