PRD — Loom

Document Status

Draft V1

Purpose

This PRD defines the product requirements for Loom, the workflow surface and operator console for Cambium.

Loom is where humans meet the system. If Hypha is the engine room, Loom is the bridge. It needs to make the platform understandable, inspectable, and controllable without reducing everything to dumb boxes and arrows.

Product Summary

Loom is the human-facing workflow surface for Cambium.

Its V1 job is to let operators: - define workflows - inspect workflow runs - understand execution state - see failures, bottlenecks, and approvals - intervene when necessary - build trust in how Cambium behaves

Loom is not just a pretty builder. The real product value is operational clarity.

Problem

Most workflow interfaces are weak in one of two directions: - they are visually neat but operationally shallow - they are operationally detailed but miserable to use

For Cambium, that tradeoff is unacceptable.

If Loom only draws diagrams, operators will still need logs and engineering help to understand what happened. If Loom only shows tables and raw internals, the orchestration model will become hard to design and reason about.

Loom needs to bridge design-time and run-time.

Goals

Product goals

1. Let operators create and edit workflow definitions.
2. Let operators inspect workflow runs with enough depth to debug and trust the system.
3. Surface approvals, failures, and anomalies clearly.
4. Make intervention possible from the UI.
5. Provide a strong operational console for Cambium V1.

UX goals

1. Prioritize clarity over visual theater.
2. Make the current state of a run legible in seconds.
3. Preserve the graph model without making the interface chaotic.
4. Show causality, not just status.
5. Keep the workflow surface usable as the platform grows more complex.

Non-Goals

This PRD does not require V1 to ship: - advanced whiteboard-style infinite canvas behavior - collaborative multiplayer editing on day one - huge template marketplaces - fully no-code business-user abstraction layers - fancy visual effects with little operational value

If a choice has to be made, the bias should be toward operator usefulness, not demo candy.

Primary Users

1. Operator

Needs to: - configure workflows - monitor runs - intervene in failures or blocked states - understand why something happened

2. System designer

Needs to: - model workflows graphically - attach metadata and policies - inspect graph structure before runtime

3. Reviewer / approver

Needs to: - view pending actions that require threshold or manual approval - understand the context before deciding

Core User Stories

Workflow design

• As an operator, I can create a workflow visually.
• As an operator, I can add nodes and edges.
• As an operator, I can configure node types and metadata.
• As an operator, I can attach policy or approval rules to nodes.
• As an operator, I can save and version workflow definitions.

Run inspection

• As an operator, I can view all workflow runs.
• As an operator, I can open a specific run and see its current state.
• As an operator, I can see which nodes have completed, failed, are waiting, or are active.
• As an operator, I can inspect a timeline of events for a run.
• As an operator, I can inspect node-level inputs, outputs, errors, and retries.

Governance and intervention

• As an operator, I can see pending approval gates.
• As an operator, I can inspect why a run is blocked.
• As an operator, I can pause or resume a run when permitted.
• As an operator, I can see anomaly or risk signals attached to a run.

V1 Product Surfaces

1. Workflow List View

Requirements

• Show all workflow definitions available in the current workspace.
• Show version status.
• Show last updated timestamp.
• Allow creation of a new workflow.
• Allow opening a workflow for editing.

Minimum filters

• status
• updated date
• owner/creator if available

2. Workflow Editor

The V1 editor should allow visual modeling of workflow graphs.

Requirements

• Add node types.
• Connect nodes with edges.
• Configure node metadata.
• Configure edge conditions where applicable.
• Attach policies or approval requirements.
• Save draft changes.
• Publish or activate a workflow version.

Minimum supported node types

• task
• condition
• wait
• approval/gate
• success terminal
• failure terminal

Editor UX requirements

• Selected node shows editable properties.
• Edge logic is inspectable.
• Invalid graph states are surfaced clearly.
• Version changes are explicit.

Constraint

The editor must not force false simplicity. If the runtime supports branching and fallback logic, the UI needs to represent that .

3. Run List View

Requirements

• Show recent and active workflow runs.
• Show run status.
• Show workflow definition and version.
• Show started time and last update.
• Allow filtering by status.
• Allow opening a run detail page.

Minimum filters

• active/running
• failed
• blocked
• completed
• paused

4. Run Detail View

This is one of the most important screens in V1.

Requirements

• Show workflow name and version.
• Show overall run status.
• Show graph visualization with node states.
• Show active path or active nodes.
• Show event timeline.
• Show approvals or blockages.
• Show anomaly/risk indicators.
• Show checkpoint/recovery status if available.
• Show intervention controls where permitted.

