Skip to content

Pipeline Plan 26

Jump to bottom
Seth Ford edited this page Feb 13, 2026 · 1 revision

The plan file is in a sensitive location. Let me present the plan directly since the pipeline artifacts directory requires special permissions.

Pipeline Replay & DVR — Implementation Plan

Summary

Add a DVR-style replay system to the Shipwright dashboard that lets users scrub through any completed (or running) pipeline run frame-by-frame. The feature reconstructs pipeline state from the existing events.jsonl event stream using an event-sourcing pattern — no new data collection is needed.

Key Architecture Insight

The foundation is already solid:

  • events.jsonl captures 40+ event types with timestamps, issue numbers, stages, and custom fields
  • dashboard/server.ts already has getPipelineDetail(), getTimeline(), and readEvents()
  • The dashboard frontend already has tab navigation, SVG pipeline visualization (renderPipelineSVG), and WebSocket state management
  • The timeline tab already shows Gantt-like stage segments

Files to Modify

File Action Purpose
dashboard/server.ts Modify Add 3 API endpoints + replay types + event reconstruction logic
dashboard/public/app.js Modify Add Replay tab with timeline scrubber, frame viewer, narrative panel
dashboard/public/styles.css Modify Add scrubber/frame viewer/narrative styles
dashboard/public/index.html Modify Add Replay tab button to navigation
scripts/sw-pipeline.sh Modify Enrich key events with activity descriptions
scripts/sw-pipeline-test.sh Modify Add replay-related test cases

Implementation Steps

Step 1-4: Backend (server.ts)

  1. Add ReplayFrame, PipelineNarrative, PipelineReplay interfaces
  2. Implement getPipelineReplay(issue) — event-sourcing walk that builds frames from filtered events, tracking current stage, completed stages, iteration count, test status
  3. Implement generateNarrative() — template-based summary from frame data (e.g., "Pipeline ran 8 stages in 12m. Built in 15 iterations with 2 auto-fixed failures.")
  4. Implement exportReplayMarkdown() — markdown report with timeline table, key decisions, event log

Step 5: API Routes

Add before the existing /api/pipeline/{issue} catch-all:

  • GET /api/pipeline/{issue}/replay — full replay data
  • GET /api/pipeline/{issue}/events — raw filtered events
  • GET /api/pipeline/{issue}/export — markdown download

Step 6-10: Frontend (app.js, styles.css, index.html)

  1. Add Replay tab (contextual — opens when clicking a pipeline)
  2. Timeline scrubber: SVG bar with color-coded stage segments (green=success, yellow=retry, red=fail, blue=running), draggable handle, keyboard arrows, play/pause auto-advance
  3. Frame viewer: stage progress bar, event details card, iteration counter, test status, decision highlights
  4. Narrative panel: summary paragraph, clickable key decisions list (seeks scrubber), stage breakdown table
  5. Permalink (/#replay/{issue}) + copy link + export button

Step 11-12: Pipeline & Tests

  1. Enrich stage.started/stage.completed/pipeline.completed events with activity field
  2. Add mock events.jsonl test data, verify frame count, stage progression, narrative keywords, markdown export

Task Checklist

  • Task 1: Add ReplayFrame, PipelineNarrative, PipelineReplay TypeScript interfaces
  • Task 2: Implement getPipelineReplay() event-sourcing function
  • Task 3: Implement generateNarrative() template-based narrative
  • Task 4: Implement exportReplayMarkdown() markdown generator
  • Task 5: Add /replay, /events, /export API routes (fix route ordering)
  • Task 6: Add Replay tab to dashboard navigation
  • Task 7: Build timeline scrubber SVG with drag/keyboard/playback
  • Task 8: Build frame viewer panel (stage progress, event details, decisions)
  • Task 9: Build narrative panel (summary, key decisions, stage breakdown)
  • Task 10: Add permalink (/#replay/{issue}) and export/copy buttons
  • Task 11: Enrich pipeline events with activity descriptions
  • Task 12: Add replay tests to sw-pipeline-test.sh
  • Task 13: Run npm test — all 22 suites pass

Testing Approach

Unit: Mock events.jsonl with complete pipeline run → verify frame count, stage progression, narrative keywords, markdown sections

Manual: Start dashboard → open Replay tab → drag scrubber → click key decisions → export markdown → test permalink

Integration: npm test — all 22 existing suites pass, no regressions

Definition of Done

  • Pipeline runs replayable after completion (event-sourced frames)
  • Timeline scrubber with color-coded stage segments
  • Frame viewer with stage state, event details, iteration info
  • Template-based narrative summary with key decisions
  • Shareable permalink per pipeline run
  • Markdown export via download button
  • All 22 test suites pass
  • Bash 3.2 compatible, follows existing code patterns

Clone this wiki locally