Show Me Lifecycle Integration Research

Final decisions

Import HumanLayer's show-me as a reusable presentation skill, but do not make it a new phase or an unconditional step in every workflow. Its role is a conditional renderer: an owning skill produces the authoritative requirements, specification, plan, evidence, findings, or documentation, then show-me projects that bounded state into the smallest useful visual.

Every user request to explain, show, visualize, diagram, or walk through the current topic is a direct trigger. Automatic use should require a relationship that prose would make harder to understand, normally at least three mappings, branches, dependencies, actors, state changes, hierarchy levels, ownership boundaries, or spatial relationships. Simple facts, short status reports, one-step commands, and linear explanations should stay prose-only.

The default output should be inline and lightweight: a table, pseudocode, a call tree, a component or file tree, a shape-specific diff, or Mermaid. Focused HTML is an explicit artifact path, not an automatic consequence of invoking the skill. The visual supplements a terse textual conclusion and never becomes the only carrier of a requirement, decision, finding, or verification claim.

Install show-me in the default misc pack beside wait-what. Keep it out of handoff: handoffs are agent-to-agent state transfer and need no presentation layer.

write-backlog is the automatic exception to the general conditional trigger. Before provider writes, it presents the proposed module, epic, story, and dependency topology. Every written ticket then contains, in order, the complete text including user story and acceptance criteria, one compact show-me visual explainer, and a concise wait-what explanation. These presentation layers do not replace textual scope, traceability, or provider-native parent/dependency relations.

Upstream contract and provenance

The assessed upstream revision is 4d8d644ca747517973f58d7953f58d7cd07520cd. The authoritative show-me skill asks the agent to explain the current topic visually, skip preamble, keep prose brief, select the smallest useful view, and avoid overwhelming the user. The repository documents explicit installation and /show-me invocation in its README.

Supported shapes are pseudocode, runtime call trees, component trees, shallow file-responsibility trees, Mermaid flows, shape-specific diffs, copyable code, and one focused HTML diagram, infographic, or short deck. The plugin has no scripts, templates, references, or bundled assets. Optional HTML assumes a file write plus a platform-specific shell open operation, so the imported skill must route opening through the active product capability rather than preserving that command literally.

The upstream contract is explicit invocation. Automatic lifecycle use is a Harness integration decision, not an upstream behavior. That integration needs one shared trigger policy so wrappers do not invent inconsistent diagram rules.

Lifecycle placement matrix

Surface	Placement	Policy	Authority boundary
`requirements-grill`	After each persisted round update; again before shared-understanding approval	Assess every checkpoint; render when the frontier, glossary relationships, parked branches, or flow is genuinely complex	Grill status/log and accepted answers remain authority; the visual asks for no new decision
`create-spec`	After the complete spec is compiled and retained, when presenting it	Conditional or explicit-user trigger; no approval gate added	`SPEC.md`, user stories, and binary acceptance criteria remain authority; the visual cannot invent closure
`create-plan`	After task graph synthesis and before the final language gate/presentation	Strong trigger; render multiwave/dependency-heavy plans, skip trivial linear plans	`PLAN.md` task fields, dependencies, validation, and ledger remain executable authority
`implement-spec`	At the execution-board checkpoint, after each validated wave, and at final implementation-notes presentation	Strong trigger for multiwave or cross-surface delivery; on-demand for small changes	`PLAN.md`, `IMPLEMENTATION-NOTES.md`, tests, runtime evidence, screenshots, and acceptance audit remain authority
`docs-ingest-phase`	While authoring a complex routed flow or relationship-heavy concept; after public fragment sufficiency	Conditional content enrichment	Editable prose and cited sources remain complete without the visual; diagrams follow the target renderer's rules
Generic explanation	When the user asks to explain, show, visualize, diagram, compare, or walk through	Direct trigger	Presentation only; it does not mutate workflow state
`finder-phase`	After frontier recomputation and before presenting the selected next route	Conditional when the frontier has several claims, dependencies, or routes	Provider backlog/root state remains the living map; do not create a second durable map
`debugging-phase`	After the evidence matrix is synthesized and at exit	Conditional for causal chains, event chronology, or several hypothesis states	Cited evidence and `confirmed`, `rejected`, or `inconclusive` statuses remain proof
`review-phase`	After the immutable review report is assembled and retained	On-demand explanation of findings by lens, severity, location, or route	The frozen target and exact review report remain authority; no visual enters evidence generation
`prototype-phase`	When presenting variant comparison or the final accept/iterate/reject decision	Conditional; the runnable prototype is already the primary visual	Prototype artifact and verdict remain evidence; do not create redundant slides by default
`write-backlog`	Present proposed topology before provider writes; add a compact visual and then `wait-what` wording to every written ticket	Mandatory	Text, user stories, acceptance criteria, traceability, and provider-native parent/dependency relations remain authority

