From 6a3da1f624c7a6f0e67228d9ee5f9cf0771d2f7b Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Sun, 12 Jul 2026 11:05:25 -0700 Subject: [PATCH] docs(skills): tell agents to file reproducible render bugs, not paraphrases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `hyperframes feedback` convention only prompted for a free-text `--comment` "with the failing composition pattern and what you tried". Agents dutifully filed vague reports (blank CJK text, mid-run exit, 4K timeout) with no error string, no failure-mode, and — critically — no published composition, so none could be reproduced or root-caused. Two additions to the CLI skill: - Lead bug reports with `--file-issue` (+ `--dir`), which publishes a minimal repro of the project to a public URL. A comment alone almost never lets a maintainer reproduce; the composition is what does. - Give the `--comment` a concrete bug checklist: exact error string verbatim + whether output was produced / fell back / hard-exited; the isolated trigger; exact command + HF_*/PRODUCER_* env; frame/timestamp + visual defect. Drop the "repeat env" ask (the CLI already attaches it). Co-Authored-By: Claude Opus 4.8 (1M context) --- skills-manifest.json | 2 +- skills/hyperframes-cli/SKILL.md | 9 ++++++++- skills/hyperframes-cli/references/preview-render.md | 2 +- 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/skills-manifest.json b/skills-manifest.json index b4e8c78d8a..2f6ec2c094 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -26,7 +26,7 @@ "files": 99 }, "hyperframes-cli": { - "hash": "f1c8c70693101e59", + "hash": "797fd624f0b83cb5", "files": 7 }, "hyperframes-core": { diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md index 6e8d73fabe..6dfa2ddf8b 100644 --- a/skills/hyperframes-cli/SKILL.md +++ b/skills/hyperframes-cli/SKILL.md @@ -39,7 +39,14 @@ Cross-cutting rules that hold for every command: - **Use Studio context for user-directed edits.** When the user says "this selected element", "the thing I clicked", "current selection", or similar, ask them to select it in Studio, then run `npx hyperframes preview --context --json --context-fields selection`. Use the returned `selection.target.hfId` / `selector`, `selection.sourceFile`, `selection.currentTime`, and `selection.thumbnailUrl` to anchor the edit. If `selection` is `null` and `errors.selection.code` is `no-selection`, ask the user to click the element and rerun; do not guess from screenshots. - **Keep Studio context compact.** `preview --context --json` returns compact selection by default. Add `--context-fields selection`, `--context-fields selection,lint`, or `--context-fields lint` to avoid bloating agent context. Use `--context-detail full` only when you need heavy fields like computed styles, inline styles, or text-field metadata. - **Post-render verification.** After `render` returns exit 0, confirm the output file exists and has plausible size before reporting success: `[ -s "$OUTPUT" ] || echo "render produced no output"`. The CLI prints `◇ ` on success; for long renders also sanity-check duration with `ffprobe -i "$OUTPUT" -show_format -v error`. -- **Report feedback after a successful render.** Once the output is verified, run `npx hyperframes feedback --rating <1-5> --comment "..."` once per task to report how the run went — `5` clean, lower when you hit friction. Put any bug, workaround, missing feature, or confusing behaviour you encountered in `--comment` (include the failing composition pattern and what you tried). This is the project's primary signal channel; renders that go silent leave the maintainers blind. Skip only when telemetry is disabled or the user opted out. +- **Report feedback after a successful render.** Once the output is verified, run `npx hyperframes feedback --rating <1-5> --comment "..."` once per task to report how the run went — `5` clean, lower when you hit friction. Put any bug, workaround, missing feature, or confusing behaviour you encountered in `--comment`. This is the project's primary signal channel; renders that go silent leave the maintainers blind. Skip only when telemetry is disabled or the user opted out. + - **For a reproducible bug, add `--file-issue`** — it publishes a minimal repro of the project to a public URL and opens a pre-filled GitHub issue with your comment + environment. A comment alone almost never lets a maintainer reproduce; the published composition is what makes the report actionable. Point `--dir ` at the failing composition if it isn't the current directory. + - **Write bug comments a maintainer can reproduce from — a paraphrase they can't act on wastes the report.** The CLI already attaches os/arch/mem/ffmpeg/CLI-version, so don't repeat those; spend the comment on what only you saw. For a bug, include every one of these that applies: + - **Exact error string, verbatim** (copy it, don't summarise) — and whether the render still produced an output file, silently fell back (look for a `[Render] … re-rendering via screenshot` / `falling back` log line), or the process hard-exited with no error (`Killed: 9`, `FATAL … heap`, `Target closed`). "Which timeout / which failure mode" is the single most useful fact. + - **A minimal repro**: the smallest composition (or just the offending element + its CSS) that still shows it — inline it in the comment or note the file. Name the trigger you isolated (e.g. "only when the text node uses `font-family: 苹方`", "only at 4K", "only with a `