render ยท diff
v1.0.0 to v1.0.0
1 added, 0 removed. Audit A to A.
---
name: render
description: Turn a plan, PRD, review, audit, comparison, brainstorm, explanation
or architecture map into an interactive HTML page the user marks up in place,
then read their marks back and act on them. Every section carries an anchored
comment affordance, so feedback returns bound to the exact thing it was left on.
Use for "render this as a page", "make this visual", "I want to review this
properly", "turn this plan into something I can comment on", or to wrap another
skill's output (`render /review-code`). Not for generating a Mermaid diagram
into docs/ (use docs-diagram), not for designing a UI for a product being built
(use product-design-spec), and not for simplifying prose the user did not
understand (use wtf).
metadata:
+ summary: "Turn any output into an interactive HTML page you mark up in place, then read the marks back"
author: mgiovani
version: 1.0.0
disable-model-invocation: true
argument-hint: <mode|/skill|path> [subject]
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Task, Skill, Artifact
---
# Render
Build a page the user can work, not a document they have to scroll. Long
findings lists, requirement inventories, option matrices and step plans all lose
their shape as linear markdown. This skill gives them one, and gives the user a
way to answer back that survives the round trip.
## Invocation forms
| Form | Behavior |
|------|----------|
| `render <mode> [subject]` | Build that mode's page for the subject |
| `render /<skill> [args]` | Run the wrapped skill, then render its output in the matching mode |
| `render <path>` | Read an existing file and convert it to its matching mode |
| `render` | Show the mode table and ask which one; never pick one silently |
## Modes
| Mode | The page is | Per-item verdicts |
|------|-------------|-------------------|
| `prd` | Requirements grouped by family, the evidence behind each | keep / change / drop |
| `plan` | Ordered steps, their dependencies, the files each touches | approve / rework / cut |
| `review` | Findings by severity and file, with the code excerpt | fix / won't fix / discuss |
| `audit` | Whole-repo findings, filterable by area and severity | same triage as review |
| `compare` | Options against weighted criteria, evidence per cell | pick a winner |
| `brainstorm` | Idea cards, the tension each one resolves, by theme | shortlist / park / drop |
| `explain` | The one-line answer, the mechanism, then detail on demand | none, comments only |
| `map` | Module graph, data flow, entry points | none, comments only |
Each mode's contents are specified in `references/<mode>.md`. Load only the one
you need, and load it after the mode is settled.
## Workflow
### 1. Resolve the mode
From the first argument:
- A mode name: use it.
- A skill name with a leading slash: run that skill first, then map its output
to a mode using the table in `references/wrapping.md`.
- A file path: read the file, then pick the mode its content matches. State
which mode you picked and why, in one line, before building.
- Nothing: print the mode table above and ask. Do not guess.
### 2. Gather the real content
The page renders what the run actually produced. Never invent an item to fill a
grid, never write placeholder copy, never carry an example from a reference file
into a real page. If a section would be empty, the page says it is empty and
why.
A wrapped skill supplies its own output, and a file supplies its contents. With
a bare mode, do the work the mode implies before rendering: `render review` on a
diff runs the review first.
### 3. Load the design guidance
Announce `Using artifact-design to calibrate this page's treatment` and load the
`artifact-design` skill before writing any HTML, via the `Skill` tool where one
exists. If the page will declare a runtime capability, load
`artifact-capabilities` the same way.
Both are host skills rather than siblings in this repository, so they are absent
on some agents. Where neither can be loaded, say so in one line and apply
[references/page-kit.md](references/page-kit.md) directly: it carries the
theming rules, the type and layout floor, and the state contract this skill
depends on. The page is still built; it just loses the calibration pass.
### 4. Build the page
[references/page-kit.md](references/page-kit.md) holds the document skeleton
and the state block, plus how a page is written and published. Anchors and the
comment affordance are specified in
[references/feedback-loop.md](references/feedback-loop.md), and every mode
carries them. Reach for [references/diagrams.md](references/diagrams.md) only
once the content turns out to have a shape worth drawing.
Six rules hold across every mode:
1. **Every page is annotatable.** Anchors and the comment affordance are not a
per-mode feature. A page without them cannot return feedback, which is the
point of the skill.
2. **Real content only.** See step 2.
3. **Theme-correct in all three states.** Define the light palette as tokens on
bare `:root`, redefine those tokens under
`@media (prefers-color-scheme: dark)` guarded by `:not([data-theme="light"])`,
and redefine them again under `:root[data-theme="dark"]`. Give `body` an
explicit token background. A color whose only definition sits inside a media
block renders one theme's text on the other theme's background.
4. **The page is greyscale.** Color is spent only on the verdict vocabulary,
where it distinguishes marked items at a glance. Selected and pressed states
are an ink fill, not a hue; there is no brand accent, no colored heading or
filter, and no colored diagram. See the Color section of
[references/page-kit.md](references/page-kit.md).
5. **Diagrams are inline SVG built from the page's own tokens.** Mermaid brings
its own theme and fights the three-state setup above.
6. **State drives the DOM, never the reverse.** The page renders from its
embedded state object. Saving serializes that object, never the live DOM.
### 5. Deliver and report
Report the output path, the published link if there is one, and whatever count
matters for this mode. Then say how to answer back: marks and comments are both
kept by the page, so the user presses save and tells you. Keep this to two
lines.
### 6. Read the marks back
When the user says they have marked it, read the page back per
`references/feedback-loop.md`, then act on what it returns. Group your response
by what they decided, not by page order, and name any comment whose anchor no
longer resolves rather than dropping it.
## Worked examples
**Bare mode** (`render compare postgres vs sqlite for the vault store`): gather
the real criteria from the project's own constraints and build the matrix with
evidence behind every cell. Publish it, report the link, and wait. The user
picks a winner on the page; you read it back and write the decision up.
**Wrapping a skill** (`render /review-security`): run `review-security` to
completion first. Its output is a severity-ranked list with file:line evidence,
which maps to `review` mode. Build the triage board from the findings it
actually produced, one anchor per finding.
**Converting a file** (`render docs/plans/auth.md`): read it first. It turns out
to be an ordered step list with dependencies, so say "rendering as `plan` mode"
before building. Do not rewrite the plan's content while converting it.
**No argument** (`render`): print the mode table and ask which mode. Build
nothing until that is answered.
## Notes
- The wrapped skill never needs to know this skill exists. `render /<skill>`
runs it unchanged and renders what comes out.
- Re-running `render` on the same subject updates the same page when the output
path matches. This is the intended way to revise, and preserving the reader's
marks across it is a required step, not a side effect: read the existing state
block and embed it in the new page, per the re-render rules in
[references/feedback-loop.md](references/feedback-loop.md).
- Two modes carry no verdict controls, `explain` and `map`. They still carry
anchored comments, which is usually the only feedback those pages need.