220 lines
8.3 KiB
Markdown
220 lines
8.3 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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.
|