Where it should not become automatic

Outside backlog writing, wait-what repairs language and contextual vocabulary without making every question visual. Use show-me when the user asks or the simplified repitch still contains a genuinely complex relationship.
UI screenshots and verify-behavior evidence are observations of actual behavior. Generated diagrams cannot replace them or make an acceptance criterion pass.
Manual review checklists contain replayable actions and results. A visual may orient the user but cannot replace checklist rows.
Design and prototype workflows own product artifacts and human verdicts. Ordinary explanation must not silently invoke image generation, browser work, or durable prototype production.
Backlog visuals explain the proposed and written topology. They do not become product scope or provider dependency authority.
Uncertainty should not be hidden behind crisp arrows. If a useful visual is retained, mark inferred, unknown, blocked, and disputed relationships.

Presentation and accessibility contract

Use at most one visual by default. Prefer a table for exact mappings or comparisons, a flow/sequence/state diagram for dependent events, and a tree for hierarchy, ownership, or nesting. Keep the visual small enough to scan; use prose when simplification would distort the system.

Every visual has an adjacent textual conclusion and must not encode meaning by color alone. Mermaid diagrams should include accessible title and description metadata following the accTitle and accDescr guidance. Complex diagrams also need a structured text equivalent, consistent with the W3C complex-image guidance. Durable visuals need source links, renderer validation, and the same update ownership as the page that contains them.

Proposed integration shape

Import the pinned upstream skill under the shared skills source, preserve its license and provenance, and place it in the default pack that makes it available to lifecycle wrappers and generic explanations through the default misc pack.
Add one reusable Harness trigger contract: invoke when the user explicitly asks for a visual explanation or when a compact visual materially clarifies three or more mappings, branches, dependencies, actors, state changes, hierarchy levels, ownership boundaries, or spatial relationships.
Wire disclosed pointers into the six requested surfaces: requirements-grill, create-spec, create-plan, implement-spec, generic explanation guidance, and docs-ingest-phase.
Add conditional pointers to finder-phase, debugging-phase, and the final presentation step of review-phase. These are the highest-value additional placements.
Keep prototype-phase conditional. Make write-backlog present proposed topology and add one compact visual followed by wait-what wording to every written ticket.
Test the trigger boundary and authority boundary. Contract tests should prove explicit explanation requests invoke the skill, complex planning/debugging states assess it, simple outputs skip it, and visuals never replace durable source fields or behavioral evidence.

Remaining design questions

Whether requirements closure should always render a compact shared- understanding view or merely assess the trigger. The evidence favors a mandatory assessment and conditional visual.
Whether HTML artifact creation is excluded from automatic inner use entirely or allowed after explicit user artifact intent. The conservative default is explicit intent only.
Which shared root guidance owns the generic user-explanation trigger so it is declared once rather than copied into every skill.

Research lanes

Upstream lane: pinned source, formats, invocation, dependencies, and license.
Lifecycle lane: placement across requirements, planning, delivery, docs, Finder, debugging, review, prototypes, backlog, and handoff.
Critical lane: overlap, accessibility, renderer portability, false authority, persistence, token cost, and exclusions.

Show Me Lifecycle Integration Research

On this page