Sequence Status Workflow - Design Specification

Executive Summary

This document specifies a redesigned workflow diagram for sequence statuses. The goal is to create a compact, scannable visualization that can be understood in under 5 seconds.

Current Problems (Analysis)

Problem	Root Cause
Too tall (720px)	Vertical stacking of every state; wastes horizontal space
Arrows pointing wrong	Rejected arrow goes to `completed` (line 99-100) instead of `rework_required`
Complex branching	4D/2D split shown as equal-weight paths; cognitive overload
Rework loop unclear	Loop-back arrow is tiny text on rotated label; hard to parse

Recommended Approach: Two-Track Horizontal Layout

Why This Approach?

Horizontal flow matches reading direction - Left-to-right progression is intuitive
Parallel tracks show branching clearly - 4D track above, 2D track below, visually distinct
Compact width - Fits in typical doc/readme viewport (800px)
Rework as annotation - Not a full path; shown as a simple return arrow with clear label

Other approaches considered:

Approach	Rejected Because
Compact Grid	Hard to show flow direction; looks like a table
Simplified Linear	Loses important 4D/2D branch information
Swimlane	Adds visual complexity for minimal benefit

Dimensions

viewBox: "0 0 800 280"

Width: 800px - Fits in most markdown viewers, GitHub, docs
Height: 280px - Compact; no scrolling required
Padding: 20px on all sides

Layout Grid

The diagram uses a 5-column horizontal grid:

Column	X Position	Content	Width
1	20-140	Initial states (stacked)	120px
2	180-300	Labeling states (stacked)	120px
3	340-460	Review states (stacked)	120px
4	500-620	Final states (stacked)	120px
5	660-780	End state	120px

Row positions:

Track labels: y=20 (small text)
4D track: y=60 (center of state boxes)
2D track: y=140 (center of state boxes)
Shared path: y=100 (center, for converged flow)
Legend: y=250

State Positions (Exact Coordinates)

Column 1: Initial (Stacked Vertically, Centered)

All three initial states share one column, shown as a compact vertical stack:

State	x	y	Notes
`unattempted`	80 (center)	60	Top of stack
`pending`	80 (center)	100	Middle
`ready_for_annotation`	80 (center)	140	Bottom; branch point

Box dimensions: 130x28 each (compact)

Column 2: Labeling (Two Tracks)

State	x	y	Track
`labeling_4d`	240 (center)	60	4D track
`labeling_2d`	240 (center)	140	2D track

Box dimensions: 110x28 each

Column 3: Review (Two Tracks + Transition)

State	x	y	Track
`review_4d`	400 (center)	60	4D track
`ready_for_2d`	400 (center)	100	Transition (between tracks)
`review_2d`	400 (center)	140	2D track

Box dimensions: 100x28 (review_4d, review_2d), 95x24 (ready_for_2d - smaller, transitional)

Column 4: Final Review

State	x	y	Notes
`final_review`	560 (center)	100	Centered vertically
`rework_required`	560 (center)	180	Below, connected by rejection arrow

Box dimensions: 110x28 (final_review), 120x24 (rework_required - red accent)

Column 5: Completion

State	x	y	Notes
`completed`	720 (center)	80	Upper
`customer_approved`	720 (center)	120	Lower; final state

Box dimensions: 100x28 each

Arrow Paths (Connections)

Happy Path (Main Flow)

