agentleFS
TrecekTrecek/useful-claude-skills/.claude/skills/arch-lens-scenarios/SKILL.md

arch-lens-scenarios

Skill1 starsChanged 8 months agoMITView on GitHub

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

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 6 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY

    line 38
  2. Distinctive:

    Look for: main commands, primary workflows, user stories

    line 51
  3. Distinctive:

    Look for: success paths, normal flow, expected behavior

    line 56
  4. Distinctive:

    Look for: error handling, retry, recovery, fallback

    line 61
  5. Distinctive:

    Look for: resume, checkpoint, restore, continue

    line 66
  6. Distinctive:

    Look for: API calls, subprocess, external, integration

    line 71
  7. Very specific:

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

    line 128
  8. Distinctive:

    Before creating the diagram, verify:

    line 243

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 /arch-lens-scenarios or /make-arch-diag scenarios

Critical Constraints

NEVER:

  • Modify any source code files
  • Show internal component details
  • Include all possible scenarios (pick key ones)

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 /mermaid skill using the Skill tool - this is MANDATORY

Analysis Workflow

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: temp/arch-lens-scenarios/arch_diag_scenarios_{YYYY-MM-DD_HHMMSS}.md


Output Template

# 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:

ColorCategoryDescription
Dark BlueEntryCLI/trigger entry points
PurpleInitInitialization and detection
OrangeProcessCore processing components
TealStateData and state components
RedContinueResumption and recovery

Scenario Validation Summary

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.