Node state rendering

At minimum, distinguish: - not started - active - waiting - blocked - succeeded - failed - skipped

Run detail principle

An operator should be able to answer these questions quickly: - what is happening now? - what happened just before this? - what failed? - why is this blocked? - what can I do about it?

5. Event Timeline

Requirements

• Show structured events in chronological order.
• Allow event filtering by type.
• Show event timestamps.
• Show related node/task references.
• Show enough payload detail to understand what changed.

Core event types to support in UI

• run started
• node entered
• node completed
• node failed
• retry scheduled
• blocked/pending approval
• resumed
• paused
• anomaly detected
• intervention applied
• run completed

The timeline should not just be a dump. It should help reconstruct causality.

6. Approvals / Pending Actions View

Requirements

• Show actions waiting on approval.
• Show the run and node context.
• Show why approval is needed.
• Show severity or sensitivity if available.
• Allow authorized users to approve, reject, or escalate.

This may be a dedicated screen or a first-class panel in V1, but it has to be visible and usable.

7. Intervention Controls

Requirements

• Pause a run.
• Resume a paused run.
• Cancel a run where permitted.
• Surface recovery or replay entry points if available.
• Record interventions through the backend.

UX constraint

Intervention controls must be permission-aware and auditable. No mystery buttons that silently mutate runtime state.

8. Health / Risk Indicators

Requirements

• Surface run-level health state.
• Surface anomaly or risk indicators.
• Show blocked or degraded status clearly.
• Make it obvious when the platform has downshifted or paused due to policy or stress.

This matters because Cambium is not just running workflows. It is supposed to help keep them healthy.

Information Architecture

V1 Loom should likely have these top-level areas: - Workflows - Runs - Approvals - Health / Issues

Potential later additions: - Templates - Audit - Metrics - Integrations

UX Principles

1. Operational first

If a screen s cool but does not help a human act, it is secondary.

2. Explain path, not just point state

A workflow node being red is not enough. The operator needs context.

3. Debuggability is part of the product

The UI should reduce dependence on raw backend logs.

4. Respect complexity without glorifying it

Cambium will be complex. The interface should organize that complexity, not pretend it does not exist.

5. Fast answers

A good Loom screen should help a user answer: - What is happening? - Why? - What next?

Functional Requirements Summary

Workflow design

• Visual workflow editor
• Node configuration
• Edge configuration
• Policy attachment
• Versioning support

Runtime inspection

• Run list
• Run detail screen
• Graph state visualization
• Event timeline
• Node execution details

Governance

• Approval visibility
• Decision context
• Approval actions

Control

• Pause/resume/cancel controls
• Recovery entry points where implemented

Health

• Risk and anomaly indicators
• Health/degraded state indicators

Data / Backend Dependencies

Loom depends on backend support for: - workflow definitions and versions - workflow runs - node/task execution state - event history - approval/policy status - anomaly signals - intervention APIs - auth and permissions

If the backend does not expose structured state, Loom will degrade into a log viewer. That would be a design failure upstream, not just a UI problem.

Success Metrics

Product success

• Operators can design simple-to-moderately complex workflows visually.
• Operators can understand active and failed runs without engineering assistance.
• Approval and blocked states are clearly visible.
• Intervention actions are usable and trustworthy.

UX success

• Time to identify a failure point is low.
• Time to identify why a run is blocked is low.
• Operators rely less on raw logs.
• Users trust the surface enough to use it as the primary operations console.

Open Questions

1. Should the editor and runtime inspector be separate views or one unified workspace?
2. What is the minimum graph complexity Loom should support in V1 before the UI becomes cluttered?
3. How much node detail should be shown inline vs in side panels?
4. Should approvals live in a dedicated queue or inline in run views, or both?
5. What is the best visual metaphor for showing branching and fallback paths clearly?

Build Recommendation

Implementation should likely proceed in this order: 1. Workflow list and basic editor shell 2. Graph editing for core node types 3. Run list and run detail page 4. Event timeline and node detail panels 5. Approval views and intervention controls 6. Health and anomaly indicators

That sequence gets Loom useful quickly instead of waiting for some mythical perfect canvas.

Final Requirement Statement

Loom must provide a clear, operator-grade workflow surface for designing workflows, inspecting run behavior, understanding failures and approvals, and intervening safely in Cambium’s orchestration runtime.