talont-org/arch-lens-process-flow

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)
• Run subagents in the background (run_in_background: true is prohibited)

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
• If the Skill tool cannot be used (disable-model-invocation) or refuses this invocation, do NOT proceed with diagram creation. Abort this step and omit the diagram from output.
• After writing the diagram file, emit the absolute path as a structured output token as your final output. Resolve the relative temp/arch-lens-process-flow/... save path to absolute by prepending the full CWD:

  diagram_path = /absolute/cwd/temp/arch-lens-process-flow/{filename}.md
  

  This token is MANDATORY — the pipeline cannot proceed without it.

Arguments

/autoskillit:arch-lens-process-flow [context_path]

• context_path (optional) — Absolute path to a PR context file containing new files (★-prefixed) and modified files (●-prefixed) from the PR diff. When provided, read this file before beginning analysis and focus the diagram on the architectural areas affected by these specific files. When absent, explore the full CWD.

---

Analysis Workflow

Step 0: Read PR context (when provided)

If a context_path positional argument is present:

1. Read the file at context_path
2. Extract: new files list (★-prefixed), modified files list (●-prefixed)
3. Focus Step 1 exploration on the modules/components these files belong to
4. Apply ★ prefix on diagram nodes representing new files/components
5. Apply ● prefix on diagram nodes representing modified files/components

If no context_path is provided, skip this step and explore the full CWD in Step 1.

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: {{AUTOSKILLIT_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:

IMPORTANT: Emit the structured output tokens as literal plain text with no markdown formatting on the token names. Do not wrap token names in **bold**, *italic*, or any other markdown. The adjudicator performs a regex match on the exact token name — decorators cause match failure.

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