Chain Architect - SO1 Documentation

Quick Reference

Property	Value
Domain	Prompts
FORGE Stage	2 (Implementation)
Version	1.0.0
Primary Output	Multi-step prompt chain specifications

Use this agent when you need to:

Break complex tasks into sequential or parallel prompt steps
Design workflows that require multi-stage reasoning
Map data flow between dependent prompt operations
Create error handling and fallback strategies for prompt chains

Core Capabilities

Chain Design

Creates multi-step prompt sequences for complex task orchestration

Task Decomposition

Breaks complex reasoning into chainable subtasks with clear boundaries

Data Flow Mapping

Defines how outputs from one step feed into subsequent steps

Error Branching

Designs fallback paths and error recovery strategies

When to Use

Ideal Use Cases

Complex tasks requiring multi-step reasoning (e.g., analyze → synthesize → recommend)

Workflows where early steps inform later decisions (conditional branching)

Parallel analysis scenarios (e.g., multi-perspective evaluation)

Tasks needing error recovery and fallback strategies

Orchestrating multiple Veritas prompts into cohesive workflows

Not Recommended For

Usage Examples

Code Review Chain
Parallel Analysis
Incident Response

Multi-Step Code Review & Improvement

Task: Review code → Prioritize issues → Generate improvements → Explain changesChain Design

{
  "id": "vrt-chain-f8e7d6c5",
  "name": "Code Review and Improvement",
  "description": "Reviews code, identifies issues, generates improved version",
  "input": {
    "schema": {
      "code": "string",
      "language": "string",
      "context": "string (optional)"
    }
  },
  "steps": [
    {
      "id": "step_1",
      "name": "Analyze Code Quality",
      "prompt_id": "vrt-a1b2c3d4",
      "input_mapping": {
        "code": "{{input.code}}",
        "language": "{{input.language}}",
        "focus_areas": ["security", "performance", "maintainability"]
      },
      "output_key": "review_result",
      "on_error": "fail"
    },
    {
      "id": "step_2",
      "name": "Prioritize Issues",
      "prompt_id": "vrt-prioritize01",
      "input_mapping": {
        "issues": "{{review_result.issues}}",
        "severity_weights": {
          "security": 1.0,
          "performance": 0.8,
          "style": 0.3
        }
      },
      "output_key": "prioritized_issues",
      "condition": "{{review_result.issues.length > 0}}",
      "on_error": "skip"
    },
    {
      "id": "step_3",
      "name": "Generate Improved Code",
      "prompt_id": "vrt-improve01",
      "input_mapping": {
        "original_code": "{{input.code}}",
        "issues": "{{prioritized_issues}}"
      },
      "output_key": "improved_code",
      "on_error": "fallback",
      "fallback": {
        "action": "return_original",
        "value": "{{input.code}}"
      }
    },
    {
      "id": "step_4",
      "name": "Explain Changes",
      "prompt_id": "vrt-explain01",
      "input_mapping": {
        "original": "{{input.code}}",
        "improved": "{{improved_code}}",
        "issues_addressed": "{{prioritized_issues}}"
      },
      "output_key": "explanation",
      "condition": "{{improved_code != input.code}}"
    }
  ],
  "execution": {
    "mode": "sequential",
    "max_retries": 2,
    "timeout_seconds": 120
  }
}

Key Design Decisions:

Sequential execution: Each step depends on previous results
Conditional step 2: Only prioritize if issues found
Fallback on step 3: Return original code if improvement fails
Skip step 4: If no changes made, skip explanation

Multi-Perspective Analysis Chain

Task: Analyze proposal from technical, business, and security perspectives in parallel, then synthesizeChain Design

{
  "id": "vrt-chain-b2c3d4e5",
  "name": "Multi-Perspective Analysis",
  "description": "Analyzes content from multiple perspectives, then synthesizes findings",
  "input": {
    "schema": {
      "content": "string",
      "perspectives": "array (optional)"
    }
  },
  "steps": [
    {
      "id": "parallel_group_1",
      "name": "Multi-Perspective Analysis",
      "type": "parallel",
      "steps": [
        {
          "id": "technical_analysis",
          "name": "Technical Analysis",
          "prompt_id": "vrt-tech-analysis",
          "input_mapping": {
            "content": "{{input.content}}",
            "perspective": "technical"
          },
          "output_key": "technical_result"
        },
        {
          "id": "business_analysis",
          "name": "Business Analysis",
          "prompt_id": "vrt-biz-analysis",
          "input_mapping": {
            "content": "{{input.content}}",
            "perspective": "business"
          },
          "output_key": "business_result"
        },
        {
          "id": "security_analysis",
          "name": "Security Analysis",
          "prompt_id": "vrt-sec-analysis",
          "input_mapping": {
            "content": "{{input.content}}",
            "perspective": "security"
          },
          "output_key": "security_result"
        }
      ],
      "on_error": "continue"
    },
    {
      "id": "step_2",
      "name": "Synthesize Analyses",
      "prompt_id": "vrt-synthesize",
      "input_mapping": {
        "analyses": [
          "{{technical_result}}",
          "{{business_result}}",
          "{{security_result}}"
        ]
      },
      "output_key": "synthesis",
      "on_error": "fail"
    }
  ],
  "execution": {
    "mode": "mixed",
    "max_retries": 1,
    "timeout_seconds": 180
  }
}

