# Arch Lens Scenarios

> Create Scenarios architecture diagram showing end-to-end user journeys and component cooperation validation. Validation lens answering "Do the components work together?

- **Type:** Skill
- **Install:** `agentstack add skill-talont-org-autoskillit-arch-lens-scenarios`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TalonT-Org](https://agentstack.voostack.com/s/talont-org)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [TalonT-Org](https://github.com/TalonT-Org)
- **Source:** https://github.com/TalonT-Org/AutoSkillit/tree/main/src/autoskillit/skills_extended/arch-lens-scenarios

## Install

```sh
agentstack add skill-talont-org-autoskillit-arch-lens-scenarios
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Scenarios Architecture Lens

**Cognitive Mode:** Validation (+1 Validator)
**Primary Question:** "Do the components work together?"
**Focus:** End-to-End User Journeys, Component Cooperation, Scenario Validation

## When to Use

- Need to validate component cooperation
- Documenting key user scenarios
- Analyzing end-to-end flows through architecture
- User invokes `/autoskillit:arch-lens-scenarios` or `/autoskillit:make-arch-diag scenarios`

## Critical Constraints

**NEVER:**
- Modify any source code files
- Show internal component details
- Include all possible scenarios (pick key ones)
- Run subagents in the background (`run_in_background: true` is prohibited)

**ALWAYS:**
- Focus on END-TO-END journeys
- Show component touchpoints in sequence
- Select 3-5 representative scenarios
- Validate components work together
- 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-scenarios/...`
  save path to absolute by prepending the full CWD:
  ```
  diagram_path = /absolute/cwd/temp/arch-lens-scenarios/{filename}.md
  ```
  This token is MANDATORY — the pipeline cannot proceed without it.

## Arguments

`/autoskillit:arch-lens-scenarios [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:

**Primary Use Cases**
- Find the main user-facing operations
- Identify CLI commands or API endpoints
- Look for: main commands, primary workflows, user stories

**Happy Path Flows**
- Trace successful execution paths
- Identify component touchpoints
- Look for: success paths, normal flow, expected behavior

**Error/Recovery Flows**
- Trace error handling paths
- Identify recovery mechanisms
- Look for: error handling, retry, recovery, fallback

**Resume/Restart Flows**
- Find state persistence and resume
- Identify checkpoint mechanisms
- Look for: resume, checkpoint, restore, continue

**Integration Points**
- Find external system interactions
- Identify cross-component calls
- Look for: API calls, subprocess, external, integration

### Step 2: Select Key Scenarios

Choose 3-5 representative scenarios:
1. **Primary Happy Path**: The main use case
2. **Secondary Use Case**: Another important flow
3. **Resume/Recovery**: How to continue after interruption
4. **Error Handling**: How failures are managed
5. **Integration**: External system interaction

### Step 3: Map Component Touchpoints

For each scenario:
- Entry point (CLI, API, trigger)
- Processing components (in order)
- State changes
- Output/artifacts
- Exit point

**CRITICAL - Analyze Read/Write Direction:**
For EVERY component in each scenario:
- **What does it READ?** (inputs, state, config)
- **What does it WRITE?** (outputs, state changes, artifacts)
- **What does it PASS THROUGH?** (data transformed and forwarded)

For scenario flows, annotate each arrow:
- "reads from" / "loads" for input operations
- "writes to" / "saves" for output operations
- "transforms" for data that passes through

This reveals the actual data dependencies between scenario steps.

### Step 4: Create the Diagram

Use flowchart with:

**Direction:** `LR` (left-to-right) for sequential scenario flow

**Subgraphs per Scenario:**
- Each scenario gets its own subgraph
- Show components touched in sequence

**Node Styling:**
- `cli` class: Entry points (CLI, triggers)
- `phase` class: Initialization, setup
- `handler` class: Processing components
- `stateNode` class: Data/state components
- `output` class: Outputs, artifacts
- `detector` class: Recovery, continue paths

**Show Sequential Flow:**
- Each scenario flows left to right
- Components connected in order of execution

### Step 5: Write Output

Write the diagram to: `{{AUTOSKILLIT_TEMP}}/arch-lens-scenarios/arch_diag_scenarios_{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

```markdown
# Scenarios Diagram: {System Name}

**Lens:** Scenarios (Validation)
**Question:** Do the components work together?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}

## Scenario Overview

| Scenario | Purpose | Key Components |
|----------|---------|----------------|
| {name} | {validates what} | {components} |

## Scenarios Diagram

```mermaid
%%{init: {'flowchart': {'nodeSpacing': 40, 'rankSpacing': 50, 'curve': 'basis'}}}%%
flowchart LR
    %% 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;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;

    subgraph Scenario1 ["SCENARIO 1: Primary Flow"]
        direction TB
        S1_CLI["CLI Entry"]
        S1_INIT["Initialize"]
        S1_PROC["Process"]
        S1_OUT["Output"]
    end

    subgraph Scenario2 ["SCENARIO 2: Resume"]
        direction TB
        S2_DETECT["Detect State"]
        S2_LOAD["Load Checkpoint"]
        S2_CONT["Continue"]
    end

    subgraph Scenario3 ["SCENARIO 3: Error"]
        direction TB
        S3_DETECT["Detect Failure"]
        S3_HANDLE["Handle Error"]
        S3_RECOVER["Recovery Action"]
    end

    %% SCENARIO 1 FLOW %%
    S1_CLI --> S1_INIT
    S1_INIT --> S1_PROC
    S1_PROC --> S1_OUT

    %% SCENARIO 2 FLOW %%
    S2_DETECT --> S2_LOAD
    S2_LOAD --> S2_CONT

    %% SCENARIO 3 FLOW %%
    S3_DETECT --> S3_HANDLE
    S3_HANDLE --> S3_RECOVER

    %% CLASS ASSIGNMENTS %%
    class S1_CLI,S2_DETECT,S3_DETECT cli;
    class S1_INIT phase;
    class S1_PROC,S2_LOAD,S3_HANDLE handler;
    class S1_OUT stateNode;
    class S2_CONT,S3_RECOVER detector;
```

**Color Legend:**
| Color | Category | Description |
|-------|----------|-------------|
| Dark Blue | Entry | CLI/trigger entry points |
| Purple | Init | Initialization and detection |
| Orange | Process | Core processing components |
| Teal | State | Data and state components |
| Red | Continue | Resumption and recovery |

## Scenario Validation Summary

| Scenario | Validates | Key Components |
|----------|-----------|----------------|
| {name} | {what it validates} | {component list} |

## Detailed Scenarios

### Scenario 1: {Name}

**Purpose:** {What this validates}

**Flow:**
1. {Step 1}
2. {Step 2}
3. {Step 3}

### Scenario 2: {Name}

**Purpose:** {What this validates}

**Flow:**
1. {Step 1}
2. {Step 2}
```

---

## 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-process-flow` - For detailed workflow view
- `/autoskillit:arch-lens-error-resilience` - For failure handling details

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TalonT-Org](https://github.com/TalonT-Org)
- **Source:** [TalonT-Org/AutoSkillit](https://github.com/TalonT-Org/AutoSkillit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-talont-org-autoskillit-arch-lens-scenarios
- Seller: https://agentstack.voostack.com/s/talont-org
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.