Skip to content

Show-don't-tell is under-applied in real builds — sections read as sparse text-in-cards #63

Description

@codeswithroh

The evidence

Real skill output (TraceGate) shows sections built mostly as small text-in-card clusters (a label, a short description, occasionally a tiny icon) surrounded by large amounts of empty dark background, with no real mockup, illustration, chart, or annotated capture carrying the section's point. The "evidence" and "expansion" sections specifically read as sparse — a handful of small cards floating in a mostly-empty viewport, not a rich, considered composition.

Why this is a real gap, not just this one build

SKILL.md Step 4's non-negotiable #1 (show-don't-tell) and references/anti-slop-checklist.md's gate 1 already state this as the project's top principle. The fact that a real build still came out this sparse means either the rule isn't concrete enough to act on, or it's being satisfied technically (a card is a visual, not a paragraph) without satisfying it in spirit (a card with one line of text and a tiny icon is barely more visual than the prose it replaced).

What to investigate and fix

  1. Tighten the show-don't-tell table in references/component-patterns.md with an explicit floor: a card in a proof/evidence section needs a real supporting visual (a chart, an annotated capture, a constructed diagram) to satisfy the rule — a label + description + small icon in a bordered box is the minimum bar for a feature card, not the ceiling for what a proof or evidence section should look like.
  2. Check whether this is a density problem, not just a content problem. Per references/style-tokens.md's Section-level padding work (already generous) and the diversification engine's archetype choices — is the model choosing an archetype (P# proof, F# feature) that's inherently light on visual surface area for a technical/evidence-heavy product, and not compensating with additional real visual weight (a chart, a diagram, a real annotated screenshot of the actual evidence output)?
  3. Cross-reference with Add a canonical narrative-arc discipline so every generated page tells a coherent story #62 (narrative arc) — a "proof" beat in the narrative arc should have a real visual-evidence floor of its own, since proof is the one place a page most needs to show, not describe.

Why this matters

Sparse, text-in-card sections are a specific, recognizable version of the generic-AI-output tell this whole skill exists to prevent — just a quieter one than a wall of prose. A page that's mostly empty dark space with small card clusters floating in it reads as unfinished, not restrained.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions