spk-doctrine-show-me

name	spk-doctrine-show-me
description	Explain Spec Kitty work with compact, checkable visuals. Use for specs, plans, architecture, control flow, diffs, status boards, or whenever prose obscures structure.

spk-doctrine-show-me

Make the current point visible. Skip the preamble, keep prose brief, and pick the smallest representation that answers the question. Do not add a diagram when a sentence or short list is clearer.

Choose the Shape

• Logic or an algorithm: compact pseudocode.
• Runtime behavior: call tree or sequence diagram.
• UI composition: component tree with only relevant state and boundaries.
• Ownership or refactor scope: shallow file tree with one responsibility per entry.
• Existing-to-proposed change: diff over the matching tree, flow, or pseudocode.
• Domain lifecycle: state diagram.
• Data or concept relationships: entity-relationship or class diagram.
• Architecture: C4 Context first, then Container or Component only when useful.
• Dense visual UI/layout comparison: one focused HTML artifact when the host can open it; keep durable project documentation diagram-as-code.

Place each visual beside the text it supports. Include only the calls, files, states, relationships, and boundaries needed for the current decision. Label relationships and preserve source paths or identifiers that make the visual checkable against code and artifacts.

Load Spec Kitty's Diagram Doctrine

Prefer Mermaid inline; use PlantUML when richer layout, C4 support, or its DSL earns the rendering cost. Read references/spec-kitty-diagram-sources.md, then load only the needed toolguide, directive, or tactic through spec-kitty charter context --include .... It maps portable commands to the canonical Mermaid and PlantUML guides, C4 directive, diagram-review tactic, and bundled theme assets.

In specification, visualize actor flows, concepts, rules, and lifecycle states; do not smuggle implementation choices into product requirements. In planning, visualize architecture, data/control flow, boundaries, migrations, and risky interactions. Prose requirements and contracts remain authoritative.

Render /spec-kitty.status in a TUI

Use the command's Rich human output in a capable terminal. For a custom TUI, consume structured data instead of scraping ANSI output:

spec-kitty agent tasks status --json --mission <handle>

Keep lifecycle truth distinct from the current status display projection:

planned → claimed → in_progress → for_review → in_review → approved → done
Display: Planned → Doing → For Review → Approved → Done

For the five-group display only, fold claimed, in_progress, and in_review into Doing and mark claimed/review entries. Read blocked/canceled from work_packages[].lane, stale from work_packages[].is_stale, and review warnings from stalled_wps and stale_verdicts; show them off-board. On narrow screens, stack the same groups vertically.

Show Done progress (done_count / total_wps) separately from Weighted readiness (progress_percentage). Never label weighted readiness as completed work. JSON has no next_action: reproduce the human hint from mission_slug as spec-kitty next --agent <your-name> --mission <mission_slug>, with the caller supplying the agent. That command—not status—selects the exact workflow action.

Origin and Attribution

Adapted from HumanLayer's MIT-licensed show-me skill by Dexter Horthy: https://github.com/humanlayer/skills/tree/main/plugins/show-me/skills/show-me. The source article also credits Dillon Mulroy for the call-tree shape and Matt Pocock for HTML-explainer inspiration. Preserve the notice and provenance in references/humanlayer-origin-and-license.md when redistributing this skill.