/agentic-workflow-guide

IR Architecture (Intermediate Representation)

Advanced pattern for transformation tasks with deterministic output

Back to overview.md

Overview

This advanced pattern is particularly effective for document generation, code transformation, and any task where deterministic output is critical.

Two-Stage Architecture

Input → IR (Intermediate Representation) → Output

graph LR
    A[Input] --> B[Generate IR]
    B --> C[Validate IR]
    C -->|Valid| D[Transform]
    C -->|Invalid| E[Reject/Fix]
    D --> F[Render Output]

Core Principles

Separation of Concerns

IR Specification Guidelines

1. Define allowed structure - JSON, YAML, or structured Markdown
2. Strict schema - All required fields must be present
3. No inference - Missing data = error, not auto-completion
4. Version control - IR schema should be versioned

Current State In Append-Only Documents

When one document contains both current state and history, do not search the entire body for status keywords.

1. Define explicit start and end boundaries for the current-state region.
2. Parse only that region with an exact header/schema.
3. Reject missing columns, wrong cell counts, and duplicate logical keys.
4. Exclude the history region by construction, not with a growing list of old statuses.

This prevents an old pending record from being revived as current work.

When to Use

• Document generation (specs → documentation)
• Code transformation (one language → another)
• Report generation (data → formatted report)
• Template-based output (variables → filled template)

When NOT to Use

• Creative tasks (writing, brainstorming)
• Exploratory analysis
• Tasks requiring adaptive responses

Implementation Example

Document Generation Workflow:

Step 1: Generate IR
  Input: User requirements
  Output: Structured document spec (JSON)

Step 2: Validate IR
  - All required sections present?
  - Data types correct?
  - References valid?
  → Reject if invalid

Step 3: Transform
  IR → Markdown/HTML/PDF
  (Deterministic, no creativity)

Step 4: Render
  Apply styling, formatting
  Output final document

Example IR Schema

{
  "document": {
    "title": "string (required)",
    "sections": [
      {
        "heading": "string (required)",
        "content": "string (required)",
        "subsections": ["array (optional)"]
      }
    ],
    "metadata": {
      "author": "string",
      "version": "string",
      "created": "ISO8601 date"
    }
  }
}

Benefits