lda-wf/docs/historical/superpowers/plans/2026-07-13-presentation-followup-visual-story-pass.md

Presentation Follow-up Visual And Story Pass Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make the remaining defense scenes explain their role clearly and use the available 720p canvas deliberately without inventing runtime evidence.

Architecture: Keep the existing React presentation compositor, storyboard metadata, and scene-specific projections. This pass changes scene copy, composition, and CSS only where the screenshot review found a concrete hierarchy problem; it does not introduce a second layout system, a new theme, or a new transport. The factual Scene 10 file browser remains a separate roadmap item.

Tech Stack: React 19, TypeScript, Vite, Vitest, Testing Library, existing CSS tokens, lucide-react icons, Playwright CLI.

Global Constraints

• Preserve the single Editorial Canvas and responsive 1280x720 / 1024x768 rehearsal targets.
• Do not reintroduce a stage-wide dark/light theme switch or blue accents on non-demo editorial scenes.
• Do not claim that a replay branch preserves a run identity when its recording uses another ID.
• Keep Scenes 3–5 structurally stable unless a copy or spacing change is required to explain the transition into Scene 7.
• Do not add an input-file browser in this pass; the factual browser is a separate product slice already tracked in docs/current_roadmap.md.
• Every visual change must have a route-level or component-level test and a screenshot check at both rehearsal viewports.

---

Task 1: Clarify The Opening And Lifecycle-to-Authoring Story

Files:

• Modify: web/apps/console/src/presentation/storyboard.ts
• Modify: web/apps/console/src/presentation/opening/OpeningThesisScene.tsx
• Modify: web/apps/console/src/presentation/SceneBody.tsx
• Test: web/apps/console/src/presentation/opening/OpeningThesisScene.test.tsx
• Test: web/apps/console/src/presentation/SceneBody.test.tsx

Interfaces:

• Consumes: SceneDefinition, SceneBeatDefinition, and the existing Scene 1/5/7 render paths.

• Produces: explicit opening and transition copy that distinguishes product goal, implemented contribution, lifecycle vocabulary, and authoring/repair work.

• Step 1: Add failing copy-contract tests.

Add assertions that the title beat exposes all three ideas without treating them as synonyms:

expect(screen.getByRole("heading", { name: /design and implementation of lda\.chat/i })).toBeInTheDocument();
expect(screen.getByText(/product goal.*AI agent.*workspace automation/i)).toBeInTheDocument();
expect(screen.getByText(/implemented contribution.*typed workflow substrate/i)).toBeInTheDocument();

Add a Scene 7 integration assertion that the authoring scene names its relationship to the lifecycle rather than presenting an isolated diagnostic screen:

expect(screen.getByText(/turns an agent proposal into a valid workflow/i)).toBeInTheDocument();

Run:

pnpm --dir web/apps/console test -- src/presentation/opening/OpeningThesisScene.test.tsx src/presentation/SceneBody.test.tsx

Expected: the new assertions fail because the current title/authoring copy does not expose those distinctions.

• Step 2: Update storyboard copy and scene framing.

Use copy with these meanings, keeping the existing title and product name:

Scene 1 title: The product goal: an AI agent for workspace automation.
Scene 1 substrate: The implemented contribution: a typed workflow substrate that external agents can operate.
Scene 5 lifecycle: Draft, Artifact, Deployment, and Run are the durable vocabulary behind reusable automation.
Scene 7 authoring: This is how an external agent proposal becomes a valid workflow: discover, author, diagnose, repair.

Render the first two Scene 1 statements as separate hierarchy levels in the existing opening composition. Do not make the phrase “AI agent” disappear; make the implementation boundary visible directly below it. Keep the three planner/tool-surface/runner nodes as supporting decomposition, not a second title.

• Step 3: Verify copy and accessibility.

Run the focused tests again and confirm the accessible heading remains unique after any scene transition animation:

pnpm --dir web/apps/console test -- src/presentation/opening/OpeningThesisScene.test.tsx src/presentation/SceneBody.test.tsx
pnpm --dir web/apps/console typecheck

Expected: focused tests and typecheck pass.

• Step 4: Commit.

git add web/apps/console/src/presentation/storyboard.ts web/apps/console/src/presentation/opening/OpeningThesisScene.tsx web/apps/console/src/presentation/SceneBody.tsx web/apps/console/src/presentation/opening/OpeningThesisScene.test.tsx web/apps/console/src/presentation/SceneBody.test.tsx
git commit -m "feat: clarify presentation opening and authoring story"

---

Task 2: Give Authoring And Prepared Lifecycle A Dominant Artifact

Files:

• Modify: web/apps/console/src/presentation/authoring/AuthoringPhaseVisual.tsx
• Modify: web/apps/console/src/presentation/authoring/PreparedAuthoringLifecycleScene.tsx
• Modify: web/apps/console/src/presentation/presentation.css
• Test: web/apps/console/src/presentation/authoring/AuthoringPhaseVisual.test.tsx
• Test: web/apps/console/src/presentation/authoring/PreparedAuthoringLifecycleScene.test.tsx

