Developer Artifact Shaper
Use this skill when a task needs a plan, design note, investigation, review report, or handoff artifact.
Core Rule
Pick the artifact format from the job it must do:
- Markdown or TOON for canonical source, git diffs, CLI/TUI handoff, and long-lived docs.
- HTML for generated human review surfaces, dense comparisons, visual diagrams, prototypes, dashboards, or desktop app previews.
- Dual when a durable source and a rich review surface are both useful.
- Model review artifacts use durable text sources and generated static review views; do not make rendered diagrams the only source.
- Product, business, data, research, UX, and mockup artifacts use visual-source-first pairs when humans need visual inspection: agent-readable source plus generated visual review surface.
- High-fidelity is the default for UI, customer-facing workflow, product, and mockup review. Low-fidelity sketches are scratch only unless explicitly captured as evidence.
Do not make generated HTML the only durable source for a decision.
Process
- Identify the artifact purpose: decision, plan, investigation, review, report, runbook, product brief, business case, data definition, research synthesis, UX flow, handoff, or prototype.
- Identify the canonical source location.
- Decide the review surface: markdown, html, or dual.
- Name the evidence that must be linked.
- For visual artifacts, choose the family: product, business, data, research, or UX.
- Decide whether the artifact should be listed in
docs/artifacts/artifacts.manifest.json.
- State the update rule: edit source first, regenerate review surface second.
Output
Artifact Type
Canonical Source
Review Surface
Artifact Family
Evidence Links
Manifest Entry
Update Rule
1---2name: developer-artifact-shaper3description: Choose the right developer artifact type, source of truth, and review surface for a task.4---56# Developer Artifact Shaper78Use this skill when a task needs a plan, design note, investigation, review report, or handoff artifact.910## Core Rule1112Pick the artifact format from the job it must do:1314- Markdown or TOON for canonical source, git diffs, CLI/TUI handoff, and long-lived docs.15- HTML for generated human review surfaces, dense comparisons, visual diagrams, prototypes, dashboards, or desktop app previews.16- Dual when a durable source and a rich review surface are both useful.17- Model review artifacts use durable text sources and generated static review views; do not make rendered diagrams the only source.18- Product, business, data, research, UX, and mockup artifacts use visual-source-first pairs when humans need visual inspection: agent-readable source plus generated visual review surface.19- High-fidelity is the default for UI, customer-facing workflow, product, and mockup review. Low-fidelity sketches are scratch only unless explicitly captured as evidence.2021Do not make generated HTML the only durable source for a decision.2223## Process24251. Identify the artifact purpose: decision, plan, investigation, review, report, runbook, product brief, business case, data definition, research synthesis, UX flow, handoff, or prototype.262. Identify the canonical source location.273. Decide the review surface: markdown, html, or dual.284. Name the evidence that must be linked.295. For visual artifacts, choose the family: product, business, data, research, or UX.306. Decide whether the artifact should be listed in `docs/artifacts/artifacts.manifest.json`.317. State the update rule: edit source first, regenerate review surface second.3233## Output3435### Artifact Type36### Canonical Source37### Review Surface38### Artifact Family39### Evidence Links40### Manifest Entry41### Update Rule42
45ck