Building Feedback Artifacts
Overview
When a human needs to review your output, understand source material, or explore a project/system, a wall of chat text is a poor medium. Build a purpose-shaped interactive artifact instead: either an inline visual widget (quick in-session glance) or a self-contained HTML file (heavy, item-by-item, multi-session, or sent to other people).
Core principle: match the review medium, language, and feedback loop to the real reviewer and decision, not to your convenience. This is not a generic /html skill. The point is not to make HTML by default; the point is to keep humans in the loop when plain chat would hide the judgment work.
This skill has three mutually exclusive task families. Do not blend their templates, UI vocabulary, or return paths:
| Family |
Use when |
Primary human action |
Return path |
Read next |
| External feedback |
A colleague, user, customer, friend, or expert reviews a concrete artifact |
Approve, annotate, compare, correct, or comment |
JSON export with self-contained records |
references/template-selection.md, then the selected archetype |
| Personal source learning |
The human reads a notebook, paper, repo walkthrough, or long source document to understand it |
Ask questions, quote passages, mark follow-ups |
Copy current-round Markdown to the agent; JSON is backup/debug |
references/template-selection.md + references/source-led-package-schema.md |
| Project/system understanding |
The human needs to understand a project's structure, data flows, prompts/configs, or runtime behavior |
Explore map/flow/assets; optionally leave comments |
Copy current-round Markdown to the agent; JSON is backup/debug |
references/template-selection.md, then project or interactive schema |
If the intended audience or primary action is unclear, pause and ask. The common failure mode is treating personal learning or system exploration as an external feedback review, which creates confusing forms, leaked internal context, and the wrong export semantics.
Invariants — the bottom line for every artifact
Three principles hold across every intent, audience, and scope; full rationale in references/interaction-principles.md.
- Human-centric — the UI serves human judgment, not JSON prettified into a page. Carry information with layout / state / hierarchy, not sentences describing it; render content as the reviewer reads it (tables as tables, code highlighted, markdown rendered, business labels instead of raw keys); collapse repetitive context; make the thing being judged visually dominant.
- Parse-first — parse the source material into the selected task-family contract first, then render. Never scrape feedback back out of the DOM or free text.
- Agent-readable — expose the right machine API for the selected family:
window.getExternalReviewExport() for external review, or window.getCommentQueueExport() + window.getSubmissionPrompt() for learning/understanding artifacts.
- Speak the reviewer's language — never hardcode UI language. The bundled templates ship a chrome dictionary in 7 locales (en, zh, ja, ko, es, fr, de); declare the reviewer's locale in the package and the page localises itself and sets
<html lang>. Write the content you inject in the reviewer's language too — the dictionary only covers buttons, labels, and keyboard help.
| Family |
Where the locale goes |
| External feedback |
artifact.language in external-review-package.v1 |
| Learning / understanding |
package.locale (or meta.locale for the interactive model) |
Unknown or missing locales fall back to English; regional tags such as zh-CN resolve to their base language. To add a locale, add i18n/<lang>.json with the same key set — npm run i18n fails the build if key sets drift.
An HTML-file artifact must also:
- Self-contained: all CSS/JS/data inline; no external fonts, CDNs, network, or images — one file the recipient double-clicks. Handed off locally,
localStorage is unreliable under file:// (Safari disables it), so make export the reliable hand-back and recommend a Chromium browser.
- Persist: save to
localStorage on every change; restore on load; never lose a reviewer's work to a refresh.
- Export on demand: a prominent button writes a JSON download whose every record is self-contained — the reviewed input + the output + the human's note, not just a pointer. Timestamped filename; human-readable fields on the surface, machine-only fields under
machineLocator.
- Operation help stays fixed and visible: keyboard / mode help is a usability floor, in a sticky chrome / status area — never deleted as "explanatory text".
- Open coding first: start with free-text notes only; impose no rating scale or fixed tags until failure categories are known from the data.
- Stay blind when calibrating: when collecting independent human judgment to calibrate a machine, keep machine verdicts, scores, and recommendations out of the UI — they anchor the reviewer.
Inline-widget form: lightweight, holistic, no persistence / export; wire interactions back to the conversation so the human's reaction returns immediately.
Personal learning and project/system explorers use a different feedback loop from external review artifacts: prefer offline comment queue mode. The human reads locally, adds comments from a fixed composer, optionally quotes selected text, and copies the current-round queue to the agent as Markdown. After a successful copy, those comments move into the full local history as submitted records and are not deleted. JSON remains available as a backup/debug export, not the primary action. Do not add a local server, direct agent calls, or floating selection toolbars unless the user explicitly asks for those stronger mechanics.
When to build one vs. just ask
Build an artifact only when at least one holds: multiple review targets; feedback must re-locate precisely back to a source; you expect several iterations; or the audience is other people. Otherwise ask directly in chat — an artifact for a one-off, single-target judgment is just overhead.
Not for: a single short answer (just say it), or a binary decision with no context (use the platform's question tool).
Step 1 — Define the review contract
Before designing the artifact, establish the contract:
- Reviewer: who will read this, and what do they know? Use their vocabulary in the UI.
- Primary action: what is the ONE thing they mainly do here — approve, compare, annotate, correct? This decides the layout's center of gravity. Do not let a secondary dimension (e.g. "which model is better") hijack the primary action (e.g. annotating each output). See
references/interaction-principles.md #11.
- Feedback shape: can a blank response mean OK/no comment, or must every item get a response?
- Return path: how will the feedback be used later by an agent or human?
Render for the reviewer, export for the workflow. The visible UI should contain human-readable labels and task context. Keep internal identifiers, paths, raw keys, debug/provenance, TODOs, and assembly notes out of the visible UI unless the reviewer explicitly needs them. Also keep instruction-context notes out of the visible UI: do not include wording meant for the requester, the agent, or the build process (for example "tell the team", "use this wording", "this page is for", "do not mention X"). If that guidance matters, convert it into reader-facing content or keep it only in build notes / export metadata. If later automation needs those values, put them in export metadata such as machineLocator.
Step 2 — Decide the form (inline widget vs HTML file)
A judgment over a few forces, not a fixed list. Lean by how the review will actually happen.
Pulls toward a self-contained HTML file:
- Audience is other people (must be sendable as one file).
- Review is heavy / item-by-item / high-volume / multi-session / multi-person — needs navigation, progress, and must survive a refresh.
- Feedback must accumulate and be exported as structured data.
- Needs to persist or be referenced later.
Pulls toward an inline visual widget (in-session):
- Audience is yourself, synchronously — react on the spot.
- A grasp-at-a-glance artifact: a diagram, a single chart, one comparison, a mockup — holistic comprehension beats working through items.
- Low volume, single pass, no need to persist or export.
- Tight loop: look → comment → you adjust → look again.
Heuristic: will this review need to save progress or hand back data? Yes → file. No → inline. The lists above are illustrative dimensions, not an enumeration — reason from the forces for novel cases.
digraph form {
a [shape=diamond, label="For other people, OR heavy/item-by-item, OR needs export?"];
file [shape=box, label="Self-contained HTML file"];
inline [shape=diamond, label="Inline widget mechanism available?"];
widget [shape=box, label="Inline visual widget"];
a -> file [label="yes"];
a -> inline [label="no"];
inline -> widget [label="yes"];
inline -> file [label="no (e.g. Codex)"];
}
Step 3 — Adapt to the runtime
Inline widgets are platform-specific; the HTML-file path is universal. REQUIRED: read references/platform-and-audience.md for the Claude Code ↔ Codex capability map (inline widgets, question tools, sandbox write scope, opening files) before relying on any platform-only tool. Rule: if you chose inline but the inline mechanism is unavailable on this runtime, fall back to a self-contained HTML file and open it.
Step 4 — Shape the content by task family and archetype
Read references/template-selection.md first. Pick exactly one task family, then choose the archetype/template inside that family.
For external feedback artifacts, pick the intent that matches the reviewer's primary action, then read its reference:
| Intent |
Situation |
Object structure |
Feedback action |
Reference |
| Explain / understand |
Understand what an agent did, a backend data pipeline, or a schema |
Ordered steps / flow stages / schema fields the agent renders to make hidden work legible |
Question + comment per unit; "understood" overall |
references/explain.md |
| Inspect / approve |
Eyeball an already-visual object (diagram, mockup, chart, dataset) |
One rich visual artifact |
Region notes + overall verdict |
references/inspect.md |
| Annotate / label |
Read many items and judge one-by-one (info-dense; the medium-volume default) |
Ordered list of items |
Per-item free-text note (open coding first) + state |
references/annotate.md |
| Compare / choose |
Weigh N options and pick or rate |
2–N candidates, co-present side-by-side (never behind a tab) |
Pick + reason + note |
references/compare.md |
For a simple decision over a few options with little context, use the platform's question tool instead of an artifact; build one only when the options need rich context to judge.
These archetypes are starting points, not mandatory templates — shapes the one workbench adapts to. When none fits, compose from the Invariants above, but keep the selected family and return path intact.
Step 5 — Review against the original intent before delivery
Before showing or handing off the artifact, do one explicit intent-fit pass. Re-read the original user request and the review contract, then remove anything that does not help the reviewer perform the primary action.
Check especially:
- Not a review target: remove records, tabs, sections, examples, appendix items, future-scope items, or "for reference only" material that the reviewer is not being asked to judge.
- Repeated content: if shared context has a single global review item, do not repeat it inside every unit unless the reviewer must judge each expansion separately.
- Redundant labels and badges: remove labels, badges, chips, headings, and helper text that restate information already made clear by the page structure, navigation, or a global review item. Status labels should earn their attention cost by changing the reviewer's judgment or action.
- Misleading side context: do not include data merely because it exists in the source package; include it only when it changes the human judgment.
- Wrong audience voice: remove notes written to the requester or the agent instead of the actual reviewer/reader. A meeting page, review package, or artifact should not leak scaffolding like "make sure everyone understands", "the page should say", "avoid this wording", or other process reminders.
- Machine-only detail: keep ids, paths, raw keys, provenance, debug fields, and locator data out of the visible UI; keep them in export metadata when needed.
The artifact should answer: "What exactly is the human judging, and what can be safely ignored?" If a section's only purpose is to explain why it is out of scope, prefer removing it from the artifact and recording that exclusion in the build notes or source summary only when the reviewer needs that assurance.
Design method & knowledge (read when building the HTML)
The full build method and the design knowledge distilled from real iteration:
references/building-an-artifact.md — the end-to-end build method (intent → contract → archetype → human half → agent half → intent-fit review → validate), with per-step notes, counter-examples, and a final checklist. Start here when you actually build.references/interaction-principles.md — general, transferable interaction-design principles (medium-is-not-a-document, information hierarchy, comparand co-presence, focus-by-dimming, task-defined navigation unit, global state, zone coloring, modal interaction, primary-action-first, dual human/machine consumer, blind-when-calibrating). These outlast this skill and apply to any judgment UI.references/html-artifact-design.md — how those principles land in HTML (S1–S8 tactics), each mapping to a live implementation in the template.references/keyboard-conventions.md — the skill-wide Navigate/Edit dual-mode keyboard (Jupyter-style), identical across every artifact so a reviewer learns it once. Reuse verbatim.
Reusable template & scaffold
Use references/template-selection.md as the authoritative template map. In short:
- External feedback:
review-deck.template.html or assets/scaffold.html.
- Personal source learning:
source-led-learning-explorer.template.html only; read references/source-led-package-schema.md, not the minified template JS.
- Project/system understanding:
project-understanding-map.template.html for static structure, or interactive-system-explorer.template.html for runtime behavior; read the matching schema reference.
Do not borrow controls across families unless the user explicitly asks. In particular, do not put external-review JSON-first workflow into personal learning artifacts, and do not put personal knowledge-base or writing-angle blocks into a colleague-facing review artifact.
Canonical source
This repository is the Feedback Artifact Kit skill itself. The repo root is a loadable skill package: SKILL.md is the runtime entrypoint, while schemas/, scripts/, examples/, references/, and assets/ are the durable implementation assets.
- Use this repo as the canonical source for durable contracts, parse-first schemas, validation scripts, design knowledge, and reusable templates.
- When a task needs a stable package or feedback response contract, read
README.md and prefer schemas/ plus scripts/ over ad hoc JSON shapes. External review uses external-review-package.v1 for parsed input and external-review-feedback.v1 for JSON return; learning/understanding uses comment-queue.v1 for JSON backup/debug and Markdown as the primary return.
- Validate packages and returns with
scripts/validate-artifact-contracts.mjs (npm test) before trusting the round-trip.
- When real use of this skill reveals friction, ambiguity, missing metadata, or repeated artifact patterns, update this repo so the skill improves at the source.
Common mistakes
- Dumping a big comparison or long output list into chat instead of an artifact.
- Treating the page like a Markdown document: narrating with text what layout/state/controls should carry.
- Hiding a comparand behind a tab when the task is to compare — co-present them.
- Letting a secondary dimension (e.g. model comparison) take the center and cramp the primary action (e.g. annotation).
- Leaving "for reference only" or future-scope items in a review artifact when the reviewer is only being asked to judge the current-scope list.
- Repeating shared context inside every review unit after already giving it one global review item.
- Adding badges or chips that merely repeat the obvious page contract, such as "this unit has two questions" when the page already shows those two questions.
- Styling long text as a decorative card with a contrasting left edge stripe. For prose-heavy content, use shadcn-style neutral surfaces: subtle border, 8px-ish radius, restrained shadow, muted labels, and separators. Reserve accent color for primary actions, focus states, and selected controls.
- Deleting keyboard or mode help during cleanup because it looks like explanatory text; operation help must stay fixed and visible.
- An HTML file that pulls a web font or CDN — breaks offline and when sent to others.
- Imposing a 1–5 rubric on the first review (kills open coding; decide categories from the data first).
- Exporting only the note without the reviewed content (annotations become un-actionable later).
- Building only the human half and forgetting the agent-readable export; or leaking raw keys, file paths, TODOs, debug/provenance into the reviewer's UI.
- Making blank feedback ambiguous. If blank means OK/no comment, say that in the UI and export contract.
- Using an inline widget for something a colleague must receive (widgets live in your session; send a file).
- Relying on a one-platform-only tool inside a skill meant for both runtimes (see
references/platform-and-audience.md).
- Showing machine verdicts, scores, or a recommendation while collecting independent human judgment — it anchors the reviewer (stay blind when calibrating).
- Mixing task families: sending a source-learning explorer to a colleague who only needs to review a deliverable; using a review-deck for personal project understanding; or placing comment forms inside an explanatory inspector panel.
1---2name: feedback-artifact-kit3description: Building Feedback Artifacts4---56# Building Feedback Artifacts78## Overview9When a human needs to review your output, understand source material, or explore a project/system, a wall of chat text is a poor medium. Build a purpose-shaped **interactive artifact** instead: either an **inline visual widget** (quick in-session glance) or a **self-contained HTML file** (heavy, item-by-item, multi-session, or sent to other people).1011**Core principle: match the review medium, language, and feedback loop to the real reviewer and decision, not to your convenience.** This is not a generic `/html` skill. The point is not to make HTML by default; the point is to keep humans in the loop when plain chat would hide the judgment work.1213This skill has three mutually exclusive task families. Do **not** blend their templates, UI vocabulary, or return paths:1415| Family | Use when | Primary human action | Return path | Read next |16|---|---|---|---|---|17| **External feedback** | A colleague, user, customer, friend, or expert reviews a concrete artifact | Approve, annotate, compare, correct, or comment | JSON export with self-contained records | `references/template-selection.md`, then the selected archetype |18| **Personal source learning** | The human reads a notebook, paper, repo walkthrough, or long source document to understand it | Ask questions, quote passages, mark follow-ups | Copy current-round Markdown to the agent; JSON is backup/debug | `references/template-selection.md` + `references/source-led-package-schema.md` |19| **Project/system understanding** | The human needs to understand a project's structure, data flows, prompts/configs, or runtime behavior | Explore map/flow/assets; optionally leave comments | Copy current-round Markdown to the agent; JSON is backup/debug | `references/template-selection.md`, then project or interactive schema |2021If the intended audience or primary action is unclear, pause and ask. The common failure mode is treating personal learning or system exploration as an external feedback review, which creates confusing forms, leaked internal context, and the wrong export semantics.2223## Invariants — the bottom line for every artifact24Three principles hold across every intent, audience, and scope; full rationale in `references/interaction-principles.md`.25- **Human-centric** — the UI serves human judgment, not JSON prettified into a page. Carry information with layout / state / hierarchy, not sentences describing it; render content as the reviewer reads it (tables as tables, code highlighted, markdown rendered, business labels instead of raw keys); collapse repetitive context; make the thing being judged visually dominant.26- **Parse-first** — parse the source material into the selected task-family contract first, then render. Never scrape feedback back out of the DOM or free text.27- **Agent-readable** — expose the right machine API for the selected family: `window.getExternalReviewExport()` for external review, or `window.getCommentQueueExport()` + `window.getSubmissionPrompt()` for learning/understanding artifacts.28- **Speak the reviewer's language** — never hardcode UI language. The bundled templates ship a chrome dictionary in 7 locales (en, zh, ja, ko, es, fr, de); declare the reviewer's locale in the package and the page localises itself and sets `<html lang>`. Write the *content* you inject in the reviewer's language too — the dictionary only covers buttons, labels, and keyboard help.2930| Family | Where the locale goes |31|---|---|32| External feedback | `artifact.language` in `external-review-package.v1` |33| Learning / understanding | `package.locale` (or `meta.locale` for the interactive model) |3435Unknown or missing locales fall back to English; regional tags such as `zh-CN` resolve to their base language. To add a locale, add `i18n/<lang>.json` with the same key set — `npm run i18n` fails the build if key sets drift.3637An HTML-file artifact must also:38- **Self-contained**: all CSS/JS/data inline; no external fonts, CDNs, network, or images — one file the recipient double-clicks. Handed off locally, `localStorage` is unreliable under `file://` (Safari disables it), so make export the reliable hand-back and recommend a Chromium browser.39- **Persist**: save to `localStorage` on every change; restore on load; never lose a reviewer's work to a refresh.40- **Export on demand**: a prominent button writes a JSON download whose every record is self-contained — the reviewed input + the output + the human's note, not just a pointer. Timestamped filename; human-readable fields on the surface, machine-only fields under `machineLocator`.41- **Operation help stays fixed and visible**: keyboard / mode help is a usability floor, in a sticky chrome / status area — never deleted as "explanatory text".42- **Open coding first**: start with free-text notes only; impose no rating scale or fixed tags until failure categories are known from the data.43- **Stay blind when calibrating**: when collecting independent human judgment to calibrate a machine, keep machine verdicts, scores, and recommendations out of the UI — they anchor the reviewer.4445Inline-widget form: lightweight, holistic, no persistence / export; wire interactions back to the conversation so the human's reaction returns immediately.4647Personal learning and project/system explorers use a different feedback loop from external review artifacts: prefer **offline comment queue mode**. The human reads locally, adds comments from a fixed composer, optionally quotes selected text, and copies the current-round queue to the agent as Markdown. After a successful copy, those comments move into the full local history as submitted records and are not deleted. JSON remains available as a backup/debug export, not the primary action. Do not add a local server, direct agent calls, or floating selection toolbars unless the user explicitly asks for those stronger mechanics.4849## When to build one vs. just ask50Build an artifact only when at least one holds: **multiple review targets**; **feedback must re-locate precisely back to a source**; **you expect several iterations**; or the **audience is other people**. Otherwise ask directly in chat — an artifact for a one-off, single-target judgment is just overhead.5152Not for: a single short answer (just say it), or a binary decision with no context (use the platform's question tool).5354## Step 1 — Define the review contract55Before designing the artifact, establish the contract:56- **Reviewer**: who will read this, and what do they know? Use their vocabulary in the UI.57- **Primary action**: what is the ONE thing they mainly do here — approve, compare, annotate, correct? This decides the layout's center of gravity. Do not let a secondary dimension (e.g. "which model is better") hijack the primary action (e.g. annotating each output). See `references/interaction-principles.md` #11.58- **Feedback shape**: can a blank response mean OK/no comment, or must every item get a response?59- **Return path**: how will the feedback be used later by an agent or human?6061Render for the reviewer, export for the workflow. The visible UI should contain human-readable labels and task context. Keep internal identifiers, paths, raw keys, debug/provenance, TODOs, and assembly notes out of the visible UI unless the reviewer explicitly needs them. Also keep **instruction-context notes** out of the visible UI: do not include wording meant for the requester, the agent, or the build process (for example "tell the team", "use this wording", "this page is for", "do not mention X"). If that guidance matters, convert it into reader-facing content or keep it only in build notes / export metadata. If later automation needs those values, put them in export metadata such as `machineLocator`.6263## Step 2 — Decide the form (inline widget vs HTML file)64A judgment over a few forces, not a fixed list. Lean by how the review will actually happen.6566Pulls toward a **self-contained HTML file**:67- Audience is **other people** (must be sendable as one file).68- Review is **heavy / item-by-item / high-volume / multi-session / multi-person** — needs navigation, progress, and must survive a refresh.69- Feedback must **accumulate and be exported** as structured data.70- Needs to persist or be referenced later.7172Pulls toward an **inline visual widget** (in-session):73- Audience is **yourself, synchronously** — react on the spot.74- A **grasp-at-a-glance** artifact: a diagram, a single chart, one comparison, a mockup — holistic comprehension beats working through items.75- **Low volume, single pass**, no need to persist or export.76- Tight loop: look → comment → you adjust → look again.7778Heuristic: *will this review need to save progress or hand back data?* Yes → file. No → inline. The lists above are illustrative dimensions, not an enumeration — reason from the forces for novel cases.7980```dot81digraph form {82 a [shape=diamond, label="For other people, OR heavy/item-by-item, OR needs export?"];83 file [shape=box, label="Self-contained HTML file"];84 inline [shape=diamond, label="Inline widget mechanism available?"];85 widget [shape=box, label="Inline visual widget"];86 a -> file [label="yes"];87 a -> inline [label="no"];88 inline -> widget [label="yes"];89 inline -> file [label="no (e.g. Codex)"];90}91```9293## Step 3 — Adapt to the runtime94Inline widgets are platform-specific; the HTML-file path is universal. **REQUIRED:** read `references/platform-and-audience.md` for the Claude Code ↔ Codex capability map (inline widgets, question tools, sandbox write scope, opening files) before relying on any platform-only tool. Rule: if you chose inline but the inline mechanism is unavailable on this runtime, fall back to a self-contained HTML file and open it.9596## Step 4 — Shape the content by task family and archetype97Read `references/template-selection.md` first. Pick exactly one task family, then choose the archetype/template inside that family.9899For **external feedback** artifacts, pick the intent that matches the reviewer's primary action, then read its reference:100101| Intent | Situation | Object structure | Feedback action | Reference |102|---|---|---|---|---|103| **Explain / understand** | Understand what an agent did, a backend data pipeline, or a schema | Ordered steps / flow stages / schema fields the agent renders to make hidden work legible | Question + comment per unit; "understood" overall | `references/explain.md` |104| **Inspect / approve** | Eyeball an already-visual object (diagram, mockup, chart, dataset) | One rich visual artifact | Region notes + overall verdict | `references/inspect.md` |105| **Annotate / label** | Read many items and judge one-by-one (info-dense; the medium-volume default) | Ordered list of items | Per-item free-text note (open coding first) + state | `references/annotate.md` |106| **Compare / choose** | Weigh N options and pick or rate | 2–N candidates, co-present side-by-side (never behind a tab) | Pick + reason + note | `references/compare.md` |107108For a simple decision over a few options with little context, use the platform's question tool instead of an artifact; build one only when the options need rich context to judge.109110These archetypes are starting points, not mandatory templates — shapes the one workbench adapts to. When none fits, compose from the Invariants above, but keep the selected family and return path intact.111112## Step 5 — Review against the original intent before delivery113Before showing or handing off the artifact, do one explicit **intent-fit pass**. Re-read the original user request and the review contract, then remove anything that does not help the reviewer perform the primary action.114115Check especially:116- **Not a review target**: remove records, tabs, sections, examples, appendix items, future-scope items, or "for reference only" material that the reviewer is not being asked to judge.117- **Repeated content**: if shared context has a single global review item, do not repeat it inside every unit unless the reviewer must judge each expansion separately.118- **Redundant labels and badges**: remove labels, badges, chips, headings, and helper text that restate information already made clear by the page structure, navigation, or a global review item. Status labels should earn their attention cost by changing the reviewer's judgment or action.119- **Misleading side context**: do not include data merely because it exists in the source package; include it only when it changes the human judgment.120- **Wrong audience voice**: remove notes written to the requester or the agent instead of the actual reviewer/reader. A meeting page, review package, or artifact should not leak scaffolding like "make sure everyone understands", "the page should say", "avoid this wording", or other process reminders.121- **Machine-only detail**: keep ids, paths, raw keys, provenance, debug fields, and locator data out of the visible UI; keep them in export metadata when needed.122123The artifact should answer: *"What exactly is the human judging, and what can be safely ignored?"* If a section's only purpose is to explain why it is out of scope, prefer removing it from the artifact and recording that exclusion in the build notes or source summary only when the reviewer needs that assurance.124125## Design method & knowledge (read when building the HTML)126The full build method and the design knowledge distilled from real iteration:127128- **`references/building-an-artifact.md`** — the end-to-end build method (intent → contract → archetype → human half → agent half → intent-fit review → validate), with per-step notes, counter-examples, and a final checklist. Start here when you actually build.129- **`references/interaction-principles.md`** — general, transferable **interaction-design principles** (medium-is-not-a-document, information hierarchy, comparand co-presence, focus-by-dimming, task-defined navigation unit, global state, zone coloring, modal interaction, primary-action-first, dual human/machine consumer, blind-when-calibrating). These outlast this skill and apply to any judgment UI.130- **`references/html-artifact-design.md`** — how those principles land in HTML (S1–S8 tactics), each mapping to a live implementation in the template.131- **`references/keyboard-conventions.md`** — the **skill-wide** Navigate/Edit dual-mode keyboard (Jupyter-style), identical across every artifact so a reviewer learns it once. Reuse verbatim.132133## Reusable template & scaffold134Use `references/template-selection.md` as the authoritative template map. In short:135- **External feedback**: `review-deck.template.html` or `assets/scaffold.html`.136- **Personal source learning**: `source-led-learning-explorer.template.html` only; read `references/source-led-package-schema.md`, not the minified template JS.137- **Project/system understanding**: `project-understanding-map.template.html` for static structure, or `interactive-system-explorer.template.html` for runtime behavior; read the matching schema reference.138139Do not borrow controls across families unless the user explicitly asks. In particular, do not put external-review JSON-first workflow into personal learning artifacts, and do not put personal knowledge-base or writing-angle blocks into a colleague-facing review artifact.140141## Canonical source142This repository is the Feedback Artifact Kit skill itself. The repo root is a loadable skill package: `SKILL.md` is the runtime entrypoint, while `schemas/`, `scripts/`, `examples/`, `references/`, and `assets/` are the durable implementation assets.143144- Use this repo as the canonical source for durable contracts, parse-first schemas, validation scripts, design knowledge, and reusable templates.145- When a task needs a stable package or feedback response contract, read `README.md` and prefer `schemas/` plus `scripts/` over ad hoc JSON shapes. External review uses `external-review-package.v1` for parsed input and `external-review-feedback.v1` for JSON return; learning/understanding uses `comment-queue.v1` for JSON backup/debug and Markdown as the primary return.146- Validate packages and returns with `scripts/validate-artifact-contracts.mjs` (`npm test`) before trusting the round-trip.147- When real use of this skill reveals friction, ambiguity, missing metadata, or repeated artifact patterns, update this repo so the skill improves at the source.148149## Common mistakes150- Dumping a big comparison or long output list into chat instead of an artifact.151- Treating the page like a Markdown document: narrating with text what layout/state/controls should carry.152- Hiding a comparand behind a tab when the task is to compare — co-present them.153- Letting a secondary dimension (e.g. model comparison) take the center and cramp the primary action (e.g. annotation).154- Leaving "for reference only" or future-scope items in a review artifact when the reviewer is only being asked to judge the current-scope list.155- Repeating shared context inside every review unit after already giving it one global review item.156- Adding badges or chips that merely repeat the obvious page contract, such as "this unit has two questions" when the page already shows those two questions.157- Styling long text as a decorative card with a contrasting left edge stripe. For prose-heavy content, use shadcn-style neutral surfaces: subtle border, 8px-ish radius, restrained shadow, muted labels, and separators. Reserve accent color for primary actions, focus states, and selected controls.158- Deleting keyboard or mode help during cleanup because it looks like explanatory text; operation help must stay fixed and visible.159- An HTML file that pulls a web font or CDN — breaks offline and when sent to others.160- Imposing a 1–5 rubric on the first review (kills open coding; decide categories from the data first).161- Exporting only the note without the reviewed content (annotations become un-actionable later).162- Building only the human half and forgetting the agent-readable export; or leaking raw keys, file paths, TODOs, debug/provenance into the reviewer's UI.163- Making blank feedback ambiguous. If blank means OK/no comment, say that in the UI and export contract.164- Using an inline widget for something a colleague must receive (widgets live in your session; send a file).165- Relying on a one-platform-only tool inside a skill meant for both runtimes (see `references/platform-and-audience.md`).166- Showing machine verdicts, scores, or a recommendation while collecting independent human judgment — it anchors the reviewer (stay blind when calibrating).167- Mixing task families: sending a source-learning explorer to a colleague who only needs to review a deliverable; using a review-deck for personal project understanding; or placing comment forms inside an explanatory inspector panel.
Dexter-Yao