arch-lens-process-flow

name	arch-lens-process-flow
categories	["arch-lens"]
description	Create Process/Execution Flow architecture diagram showing runtime behavior, state transitions, and decision points. Physiological lens answering "How does it behave?"
hooks	{"PreToolUse":[{"matcher":"*","hooks":[{"type":"command","command":"echo 'Process Flow Lens - Analyzing runtime behavior...'","once":true}]}]}

Process Flow Architecture Lens

Cognitive Mode: Physiological Primary Question: "How does it behave?" Focus: Runtime Behavior, State Transitions, Decision Points, Control Flow

When to Use

• Need to understand runtime execution paths
• Documenting state machines or workflows
• Analyzing decision points and branching logic
• User invokes /autoskillit:arch-lens-process-flow or /autoskillit:make-arch-diag process

Critical Constraints

NEVER:

• Modify any source code files
• Include static structure details (that's C4 lens)
• Show data storage details (that's data lineage lens)

ALWAYS:

• Focus on BEHAVIOR and STATE TRANSITIONS
• Show decision points as diamonds
• Include loop mechanisms and retry logic
• BEFORE creating any diagram, LOAD the /autoskillit:mermaid skill using the Skill tool - this is MANDATORY

---

Analysis Workflow

Step 1: Launch Parallel Exploration Subagents

Spawn Explore subagents to investigate:

State Machines & Workflows

• Find state definitions and transitions
• Identify workflow orchestration
• Look for: state machine patterns, workflow graphs, FSM implementations, state enum/constants

Entry Points & Triggers

• Find how processes are started
• Identify triggers and events
• Look for: main(), run(), execute(), start(), call, async handlers

Decision Points

• Find conditional logic that affects flow
• Identify routing functions
• Look for: if/else chains, switch/case, route_, should_, can_, is_

Loop Mechanisms

• Find iteration and retry patterns
• Identify continuation conditions
• Look for: while, for, retry logic, max_iterations, loop constructs

Terminal States

• Find completion conditions
• Identify error termination
• Look for: return, raise/throw, complete, error, success, failure states

Step 2: Map State Transitions

For each workflow/state machine discovered:

• States/Nodes: List all distinct states
• Transitions: Map state-to-state connections
• Guards: Conditions that determine transitions
• Actions: What happens during transitions

Step 3: Identify Flow Patterns

Document key patterns:

• Linear sequences (A -> B -> C)
• Branches (decision points)
• Loops (with termination conditions)
• Error paths
• Parallel paths (if any)

CRITICAL - Analyze Read/Write Direction: For EVERY node that interacts with state or storage:

• Reads from: What data does this node consume? From where?
• Writes to: What data does this node produce? To where?
• State mutations: Does it modify in-memory state, database, or files?

Label state interactions on edges:

• "reads" / "loads" / "queries" for input
• "writes" / "saves" / "updates" for output
• Distinguish primary storage (read/write) from write-only artifacts

Step 4: Create the Diagram

Use flowchart with:

Direction: TB for hierarchical flow, LR for sequential processes

Node Types:

• ([Label]) - Rounded: Start/End terminals
• {Label} - Diamond: Decision points
• [Label] - Rectangle: Process nodes
• [[Label]] - Subroutine: Subgraph calls

Subgraphs for Phases:

• Group related states into phases
• Keep START/END outside subgraphs

Node Styling:

• terminal class: START, END, ERROR nodes
• phase class: Control flow, analysis nodes
• handler class: Processing, execution nodes
• stateNode class: Decision, routing nodes
• detector class: Validation gates, failure handling

Edge Labels:

• Show conditions on decision branches
• Include loop counts where relevant

Step 5: Write Output

Write the diagram to: temp/arch-lens-process-flow/arch_diag_process_flow_{YYYY-MM-DD_HHMMSS}.md (relative to the current working directory)

After writing the diagram file, emit a structured output line:

diagram_path = {absolute_path_to_diagram_file}

---

Output Template

# Process Flow Diagram: {Workflow Name}

**Lens:** Process Flow (Physiological)
**Question:** How does it behave?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}

## Workflow Overview

| Phase | Nodes | Key Decision Points | Loop Mechanism |
|-------|-------|---------------------|----------------|
| {phase} | {count} | {decisions} | {loop info} |

## Flow Diagram

```mermaid
%%{init: {'flowchart': {'nodeSpacing': 40, 'rankSpacing': 50, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;

    %% TERMINALS %%
    START([START])
    COMPLETE([COMPLETE])
    ERROR([ERROR])

    subgraph Phase1 ["Phase Name"]
        direction TB
        N1["Node Name<br/>━━━━━━━━━━<br/>Description"]
        N2{"Decision<br/>━━━━━━━━━━<br/>Condition?"}
        N3["Process Node<br/>━━━━━━━━━━<br/>Action"]
    end

    %% FLOW %%
    START --> N1
    N1 --> N2
    N2 -->|"condition A"| N3
    N2 -->|"condition B"| ERROR
    N3 --> COMPLETE

    %% CLASS ASSIGNMENTS %%
    class START,COMPLETE,ERROR terminal;
    class N1,N3 handler;
    class N2 stateNode;

Color Legend:

Color	Category	Description
Dark Blue	Terminal	Start, complete, and error states
Purple	Phase	Control flow and analysis nodes
Orange	Handler	Processing and execution nodes
Teal	State	Selection and routing decisions
Red	Detector	Validation gates and failure handling

State Machine Characteristics

Aspect	Value	Notes
Total Nodes	{count}
Decision Points	{count}
Loop Mechanism	{description}	{max iterations}
Error Paths	{count}

Critical Routing Logic

• Condition A: {what triggers this path}
• Condition B: {what triggers this path}

---

## Pre-Diagram Checklist

Before creating the diagram, verify:

- [ ] LOADED `/autoskillit:mermaid` skill using the Skill tool
- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)
- [ ] Diagram will include a color legend table

---

## Related Skills

- `/autoskillit:make-arch-diag` - Parent skill for lens selection
- `/autoskillit:mermaid` - MUST BE LOADED before creating diagram
- `/autoskillit:arch-lens-concurrency` - For parallel execution details
- `/autoskillit:arch-lens-error-resilience` - For failure handling specifics