docs: add conditional steps documentation and skipped step styling

[jumski]

Add Conditional Steps and Error Handling

This PR introduces comprehensive support for conditional step execution and graceful error handling in pgflow. The new features allow workflows to adapt to runtime conditions and handle failures without stopping the entire run.

Key Features

• Pattern Matching: Control step execution with if/ifNot conditions using PostgreSQL's JSON containment operator
• Skip Modes: Configure what happens when conditions aren't met with fail, skip, or skip-cascade options
• Error Handling: Gracefully handle step failures with retriesExhausted: 'skip' for non-critical steps
• Type Safety: TypeScript types reflect optional dependencies when steps might be skipped

Visual Representation

Added a new step_skipped style to the D2 theme for visualizing skipped steps in flow diagrams.

Documentation

Added comprehensive documentation with:

• Overview of conditional execution and error handling
• Pattern matching syntax and examples
• Skip mode behaviors and use cases
• Error handling best practices
• Type safety considerations
• Visual diagrams showing different execution paths

These features enable more resilient workflows where non-critical steps can fail without stopping the entire process.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8cfa234

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[jumski]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• docs: add conditional steps documentation and skipped step styling #594 👈 (View in Graphite)
• fix: improve type safety for skip-cascade mode in flow steps #593
• refactor: rename condition_pattern to required_input_pattern and condition_not_pattern to forbidden_input_pattern #587
• feat: add whenUnmet and whenFailed condition modes to flow shapes #585
• feat: add ifNot condition pattern for negative condition checks #584
• feat: improve type safety for flow step outputs and skippable dependencies #583
• feat: add type safety for skippable step dependencies #582
• feat: add ContainmentPattern type for JSON condition matching #576
• feat: add whenFailed option for error handling after retries exhausted #575
• feat: add conditional step execution with skip/fail behavior #573
• feat: add conditional step execution with skip infrastructure #572
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 8cfa234

Command	Status	Duration	Result
nx run edge-worker:test:integration	✅ Succeeded	3m 53s	View ↗
nx affected -t verify-exports --base=origin/mai...	✅ Succeeded	3s	View ↗
nx affected -t build --configuration=production...	✅ Succeeded	3s	View ↗
nx affected -t lint typecheck test --parallel -...	✅ Succeeded	2m 23s	View ↗
nx run cli:e2e	✅ Succeeded	3s	View ↗
nx run edge-worker:e2e	✅ Succeeded	48s	View ↗
nx run client:e2e	✅ Succeeded	1m 9s	View ↗
nx run core:pgtap	✅ Succeeded	1s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-01-15 05:27:07 UTC

[github-actions]

🔍 Preview Deployment: Website

✅ Deployment successful!

🔗 Preview URL: https://pr-594.pgflow.pages.dev

📝 Details:

• Branch: 01-14-add_docs_for_conditional_steps
• Commit: 5edfbbda841ad178bc0847745e6e9be42c132d8d
• View Logs

_Last updated: _