lda-wf/docs/superpowers/specs/2026-07-14-authoring-lifecycle-diagram-pass-design.md

Authoring Lifecycle Diagram Pass

Goal

Make Scene 8's prepared authoring lifecycle easier to present without returning to the older dense split-screen composition. Each beat should contain one large, immediately legible diagram and a compact factual receipt derived from the same reviewed evidence already used by the scene.

The result should preserve the current unclipped, spacious layout while making the empty space explain a lifecycle transformation.

Design Direction

Scene 8 uses one continuous visual language across all six beats:

• diagram nodes represent workflow or lifecycle objects;
• solid connectors represent existing relationships;
• an open or interrupted connector represents a typed validation failure;
• a newly completed connector represents the repair;
• object identity persists between adjacent beats so the audience sees a transformation rather than six unrelated result cards;
• exact product facts remain visible as a compact receipt, not as the primary composition.

The prepared assistant remains supporting context. It must not reclaim the screen area needed by the lifecycle diagram.

Presentation-Distance Hierarchy

Every beat must communicate its main state change from presentation distance. The primary layer uses large shapes, short labels, and unmistakable spatial relationships. Exact method names, schema paths, IDs, revisions, commands, and messages belong to the secondary receipt layer.

The screen must still make sense when the secondary text cannot be read:

• Discover reads as sources feeding a typed capability;
• Draft reads as a complete workflow;
• Diagnose reads as a workflow with one visibly broken route;
• Repair reads as that same route restored;
• Artifact reads as a workflow frozen into a version;
• Deployment reads as requirements bound into a runnable deployment.

Technical evidence remains present and selectable, but it must not become the visual headline or compete with the diagram.

Beat Compositions

Discover

Show the three configured local source IDs feeding one capability contract. The contract exposes its input, output, and outcome shape. The source inventory count and capability name remain in the receipt.

The audience-facing claim is: agents discover typed capabilities before they author a workflow.

Draft

Show a large workflow graph:

read_documents --ok--> analyze --ok--> END

The step input projection appears on the first connector. Revision, workspace ID, step count, and route count remain in the receipt. The diagram should reuse the established workflow graph vocabulary without introducing an independent graph data model.

The audience-facing claim is: the draft is a mutable, inspectable workflow structure rather than a hidden chat transcript.

Diagnose

Reuse the Draft graph in the same spatial arrangement. Render the analyze.ok route as an incomplete connection that stops before END. Place one short, large label such as Missing route beside that break. Keep the typed diagnostic code, schema path, and message in the compact receipt rather than in the primary diagram.

The prepared fault-injection command remains available as secondary evidence, but it must not compete with the broken route.

The audience-facing claim is: validation identifies a concrete graph defect and the exact location that needs repair.

Repair

Preserve the Diagnose composition and complete the missing connection. The route changes from interrupted to valid, revision 3 becomes revision 4, and the diagnostic count becomes zero. Motion may draw or reveal the repaired segment, but the final state must remain fully visible when motion is disabled.

The audience-facing claim is: repair is a focused mutation followed by deterministic revalidation.

Artifact

Show the repaired draft transforming into a locked, immutable artifact. The artifact retains the workflow silhouette while gaining an identity and version. Required source contracts remain visibly attached to it rather than appearing as an unrelated list.

The receipt contains the artifact ID, version, and exact required source IDs.

The audience-facing claim is: an artifact freezes a validated workflow definition into a reusable version.

Deployment

Show the artifact requirements on the left, their concrete configured source bindings in the middle, and one runnable deployment on the right. This is a binding map, not another generic card grid. The deployment ID and runnable status remain in the receipt.

The audience-facing claim is: deployment binds logical requirements to runtime sources and validates readiness for a persisted run.

Component Boundary

AuthoringPhaseVisual remains the evidence-union dispatcher. Each evidence variant renders a shared diagram shell containing:

1. a dominant diagram region;
2. an accessible text equivalent or labelled structure;
3. a compact factual receipt.

Shared visual primitives should cover only recurring lifecycle concepts:

• workflow node;
• source or requirement node;
• directed relationship;
• broken relationship;
• lifecycle object identity;
• compact receipt row.

Do not create a general-purpose diagram framework. Reuse an existing graph renderer when it improves routing or interaction; use semantic HTML and CSS for fixed one-dimensional mappings. Avoid hand-calculated arbitrary connector geometry.

Evidence And Truthfulness

All labels and relationships come from PreparedLifecycleStepProjection["evidence"] or the reviewed evidence catalog. The visual layer must not introduce a second set of lifecycle facts.

The prepared authoring sequence remains replay evidence. The diagrams must not imply that Scene 8 performs live authoring RPC calls.

Responsive Behavior

At 1280x720, the diagram should occupy most of the result height and remain readable without scrolling. At 1024x768, the diagram may tighten or stack fixed mapping columns, but the result root must not clip or overflow its bounded viewport.

On narrower presenter/mobile surfaces, horizontal diagrams may become a contained, scrollbar-hidden pan region. Factual receipts wrap below the diagram instead of shrinking labels below readable size.

Motion

Motion communicates continuity only:

• Draft to Diagnose preserves node positions;
• Diagnose to Repair completes the missing route;
• Repair to Artifact changes object state while preserving the workflow silhouette;
• Artifact to Deployment separates requirements into concrete bindings.

No blur, pan-in on unchanged content, bounce, or repeated entrance animation. Reduced-motion mode renders each final state immediately.

Accessibility

• Every diagram has a named region.
• Connector meaning is available in text, not color alone.
• Broken and repaired states expose explicit labels.
• IDs and commands remain selectable text.
• Decorative icons are hidden from assistive technology.

Verification

Add focused tests that assert:

• each beat renders the correct diagram kind;
• Draft, Diagnose, and Repair preserve the same workflow node identities;
• Diagnose exposes the missing analyze.ok connection;
• Repair exposes the restored connection and zero diagnostics;
• Artifact preserves the exact artifact identity, version, and requirements;
• Deployment maps every requirement to its configured source;
• no visual introduces facts absent from reviewed evidence.

The browser smoke review must also include a presentation-distance check: at the full-slide screenshot scale, a reviewer should identify the primary state change without reading receipt-sized text.

Run the presentation tests, console typecheck, and production build. Capture all six beats at 1280x720 plus Discover, Diagnose, and Deployment at 1024x768. Confirm each result has no unintended internal overflow and remains readable with reduced motion enabled.

After the visual pass, review the presenter script for all six beats against the rendered screen. Each beat should support one short spoken claim anchored to the dominant diagram. Revise the script only when it describes a removed visual, omits the new focal transformation, or uses terminology that is harder to say than the diagram requires. Do not expand the script merely because the diagram contains more detail.

Out Of Scope

• changing the prepared assistant conversation;
• live authoring RPC execution;
• redesigning the lifecycle rail or presentation chrome;
• adding arbitrary graph editing;
• restoring the previous dense two-screenshot layout.