Key Design Decisions:

Parallel execution: All analyses run simultaneously
Continue on error: Synthesis proceeds with partial results
Mixed mode: Parallel group followed by sequential synthesis

Incident Triage & Resolution Chain

Task: Detect severity → Notify stakeholders → Recommend actions → Track resolutionChain Design

{
  "id": "vrt-chain-incident",
  "name": "Incident Response Chain",
  "description": "Complete incident workflow from triage to resolution tracking",
  "input": {
    "schema": {
      "alert_data": "object",
      "service_name": "string",
      "metrics": "object"
    }
  },
  "steps": [
    {
      "id": "step_1",
      "name": "Assess Severity",
      "prompt_id": "vrt-inc001",
      "input_mapping": {
        "service_name": "{{input.service_name}}",
        "alert_message": "{{input.alert_data.message}}",
        "metrics_json": "{{input.metrics}}"
      },
      "output_key": "severity_assessment",
      "on_error": "fail"
    },
    {
      "id": "step_2",
      "name": "Generate Notification",
      "prompt_id": "vrt-notify01",
      "input_mapping": {
        "severity": "{{severity_assessment.severity}}",
        "service": "{{input.service_name}}",
        "summary": "{{severity_assessment.justification}}"
      },
      "output_key": "notification",
      "condition": "{{severity_assessment.severity in ['SEV0', 'SEV1', 'SEV2']}}",
      "on_error": "skip"
    },
    {
      "id": "step_3",
      "name": "Recommend Actions",
      "prompt_id": "vrt-actions01",
      "input_mapping": {
        "incident": "{{severity_assessment}}",
        "historical_data": "{{lookup_similar_incidents()}}"
      },
      "output_key": "recommended_actions",
      "on_error": "fail"
    },
    {
      "id": "step_4",
      "name": "Create Tracking Ticket",
      "prompt_id": "vrt-ticket01",
      "input_mapping": {
        "severity": "{{severity_assessment.severity}}",
        "actions": "{{recommended_actions}}",
        "assignee": "{{routing_logic(severity_assessment.severity)}}"
      },
      "output_key": "ticket",
      "on_error": "fail"
    }
  ],
  "execution": {
    "mode": "sequential",
    "max_retries": 3,
    "timeout_seconds": 90
  }
}

Key Design Decisions:

Conditional notification: Only send for SEV0-SEV2
Dynamic data: Lookup historical incidents in step 3
High retry count: Critical workflow requires reliability

Output Format

Veritas Chain Schema

interface VeritasChain {
  type: "veritas-chain";
  version: "1.0.0";
  generated_by: "chain-architect";
  timestamp: string; // ISO8601
  
  content: {
    id: string; // vrt-chain-{sha256[:8]}
    name: string;
    category: "chain";
    version: string;
    status: "draft" | "reviewed" | "production";
    description: string;
    
    input: {
      schema: object; // JSON Schema
      required: string[];
      example: object;
    };
    
    output: {
      schema: object;
      example: object;
    };
    
    steps: Array<{
      id: string;
      name: string;
      prompt_id?: string; // Reference to Veritas prompt
      type?: "parallel"; // For grouping parallel steps
      steps?: Array<Step>; // Nested for parallel groups
      input_mapping: Record<string, any>; // Template interpolation
      output_key: string; // Key to store result
      condition?: string; // Conditional execution
      on_error: "fail" | "skip" | "fallback" | "continue";
      fallback?: {
        action: string;
        value: any;
      };
    }>;
    
    execution: {
      mode: "sequential" | "parallel" | "mixed" | "conditional";
      max_retries: number;
      timeout_seconds: number;
    };
    
    metadata: {
      author: string;
      created: string;
      tags: string[];
      complexity: "simple" | "moderate" | "complex";
    };
  };
}

Chain Design Patterns

Sequential Chains

Use when: Each step depends on previous outputs

Step 1 → Step 2 → Step 3 → Step 4
  ↓        ↓        ↓        ↓
Output   Output   Output   Final

Example: Analyze → Prioritize → Improve → Explain

Parallel Chains

Use when: Steps are independent and can run concurrently

Input → [Step 1, Step 2, Step 3] → Synthesize → Output

Example: Multi-perspective analysis (technical, business, security)

Conditional Chains

Use when: Branching logic based on intermediate results

Step 1 → Decision Point → [Path A | Path B] → Merge → Output

Example: Severity-based routing (SEV0 → Immediate escalation, SEV3 → Queue)

Error Handling Strategies

Strategy	Behavior	Use Case
fail	Halt chain execution	Critical steps that must succeed
skip	Continue to next step	Optional enhancements
fallback	Use default value	Safe defaults available
continue	Proceed with partial results	Parallel steps where some failures acceptable

