developer-artifact-shaper

name	developer-artifact-shaper
description	Choose the right developer artifact type, source of truth, and review surface for a task.

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

1. Identify the artifact purpose: decision, plan, investigation, review, report, runbook, product brief, business case, data definition, research synthesis, UX flow, handoff, or prototype.
2. Identify the canonical source location.
3. Decide the review surface: markdown, html, or dual.
4. Name the evidence that must be linked.
5. For visual artifacts, choose the family: product, business, data, research, or UX.
6. Decide whether the artifact should be listed in docs/artifacts/artifacts.manifest.json.
7. 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