docs: add conditional steps documentation and skipped step styling (#594)

# 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.

Author: jumski

.changeset/add-when-failed-option.md

@@ -0,0 +1,25 @@
+---
+'@pgflow/core': minor
+'@pgflow/dsl': minor
+---
+
+Add conditional step execution with skip infrastructure
+
+**New DSL Options:**
+
+- `if` - Run step only when input contains specified pattern
+- `ifNot` - Run step only when input does NOT contain pattern
+- `whenUnmet` - Control behavior when condition not met (fail/skip/skip-cascade)
+- `retriesExhausted` - Control behavior after all retries fail (fail/skip/skip-cascade)
+
+**New Types:**
+
+- `ContainmentPattern<T>` - Type-safe JSON containment patterns for conditions
+- `StepMeta` - Track skippable dependencies for proper type inference
+
+**Schema Changes:**
+
+- New columns: required_input_pattern, forbidden_input_pattern, when_unmet, when_failed, skip_reason, skipped_at
+- New step status: 'skipped'
+- New function: cascade_skip_steps() for skip propagation
+- FlowShape condition fields for auto-compilation drift detection

.changeset/conditional-step-execution.md

@@ -253,6 +253,10 @@ export default defineConfig({
                       label: 'Retrying steps',
                       link: '/build/retrying-steps/',
                     },
+                    {
+                      label: 'Graceful Failure',
+                      link: '/build/graceful-failure/',
+                    },
                     {
                       label: 'Validation steps',
                       link: '/build/validation-steps/',
@@ -271,6 +275,10 @@ export default defineConfig({
                     },
                   ],
                 },
+                {
+                  label: 'Conditional Steps',
+                  autogenerate: { directory: 'build/conditional-steps/' },
+                },
                 {
                   label: 'Starting Flows',
                   autogenerate: { directory: 'build/starting-flows/' },

.changeset/skip-infrastructure-schema.md

@@ -69,7 +69,7 @@ classes: {
     style.stroke: "#e85c5c"
   }
 
-  # Step state classes (created, started, completed, failed)
+  # Step state classes (created, started, completed, failed, skipped)
   step_created: {
     style.fill: "#95a0a3"
     style.stroke: "#4a5759"
@@ -86,6 +86,11 @@ classes: {
     style.fill: "#a33636"
     style.stroke: "#e85c5c"
   }
+  step_skipped: {
+    style.fill: "#4a5759"
+    style.stroke: "#6b7a7d"
+    style.stroke-dash: 3
+  }
 
   # Task state classes (queued, completed, failed)
   task_queued: {

pkgs/website/astro.config.mjs

@@ -0,0 +1,300 @@
+---
+title: Examples
+description: AI/LLM workflow patterns using conditional execution.
+sidebar:
+  order: 4
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+This page shows AI/LLM workflow patterns that benefit from conditional execution. Each example includes a diagram and condensed flow code.
+
+<Aside type="tip" title="Handler Syntax">
+  These examples use condensed syntax: root steps receive `flowInput`, dependent
+  steps receive `deps`, and `ctx.flowInput` provides flow input in dependent
+  steps.
+</Aside>
+
+## Query Routing
+
+Route to different handlers based on input. Simple questions go to a fast model, complex reasoning to a powerful model, and code questions to a code-specialized model.
+
+```d2 width="700" pad="20"
+...@../../../../assets/pgflow-theme.d2
+
+direction: right
+
+input: "Query" { class: neutral }
+classify: "Classify" { class: step_completed }
+simple: "Simple" { class: step_skipped }
+complex: "Complex" { class: step_skipped }
+code: "Code" { class: step_started }
+respond: "Respond" { class: step_created }
+
+input -> classify
+classify -> simple { style.stroke-dash: 3 }
+classify -> complex { style.stroke-dash: 3 }
+classify -> code: "intent=code"
+simple -> respond { style.stroke-dash: 3 }
+complex -> respond { style.stroke-dash: 3 }
+code -> respond
+```
+
+```typescript {7,15,23}
+new Flow<{ query: string }>({ slug: 'query_router' })
+  .step({ slug: 'classify' }, (flowInput) => classifyIntent(flowInput.query))
+  .step(
+    {
+      slug: 'simple',
+      dependsOn: ['classify'],
+      if: { classify: { intent: 'simple' } },
+    },
+    async (_, ctx) => callFastModel((await ctx.flowInput).query)
+  )
+  .step(
+    {
+      slug: 'complex',
+      dependsOn: ['classify'],
+      if: { classify: { intent: 'complex' } },
+    },
+    async (_, ctx) => callReasoningModel((await ctx.flowInput).query)
+  )
+  .step(
+    {
+      slug: 'code',
+      dependsOn: ['classify'],
+      if: { classify: { intent: 'code' } },
+    },
+    async (_, ctx) => callCodeModel((await ctx.flowInput).query)
+  )
+  .step(
+    {
+      slug: 'respond',
+      dependsOn: ['simple', 'complex', 'code'],
+    },
+    (deps) => format(deps.simple ?? deps.complex ?? deps.code)
+  );
+```
+
+**Key points:**
+
+- Intent classification determines which model handles the query
+- Only ONE model runs per query - others are skipped
+- `respond` uses `??` to coalesce the single defined output
+
+---
+
+## Conditional Fallback
+
+Enrich only when the primary source is insufficient. If retrieval returns low-confidence results, fall back to web search for current information.
+
+```d2 width="600" pad="20"
+...@../../../../assets/pgflow-theme.d2
+
+direction: right
+
+query: "Query" { class: neutral }
+retrieve: "Retrieve" { class: step_completed }
+web: "Web Search" { class: step_started }
+generate: "Generate" { class: step_created }
+
+query -> retrieve
+retrieve -> web: "low confidence"
+retrieve -> generate
+web -> generate
+```
+
+```typescript {7}
+new Flow<{ query: string }>({ slug: 'rag_fallback' })
+  .step({ slug: 'retrieve' }, (flowInput) => vectorSearch(flowInput.query)) // embedding happens inside
+  .step(
+    {
+      slug: 'web',
+      dependsOn: ['retrieve'],
+      if: { retrieve: { confidence: 'low' } },
+      retriesExhausted: 'skip', // Continue if web search fails
+    },
+    async (_, ctx) => searchWeb((await ctx.flowInput).query)
+  )
+  .step(
+    {
+      slug: 'generate',
+      dependsOn: ['retrieve', 'web'],
+    },
+    async (deps, ctx) => {
+      const docs = [...deps.retrieve.docs, ...(deps.web ?? [])];
+      return generateAnswer((await ctx.flowInput).query, docs);
+    }
+  );
+```
+
+<Aside type="note">
+  Web search only runs when retrieval confidence is low. This saves API costs
+  and latency for queries the knowledge base can answer well.
+</Aside>
+
+**Key points:**
+
+- Retrieval always runs first to check knowledge base
+- Web search is conditional on low confidence scores
+- `retriesExhausted: 'skip'` ensures graceful degradation if web search fails
+
+---
+
+## Graceful Failure Handling
+
+Continue execution when steps fail. Search multiple sources in parallel - if any source fails, continue with the others.
+
+```d2 width="700" pad="20"
+...@../../../../assets/pgflow-theme.d2
+
+direction: right
+
+query: "Query" { class: neutral }
+embed: "Embed" { class: step_completed }
+vector: "Vector" { class: step_completed }
+keyword: "Keyword" { class: step_completed }
+graph: "Graph" { class: step_skipped }
+rerank: "Rerank" { class: step_started }
+
+query -> embed
+embed -> vector
+embed -> keyword
+embed -> graph { style.stroke-dash: 3 }
+vector -> rerank
+keyword -> rerank
+graph -> rerank { style.stroke-dash: 3 }
+```
+
+```typescript {7,15,23}
+new Flow<{ query: string }>({ slug: 'multi_retrieval' })
+  .step({ slug: 'embed' }, (flowInput) => createEmbedding(flowInput.query))
+  .step(
+    {
+      slug: 'vector',
+      dependsOn: ['embed'],
+      retriesExhausted: 'skip',
+    },
+    (deps) => searchPinecone(deps.embed.vector)
+  )
+  .step(
+    {
+      slug: 'keyword',
+      dependsOn: ['embed'],
+      retriesExhausted: 'skip',
+    },
+    async (_, ctx) => searchElastic((await ctx.flowInput).query)
+  )
+  .step(
+    {
+      slug: 'graph',
+      dependsOn: ['embed'],
+      retriesExhausted: 'skip',
+    },
+    async (_, ctx) => searchNeo4j((await ctx.flowInput).query)
+  )
+  .step(
+    {
+      slug: 'rerank',
+      dependsOn: ['vector', 'keyword', 'graph'],
+    },
+    async (deps, ctx) => {
+      const all = [
+        ...(deps.vector ?? []),
+        ...(deps.keyword ?? []),
+        ...(deps.graph ?? []),
+      ];
+      return rerankResults((await ctx.flowInput).query, all);
+    }
+  );
+```
+
+**Key points:**
+
+- Three retrieval sources run **in parallel** after embedding
+- Each source has `retriesExhausted: 'skip'` for resilience
+- `rerank` combines available results - handles undefined sources gracefully
+
+---
+
+## Layered Conditions
+
+Combine `skip` and `skip-cascade` for nested conditionals. If tool use is needed, validate with guardrails before execution. Skip the entire tool branch if no tool is needed.
+
+```d2 width="650" pad="20"
+...@../../../../assets/pgflow-theme.d2
+
+direction: right
+
+input: "Message" { class: neutral }
+plan: "Plan" { class: step_completed }
+validate: "Guardrails" { class: step_completed }
+execute: "Execute" { class: step_started }
+respond: "Respond" { class: step_created }
+
+input -> plan
+plan -> validate: "needsTool"
+plan -> respond
+validate -> execute: "approved"
+validate -> respond { style.stroke-dash: 3 }
+execute -> respond
+```
+
+```typescript {7-8,16-17}
+new Flow<{ message: string }>({ slug: 'agent_guardrails' })
+  .step({ slug: 'plan' }, (flowInput) => planAction(flowInput.message))
+  .step(
+    {
+      slug: 'validate',
+      dependsOn: ['plan'],
+      if: { plan: { needsTool: true } },
+      whenUnmet: 'skip-cascade', // No tool needed = skip validation AND execution
+    },
+    (deps) => validateWithGuardrails(deps.plan.toolName, deps.plan.toolArgs)
+  )
+  .step(
+    {
+      slug: 'execute',
+      dependsOn: ['plan', 'validate'],
+      if: { validate: { approved: true } },
+      whenUnmet: 'skip', // Rejected = skip execution, still respond
+    },
+    (deps) => executeTool(deps.plan.toolName!, deps.plan.toolArgs!)
+  )
+  .step(
+    {
+      slug: 'respond',
+      dependsOn: ['plan', 'execute'],
+    },
+    async (deps, ctx) =>
+      generateResponse((await ctx.flowInput).message, deps.execute)
+  );
+```
+
+<Aside type="caution">
+  Note the different skip modes: `validate` uses `skip-cascade` (no tool needed
+  = skip everything downstream), while `execute` uses `skip` (rejected by
+  guardrails = skip execution but still respond).
+</Aside>
+
+**Key points:**
+
+- `skip-cascade` on validation skips the entire tool branch when no tool is needed
+- `skip` on execution allows responding even when guardrails reject
+- Layered conditions: tool needed → guardrails approved → execute
+
+---
+
+## Pattern Comparison
+
+| Pattern              | Use Case                    | Skip Mode      | Output Type              |
+| -------------------- | --------------------------- | -------------- | ------------------------ |
+| Query Routing        | Mutually exclusive branches | `skip`         | `T` or `undefined`       |
+| Conditional Fallback | Enrich only when needed     | `skip`         | `T` or `undefined`       |
+| Graceful Failure     | Continue when steps fail    | `skip`         | `T` or `undefined`       |
+| Layered Conditions   | Nested skip + skip-cascade  | `skip-cascade` | `T` (guaranteed if runs) |
+
+<Aside type="tip">
+  Use `skip` when downstream steps should handle missing data. Use
+  `skip-cascade` when an entire branch should be skipped together.
+</Aside>