FORGE Gate Compliance

Entry Gates (Pre-conditions)

Before invoking this agent, ensure:

Complex task defined: Clear description of multi-step reasoning required
Available prompts identified: Veritas prompts to compose into chain
Chain outcome specified: Expected final output format
Input format documented: Schema for chain inputs

Verification: Factory Orchestrator validates task complexity justifies chaining

Exit Gates (Post-conditions)

This agent completes successfully when:

Chain structure documented: Full step sequence with input/output mappings
Prompts linked: All steps reference Veritas prompts or define new ones
Data flow validated: Output → input mappings confirmed for all steps
Error handling defined: Each step has on_error strategy
Execution order established: Sequential/parallel/conditional mode set
Decision record logged: ADR with design rationale

Verification: Gatekeeper validates chain structure and completeness

Decision Record Format

All significant chain design decisions are logged as:

date:2024-01-15T11:00:00Z|context:Designing code review chain for PR automation|decision:Use sequential with conditional step 2 (prioritization)|rationale:Not all code has issues; skip prioritization when review is clean|consequences:Reduces latency by ~30% for clean code reviews|status:accepted

Integration Points

Control Plane API

This agent does not directly interact with the Control Plane API - it designs chain structures that may later be executed via the API.

Veritas Prompt Library

Consumes:

vrt-chain001: Chain design patterns and best practices
vrt-flow001: Data flow validation templates
vrt-reason01: Reasoning decomposition strategies

Produces:

Chain specifications in veritas/agent-prompts/prompts/
Category: chain
Status: draft (requires testing before production)

n8n Workflow Integration

Chain designs may inform n8n workflow structure, particularly for:

Sequential API calls with state management
Parallel webhook processing
Conditional routing based on AI analysis

Agent	Relationship	Integration Point
Prompt Refiner	Upstream	Provides refined prompts for chain composition
Fragment Curator	Peer	Supplies reusable fragments for chain steps
Factory Orchestrator	Upstream	Routes complex tasks requiring chain design
Workflow Architect	Downstream	May implement chains as n8n workflows

Error Handling

Common Issues

Data Flow Validation FailedCause: Output of step N doesn’t match required input of step N+1Resolution: Add data transformation step or adjust input mapping template

Circular DependenciesCause: Step A depends on Step B’s output, but Step B depends on Step AResolution: Decompose into separate chains or refactor dependency structure

Excessive ComplexityCause: Chain has >10 steps or deeply nested parallel groupsResolution: Split into multiple chains with intermediate persistence

Escalation Path

If the agent cannot complete chain design:

Log decision record with status:blocked
Output partial chain with unresolved dependencies flagged
Return control to Factory Orchestrator with design blockers

Success Metrics

Metric	Target	Measurement
Data Flow Completeness	100%	All step inputs mapped from prior outputs
Error Handler Coverage	100%	Every step has on_error strategy
Prompt Reuse	>70%	Percentage of steps using existing Veritas prompts
Complexity Appropriate	<10 steps	Average chain length for maintainability

Chain Complexity Guidelines

Complexity	Steps	Parallel Groups	Conditionals	Use Case
Simple	2-3	0-1	0-1	Basic sequential workflows
Moderate	4-7	1-2	1-3	Multi-stage analysis with branching
Complex	8-10	2-4	3-5	Enterprise orchestration workflows

Chains exceeding 10 steps should be split into multiple chains with intermediate persistence for maintainability.

Source Files

View Agent Source

Maintained in so1-agents repository under agents/prompts/chain-architect.md

Agents Overview

Orchestration

Automation

Engineering

DevOps

Documentation

Prompts

Incident

​Quick Reference

​Core Capabilities

Chain Design

Task Decomposition

Data Flow Mapping

Error Branching

​When to Use

​Ideal Use Cases

​Not Recommended For

​Usage Examples

​Multi-Step Code Review & Improvement

​Multi-Perspective Analysis Chain

​Incident Triage & Resolution Chain

​Output Format

​Veritas Chain Schema

​Chain Design Patterns

​Sequential Chains

​Parallel Chains

​Conditional Chains

​Error Handling Strategies

​FORGE Gate Compliance

​Integration Points

​Control Plane API

​Veritas Prompt Library

​n8n Workflow Integration

​Related Agents

​Error Handling

​Common Issues

​Escalation Path

​Success Metrics

​Chain Complexity Guidelines

​Source Files

View Agent Source

Quick Reference

Core Capabilities

When to Use

Ideal Use Cases

Not Recommended For

Usage Examples

Multi-Step Code Review & Improvement

Multi-Perspective Analysis Chain

Incident Triage & Resolution Chain

Output Format

Veritas Chain Schema

Chain Design Patterns

Sequential Chains

Parallel Chains

Conditional Chains

Error Handling Strategies

FORGE Gate Compliance

Integration Points

Control Plane API

Veritas Prompt Library

n8n Workflow Integration

Related Agents

Error Handling

Common Issues

Escalation Path

Success Metrics

Chain Complexity Guidelines

Source Files