Operational Architecture Lens

Cognitive Mode: Operational Primary Question: "How is it run and monitored?" Focus: CLI Workflows, Configuration, Observability, Task Commands

When to Use

• Need to understand operator/admin perspective
• Documenting CLI commands and workflows
• Analyzing configuration and monitoring setup
• User invokes /arch-lens-operational or /make-arch-diag operational

Critical Constraints

NEVER:

• Modify any source code files
• Include internal implementation details
• Show code-level patterns

ALWAYS:

• Focus on OPERATOR experience
• Show CLI commands and their purposes
• Document configuration hierarchy
• Include monitoring and logging outputs
• BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY

Analysis Workflow

Step 1: Launch Parallel Exploration Subagents

Spawn Explore subagents to investigate:

CLI Entry Points

• Find all CLI commands
• Identify command groups and subcommands
• Look for: CLI frameworks (Click, argparse, Commander, etc.), entry points, main commands

Configuration

• Find configuration sources
• Identify environment variables
• Look for: config files (config.yaml, .env, settings.json, application.yml), environment variable usage, configuration libraries

Task Automation

• Find task runner definitions
• Identify automation scripts
• Look for: Taskfile.yml, Makefile, package.json scripts, Rakefile, scripts/ directory

Logging & Monitoring

• Find logging configuration
• Identify observability outputs
• Look for: logging configuration, log files, metrics, activity logs, temp/ output directories

Status & Health

• Find status/health commands
• Identify diagnostic outputs
• Look for: status, health, info, diagnose, check commands

Reset & Recovery

• Find reset/cleanup commands
• Identify recovery operations
• Look for: reset, clean, clear, purge, restore commands

Step 2: Map Operator Workflows

Document common operator workflows:

• Create: How to start new work
• Run: How to execute
• Monitor: How to check status
• Debug: How to diagnose issues
• Reset: How to recover from errors

CRITICAL - Analyze Read/Write Direction: For EVERY operational component:

• Configuration: READ from env/files (input to system)
• State tracking: Does the system READ and WRITE, or just WRITE?
• Logs/monitoring: Typically WRITE-only (system writes, humans read)
• Status commands: READ from state to display

Clearly categorize:

• State (read/write): System reads back to make decisions
• Artifacts (write-only): System writes for human inspection, never reads back
• Config (read-only): System reads but doesn't modify

Step 3: Document Configuration Hierarchy

Example pattern (adjust to actual system):

1. Environment Variables (highest priority)
2. Secret files (e.g., .secrets.toml, .env.local)
3. Project config (e.g., config.yaml, settings.json)
4. Defaults (lowest priority)

Step 4: Create the Diagram

Use flowchart with:

Direction: TB for hierarchical command structure

Subgraphs:

• CLI Entry Points (commands)
• Configuration (sources)
• Registry/State (tracking)
• Monitoring (observability)
• Task Commands (automation)

Node Styling:

• cli class: CLI commands
• phase class: Configuration sources
• stateNode class: State tracking (database, registry)
• output class: Monitoring outputs
• handler class: Task automation commands

Show Relationships:

• Commands to configuration
• Commands to state tracking
• State to monitoring outputs

Step 5: Write Output

Write the diagram to: temp/arch-lens-operational/arch_diag_operational_{YYYY-MM-DD_HHMMSS}.md

Output Template

# Operational Diagram: {System Name}

**Lens:** Operational (Administration)
**Question:** How is it run and monitored?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}

## CLI Commands Quick Reference

| Command | Purpose | Key Flags |
|---------|---------|-----------|
| {command} | {purpose} | {flags} |

## Operational Diagram

```mermaid
%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    classDef cli 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 output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;

    subgraph CLI ["CLI ENTRY POINTS"]
        direction TB
        CMD1["command-name<br/>━━━━━━━━━━<br/>--flag1 --flag2<br/>Purpose"]
    end

    subgraph Config ["CONFIGURATION"]
        direction TB
        ENV["Environment Variables<br/>━━━━━━━━━━<br/>API keys, modes"]
        SETTINGS["Config File<br/>━━━━━━━━━━<br/>Project config"]
    end

    subgraph Registry ["STATE TRACKING"]
        direction TB
        STATE["State Repository<br/>━━━━━━━━━━<br/>Active state<br/>Progress"]
    end

    subgraph Monitoring ["OBSERVABILITY"]
        direction TB
        LOGS["Activity Logs<br/>━━━━━━━━━━<br/>Step-by-step"]
        DEBUG["Debug Artifacts<br/>━━━━━━━━━━<br/>temp/ directory"]
    end

    subgraph Tasks ["TASK COMMANDS"]
        direction TB
        TASK1["task command<br/>━━━━━━━━━━<br/>Automation"]
    end

    %% FLOWS %%
    CMD1 --> ENV
    ENV --> SETTINGS
    CMD1 --> STATE
    CMD1 --> LOGS
    LOGS --> DEBUG

    %% CLASS ASSIGNMENTS %%
    class CMD1 cli;
    class ENV,SETTINGS phase;
    class STATE stateNode;
    class LOGS,DEBUG output;
    class TASK1 handler;

Color Legend:

Configuration Hierarchy

Operator Workflows

Create New Work

{command example}

Check Status

{command example}

Reset/Recovery

{command example}

---

## Pre-Diagram Checklist

Before creating the diagram, verify:

- [ ] LOADED `/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

- `/make-arch-diag` - Parent skill for lens selection
- `/mermaid` - MUST BE LOADED before creating diagram
- `/arch-lens-development` - For build tooling view
- `/arch-lens-deployment` - For infrastructure view