Interfaces:

• Consumes: existing authoring projection phases and the prepared lifecycle recording.

• Produces: a stable primary evidence region that is larger at 720p, with chat/phase rail remaining supporting context.

• Step 1: Write layout-contract tests.

Assert that the active diagnostic/repair evidence is marked as the primary region and the assistant remains a supporting region:

expect(screen.getByRole("region", { name: /validation repair evidence/i })).toHaveAttribute("data-visual-role", "primary");
expect(screen.getByRole("complementary", { name: /prepared authoring assistant/i })).toHaveAttribute("data-visual-role", "support");

Assert that the prepared lifecycle has a single primary lifecycle evidence region and a visible phase label at every beat.

• Step 2: Recompose only the existing grids.

Use the current CSS variables and data attributes. At 1280x720, allocate the main evidence region at least minmax(0, 1fr) of the available stage height after caption/footer; constrain the chat rail to its content rather than letting it determine the stage height. At 1024x768, collapse to the existing narrow layout without introducing page scroll.

For Scene 7, keep the five-stage rail but make the active evidence panel the dominant surface; do not scale all five cards equally. For Scene 9, keep the assistant transcript and lifecycle rail visible, but give the active phase evidence enough width for its operation/tool details to be read without opening a browser zoom.

• Step 3: Run component tests and screenshot checks.

pnpm --dir web/apps/console test -- src/presentation/AuthoringPhaseVisual.test.tsx src/presentation/PreparedAuthoringLifecycleScene.test.tsx
pnpm --dir web/apps/console typecheck

Capture and inspect:

/present#scene/authoring/diagnose
/present#scene/authoring/repair
/present#scene/prepared-lifecycle/validate
/present#scene/prepared-lifecycle/deployment

At both 1280x720 and 1024x768, verify the primary evidence is larger, the phase rail remains legible, and document.documentElement.scrollHeight === window.innerHeight.

• Step 4: Commit.

git add web/apps/console/src/presentation/authoring web/apps/console/src/presentation/presentation.css
git commit -m "feat: strengthen authoring and lifecycle visual hierarchy"

---

Task 3: Make Scene 10 Graph Beat Read As A Workflow Diagram

Files:

• Modify: web/apps/console/src/presentation/WorkflowGraphStage.tsx
• Modify: web/apps/console/src/presentation/styles/demo-workflow.css
• Modify: web/apps/console/src/presentation/DemoWorkflowScene.tsx
• Test: web/apps/console/src/presentation/WorkflowGraphStage.test.tsx
• Test: web/apps/console/src/presentation/DemoWorkflowScene.test.tsx

Interfaces:

• Consumes: GraphExecutionPresentation, canonical prepared graph nodes, and the existing React Flow graph component.

• Produces: a graph beat with readable node labels, intentional horizontal flow, and factual node/outcome semantics.

• Step 1: Add graph-contract tests before changing layout.

Assert the graph exposes exactly the canonical node set and that only real workflow nodes appear:

expect(screen.getAllByRole("button", { name: /workflow node/i })).toHaveLength(10);
expect(screen.queryByText(/cancel: no submitted output/i)).not.toBeInTheDocument();
expect(screen.getByText(/revision requested/i)).toBeInTheDocument();

Assert the graph container exposes data-graph-layout="horizontal" on the graph beat and that action, boundary, and outcome legends remain present.

• Step 2: Rebalance graph layout without hand-positioning connectors.

Continue using React Flow for node/edge coordinates. Change only the canonical node layout/configuration and graph viewport padding: use the existing horizontal layout, reserve enough vertical space for the two outcome branches, and enlarge nodes/labels through the graph’s size variables rather than per-node pixel offsets. Keep arrowheads, edge labels, and semantic node shape variants owned by the graph component.

Do not add a second SVG connector system. If a label collides, fix the node dimensions/layout inputs or React Flow edge label placement, not a one-off transform on the label.

• Step 3: Verify graph semantics and screenshots.

pnpm --dir web/apps/console test -- src/presentation/WorkflowGraphStage.test.tsx src/presentation/DemoWorkflowScene.test.tsx

Capture:

/present#scene/run-from-deployment/graph
/present#scene/run-from-deployment/operation
/present#scene/typed-human-boundary/approval

Expected: the graph reads left-to-right at both rehearsal viewports, no connector/label is detached, and the graph contains ten real workflow nodes rather than a synthetic cancellation node.

• Step 4: Commit.

git add web/apps/console/src/presentation/WorkflowGraphStage.tsx web/apps/console/src/presentation/styles/demo-workflow.css web/apps/console/src/presentation/DemoWorkflowScene.tsx web/apps/console/src/presentation/WorkflowGraphStage.test.tsx web/apps/console/src/presentation/DemoWorkflowScene.test.tsx
git commit -m "feat: clarify workflow graph presentation"