All arrows use gray (#71717a) with arrowhead marker.

From	To	Path Type	Notes
`unattempted`	`pending`	Short vertical
`pending`	`ready_for_annotation`	Short vertical
`ready_for_annotation`	`labeling_4d`	Diagonal up-right	Branch to 4D
`ready_for_annotation`	`labeling_2d`	Horizontal right	Branch to 2D (or straight if 2D-only)
`labeling_4d`	`review_4d`	Horizontal right
`review_4d`	`ready_for_2d`	Diagonal down-right
`ready_for_2d`	`labeling_2d`	Diagonal down-right	Dotted/dashed (joining 2D track)
`labeling_2d`	`review_2d`	Horizontal right
`review_2d`	`final_review`	Diagonal up-right	Converge to center
`final_review`	`completed`	Horizontal right
`completed`	`customer_approved`	Short vertical

Rejection Path (Rework Loop)

Uses red (#ef4444) stroke and arrow.

From	To	Path Type	Label
`final_review`	`rework_required`	Short vertical down	”rejected” label
`rework_required`	`labeling_2d`	Curved return arrow (goes left, under the diagram, back to column 2)	“rework” small label

Rework arrow implementation:

Start: right side of rework_required
Curve: down and left, passing beneath the main flow
End: bottom of labeling_2d or labeling_4d (depending on what type of rework)
Use a simple curved path or rounded corner path, not complex bezier

Simplified rework alternative: Instead of a complex return arrow, show a simple annotation:

Small red text below rework_required: “returns to labeling”
This avoids arrow chaos while communicating the concept

Color Scheme (Minimal)

Use the existing color scheme but simplified:

Category	Fill	Stroke	Text
Queue (unattempted, pending, ready_for_annotation)	#27272a	#3f3f46	#e4e4e7
Labeling (labeling_4d, labeling_2d)	#1e1b4b	#6366f1	#e4e4e7
Review (review_4d, review_2d, final_review)	#422006	#f59e0b	#e4e4e7
Transition (ready_for_2d)	#27272a	#3f3f46 (dashed)	#a1a1aa
Complete (completed, customer_approved)	#052e16	#22c55e	#e4e4e7
Rework (rework_required)	#450a0a	#ef4444	#e4e4e7
Arrows (normal)	-	#71717a	-
Arrows (rejection)	-	#ef4444	-

Typography

Element	Font	Size	Color
State labels	system-ui, sans-serif	11px	#e4e4e7
Track labels (4D, 2D)	system-ui, sans-serif	10px	#71717a
Arrow labels (rejected, rework)	system-ui, sans-serif	9px	#ef4444
Legend text	system-ui, sans-serif	9px	#a1a1aa

Visual Hierarchy

Primary: State boxes and their labels (most prominent)
Secondary: Main flow arrows (gray, moderate weight)
Tertiary: Track labels “4D path” / “2D path” (faded)
Accent: Rejection/rework path (red, draws attention to exception flow)
Reference: Legend (bottom, small)

Rework Loop Design Decision

Recommendation: Use annotation, not complex arrow Instead of drawing a complex curved arrow that loops back:

<!-- Below rework_required box -->
<text x="560" y="210" text-anchor="middle" fill="#ef4444" font-size="9">
  returns to labeling
</text>

This is cleaner and avoids:

Arrow crossing other arrows
Visual clutter
Ambiguity about which labeling state it returns to

If the implementer wants the arrow version:

Draw a red dashed path from rework_required going DOWN, then LEFT under the diagram, then UP to labeling_2d
Keep stroke thin (1px) and dashed to differentiate from main flow

Legend (Compact, Horizontal)

Position: Bottom of diagram (y=250), centered horizontally

[Queue] [Labeling] [Review] [Complete] [Rework]

Each legend item: 12x12 square + label text, spaced 60px apart.

Implementation Notes for the Implementing Agent

Start with the grid - Lay out columns first, then place boxes
Draw happy path first - All the gray arrows for normal flow
Add rejection/rework last - So it overlays correctly
Test readability - View at 100% zoom in browser; all text must be legible
Keep stroke widths consistent - 1.5px for arrows, 1.5-2px for box borders
Rounded corners - rx=“5” for all state boxes (friendly, modern look)

Expected Result

A compact horizontal workflow that:

Shows the complete sequence status flow at a glance
Clearly distinguishes 4D and 2D tracks
Makes the happy path obvious (left-to-right)
Shows rework as an exception path without cluttering the main flow
Fits in 800x280 pixels

Comparison: Before vs After

Metric	Current	New Design
Dimensions	400x720	800x280
Aspect ratio	Portrait (0.56)	Landscape (2.86)
Scannable in 5 sec	No	Yes
Branch logic clear	No	Yes (stacked tracks)
Rework arrow correct	No (points to wrong state)	Yes (or uses text annotation)
Legend included	Yes	Yes (compact)

File Output

The implementing agent should save the new SVG to:

docs/images/workflows/sequence-statuses.svg

(Overwrites the existing file)

Integrations

Sequence statuses design spec

Sequence Status Workflow - Design Specification

Executive Summary

Current Problems (Analysis)

Recommended Approach: Two-Track Horizontal Layout

Why This Approach?

Dimensions

Layout Grid

State Positions (Exact Coordinates)

Column 1: Initial (Stacked Vertically, Centered)

Column 2: Labeling (Two Tracks)

Column 3: Review (Two Tracks + Transition)

Column 4: Final Review

Column 5: Completion

Arrow Paths (Connections)

Happy Path (Main Flow)

Rejection Path (Rework Loop)

Color Scheme (Minimal)

Typography

Visual Hierarchy

Rework Loop Design Decision

Legend (Compact, Horizontal)

Implementation Notes for the Implementing Agent

Expected Result

Comparison: Before vs After

File Output

​Sequence Status Workflow - Design Specification

​Executive Summary

​Current Problems (Analysis)

​Recommended Approach: Two-Track Horizontal Layout

​Why This Approach?

​Dimensions

​Layout Grid

​State Positions (Exact Coordinates)

​Column 1: Initial (Stacked Vertically, Centered)

​Column 2: Labeling (Two Tracks)

​Column 3: Review (Two Tracks + Transition)

​Column 4: Final Review

​Column 5: Completion

​Arrow Paths (Connections)

​Happy Path (Main Flow)

​Rejection Path (Rework Loop)

​Color Scheme (Minimal)

​Typography

​Visual Hierarchy

​Rework Loop Design Decision

​Legend (Compact, Horizontal)

​Implementation Notes for the Implementing Agent

​Expected Result

​Comparison: Before vs After

​File Output

Sequence Status Workflow - Design Specification

Executive Summary

Current Problems (Analysis)

Recommended Approach: Two-Track Horizontal Layout

Why This Approach?

Dimensions

Layout Grid

State Positions (Exact Coordinates)

Column 1: Initial (Stacked Vertically, Centered)

Column 2: Labeling (Two Tracks)

Column 3: Review (Two Tracks + Transition)

Column 4: Final Review

Column 5: Completion

Arrow Paths (Connections)

Happy Path (Main Flow)

Rejection Path (Rework Loop)

Color Scheme (Minimal)

Typography

Visual Hierarchy

Rework Loop Design Decision

Legend (Compact, Horizontal)

Implementation Notes for the Implementing Agent

Expected Result

Comparison: Before vs After

File Output