From 1a9ea36720e17dac7e9f3f26cea436ce7a53b2ab Mon Sep 17 00:00:00 2001 From: Dylan Piercey Date: Thu, 20 Aug 2026 09:55:16 -0700 Subject: [PATCH] docs(agent-feedback): migrate to one item per file Replace the five category files with agent-feedback/items/, one file per finding with typed frontmatter, and add repo-specific notes to the README so triage has the repro, guard-test, and pre-ship commands. --- AGENTS.md | 2 +- agent-feedback/README.md | 69 ++++++++++++------- agent-feedback/bugs.md | 9 --- agent-feedback/cleanup.md | 3 - agent-feedback/dx.md | 3 - ...26-07-30-render-awaits-completed-stream.md | 12 ++++ agent-feedback/perf.md | 3 - agent-feedback/unclear.md | 3 - 8 files changed, 58 insertions(+), 46 deletions(-) delete mode 100644 agent-feedback/bugs.md delete mode 100644 agent-feedback/cleanup.md delete mode 100644 agent-feedback/dx.md create mode 100644 agent-feedback/items/2026-07-30-render-awaits-completed-stream.md delete mode 100644 agent-feedback/perf.md delete mode 100644 agent-feedback/unclear.md diff --git a/AGENTS.md b/AGENTS.md index 5f73a2f..c6c7395 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,4 +4,4 @@ Simple and complete Marko testing utilities that encourage good testing practice ## 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..cde1800 100644 --- a/agent-feedback/README.md +++ b/agent-feedback/README.md @@ -1,39 +1,60 @@ # 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, a concrete direction. Cut evidence a fixer can re-derive from the site.> -<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.> +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. Wraps `@testing-library/dom` for Marko templates and supports Marko 3 through 6 through separate branches in `src/index.ts`. + +**Reproduce a claim.** Add a fixture under `src/__tests__/fixtures/` and a case in the matching `src/__tests__/*.test.ts`. Server-side rendering is covered by `*.server.test.ts`, browser/DOM by the rest. + +**Guard tests.** `pnpm test` (`vitest run`); `pnpm test:update` for snapshots, `pnpm test:watch` while iterating. + +**Pre-ship.** `pnpm run build` (rolldown + tsc), `pnpm run @ci:lint`, `pnpm test`. Add a changeset with `pnpm run change`. + +**Gotchas.** `devDependencies` pins a Marko 5 line while `peerDependencies` allows `3 - 6`, so the Marko 6 code paths are not exercised by the default install or by CI. Reproducing anything on the Marko 6 branch needs a Marko 6 installed on purpose; say so in the item. A Marko 6 render returns a stream-backed object, so `toString()` throws while a render is pending. diff --git a/agent-feedback/bugs.md b/agent-feedback/bugs.md deleted file mode 100644 index b8afd79..0000000 --- a/agent-feedback/bugs.md +++ /dev/null @@ -1,9 +0,0 @@ -# Suspected Bugs - -Out-of-scope defects noticed while working on something else. Format and rules: [README.md](README.md). - -## Consume the first render chunk in `render()` instead of awaiting the completed stream - -`src/index.ts` › `render` | 2026-07-30 | impact:med | effort:med - -The Marko 6 branch does `String(await (template as any).render(input))`, and that await settles only once marko's `ServerRendered` boundary reaches `FlushStatus.complete`, so `*.server.test.ts` can never observe an ``/`` placeholder or any intermediate streaming state — the HTML handed to `JSDOM.fragment` is always the fully drained output, and a fixture whose `load()` promise never settles hangs `render()` until vitest's timeout with no diagnostic. `toString()` is not an escape hatch: marko throws "Cannot consume asynchronous render with 'toString'" while the render is still pending. Nothing is needed from marko — the object returned by `template.render(input)` already exposes `[Symbol.asyncIterator]()`, `pipe()` and `toReadable()`, and a `for await` over a `` fixture yields the `Loading…` placeholder in chunk one — so the fix is local: read the first chunk and stop, either as the default or behind a new flag on `RenderOptions` in `src/shared.ts`, leaving the Marko 3/4/5 callback branch untouched. Note CI does not cover this path today: `devDependencies` pins `marko@^5.39.13` while `peerDependencies` allows `3 - 6`, so reproducing needs a Marko 6 install. Re-verify by adding a `` fixture under `src/__tests__/fixtures/` plus a case in `src/__tests__/render.server.test.ts` asserting the placeholder text, then running `pnpm test` — today that case sees only resolved content, or times out when the promise never settles. 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/2026-07-30-render-awaits-completed-stream.md b/agent-feedback/items/2026-07-30-render-awaits-completed-stream.md new file mode 100644 index 0000000..e4ed9a4 --- /dev/null +++ b/agent-feedback/items/2026-07-30-render-awaits-completed-stream.md @@ -0,0 +1,12 @@ +--- +type: bug +impact: med +effort: med +site: src/index.ts › render +--- + +# Consume the first render chunk in `render()` instead of awaiting the completed stream + +The Marko 6 branch does `String(await (template as any).render(input))`, and that await settles only once marko's `ServerRendered` boundary reaches `FlushStatus.complete`, so a `*.server.test.ts` can never observe an ``/`` placeholder or any intermediate streaming state. The HTML handed to `JSDOM.fragment` is always the fully drained output, and a fixture whose `load()` promise never settles hangs `render()` until vitest's timeout with no diagnostic. `toString()` is not an escape hatch: marko throws "Cannot consume asynchronous render with 'toString'" while the render is still pending. Nothing is needed from marko, since the object returned by `template.render(input)` already exposes `[Symbol.asyncIterator]()`, `pipe()`, and `toReadable()`, and a `for await` over a `` fixture yields the `Loading...` placeholder in chunk one. Read the first chunk and stop, either as the default or behind a new flag on `RenderOptions` in `src/shared.ts`, leaving the Marko 3/4/5 callback branch untouched. CI does not cover this path: `devDependencies` pins `marko@^5.39.13` while `peerDependencies` allows `3 - 6`, so reproducing needs a Marko 6 install. + +Check: add a `` fixture under `src/__tests__/fixtures/` plus a case in `src/__tests__/render.server.test.ts` asserting the placeholder text, then `pnpm test`; the case sees only resolved content, or times out when the promise never settles. 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).