---

Task 4: Fill Evaluation And Conclusion Beats With Their Actual Claim

Files:

• Modify: web/apps/console/src/presentation/evaluation/EvaluationEvidenceScene.tsx
• Modify: web/apps/console/src/presentation/conclusion/ConclusionScene.tsx
• Modify: web/apps/console/src/presentation/presentation.css
• Test: web/apps/console/src/presentation/evaluation/EvaluationEvidenceScene.test.tsx
• Test: web/apps/console/src/presentation/conclusion/ConclusionScene.test.tsx

Interfaces:

• Consumes: evaluationEvidence, conclusion-model, scene beat focus metadata, and existing lucide icon mappings.

• Produces: denser evidence and conclusion boards that remain readable at 720p without adding unsupported claims.

• Step 1: Add beat-specific content contracts.

For Evaluation findings, assert that the six findings have a readable two-row arrangement, the campaign-size evidence remains present, and the validity statement is not hidden. For Conclusion conclusion, assert that the central contribution statement and planner/runtime boundary remain visible.

expect(screen.getByRole("group", { name: /evaluation evidence board/i })).toHaveAttribute("data-evaluation-focus", "findings");
expect(screen.getAllByRole("listitem")).toHaveLength(6);
expect(screen.getByText(/bounded longitudinal engineering evidence/i)).toBeInTheDocument();

• Step 2: Recompose the boards around a focal claim.

For Evaluation findings, use a readable 3 × 2 finding grid with icons and a compact but visible campaign/evidence strip. Remove unused vertical whitespace rather than shrinking typography. For Conclusion, keep the contribution flow centered, enlarge the contribution node and statement, and allow limits/future-work branches to recede on the conclusion beat while remaining available on their own beats.

Use existing editorial colors and icon mappings. Do not introduce a new blue theme or a generic dashboard/stat-card treatment.

• Step 3: Verify all final-scene beats.

pnpm --dir web/apps/console test -- src/presentation/EvaluationEvidenceScene.test.tsx src/presentation/ConclusionScene.test.tsx

Capture:

/present#scene/evaluation/cohort
/present#scene/evaluation/findings
/present#scene/conclusion/limits
/present#scene/conclusion/future
/present#scene/conclusion/conclusion

Expected: no scene is mostly empty at 1280x720, no text is clipped at 1024x768, and each beat has one obvious statement to present.

• Step 4: Commit.

git add web/apps/console/src/presentation/evaluation web/apps/console/src/presentation/conclusion web/apps/console/src/presentation/presentation.css
git commit -m "feat: strengthen evaluation and conclusion visuals"

---

Task 5: Full Follow-up Smoke And Documentation

Files:

• Modify: docs/current_roadmap.md
• Create: docs/runbooks/presentation-followup-visual-review.md
• Test: web/apps/console/src/presentation/PresentationRoute.test.tsx

Interfaces:

• Consumes: all four visual tasks, the existing rehearsal route manifest, and the current screenshot runner.

• Produces: route-level regression coverage and a dated visual review record that separates fixed visuals from the deferred factual input browser/live E2E work.

• Step 1: Add route regression coverage.

Add a table-driven smoke contract for the changed routes. It must assert the expected heading, primary visual role, and no outer scroll for the route-specific test harness. Use exact-one heading assertions with a settled wait, not getAllByRole(...).length > 0.

• Step 2: Run the complete gate.

pnpm --dir web test -- --run
pnpm --dir web typecheck
pnpm --dir web build
git diff --check

Expected: console, RPC, and server tests pass; typecheck/build pass with only the known Vite chunk-size warning.

• Step 3: Capture both viewports.

Run:

./scripts/presentation-rehearsal.ps1

Manually inspect the changed routes listed in Tasks 1–4 at both viewports. Record any remaining VISUAL, FACTUAL, PRODUCT, or BLOCKED item in docs/runbooks/presentation-followup-visual-review.md.

• Step 4: Update roadmap and commit.

Link the plan and review record from docs/current_roadmap.md. Keep the factual input browser, live end-to-end run, prepared revision run identity, and full screenshot inspection as explicit follow-ups if they remain unresolved.

git add docs/current_roadmap.md docs/runbooks/presentation-followup-visual-review.md web/apps/console/src/presentation/PresentationRoute.test.tsx
git commit -m "docs: record presentation visual follow-up pass"

---

Self-Review

• Scene 1 framing is covered by Task 1.
• Scene 5 to Scene 7 narrative continuity is covered by Task 1.
• Scene 7 and Scene 9 scale/readability are covered by Task 2.
• Scene 10 graph scale and semantics are covered by Task 3.
• Scene 10 factual input browser is explicitly excluded and remains roadmap item 9.
• Scene 13/14 density and focal claims are covered by Task 4.
• Both rehearsal viewports and route-level verification are covered by Task 5.
• Live execution and replay run-identity issues are not silently included in a visual pass.