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?
In this repository59 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- arch-lens-c4-containerSkill
- arch-lens-concurrencySkill
- arch-lens-data-lineageSkill
- arch-lens-deploymentSkill
- arch-lens-developmentSkill
- arch-lens-error-resilienceSkill
- arch-lens-module-dependencySkill
- arch-lens-operationalSkill
- arch-lens-process-flowSkill
- arch-lens-repository-accessSkill
- arch-lens-securitySkill
- arch-lens-state-lifecycleSkill
- audit-archSkill
- audit-bugsSkill
- audit-cohesionSkill
- audit-defense-standardsSkill
- audit-frictionSkill
- audit-implSkill
- audit-testsSkill
- design-guardsSkill
- dry-walkthroughSkill
- elaborate-phaseSkill
- exp-lens-benchmark-representativenessSkill
- exp-lens-causal-assumptionsSkill
- exp-lens-comparator-constructionSkill
- exp-lens-error-budgetSkill
- exp-lens-estimand-claritySkill
- exp-lens-exploratory-confirmatorySkill
- exp-lens-fair-comparisonSkill
- exp-lens-governance-riskSkill
- exp-lens-iterative-learningSkill
- exp-lens-measurement-validitySkill
- exp-lens-pipeline-integritySkill
- exp-lens-randomization-blockingSkill
- exp-lens-reproducibility-artifactsSkill
- exp-lens-sensitivity-robustnessSkill
- exp-lens-severity-testingSkill
- exp-lens-unit-interferenceSkill
- exp-lens-validity-threatsSkill
- exp-lens-variance-stabilitySkill
- id-slopSkill
- implement-worktreeSkill
- investigateSkill
- make-arch-diagSkill
- make-experiment-diagSkill
- make-groupsSkill
- make-planSkill
- make-reqSkill
- make-scenariosSkill
- mermaidSkill
- plan-arcSkill
- rectifySkill
- review-approachSkill
- update-architectureSkill
- update-reqsSkill
- update-specsSkill
- verify-diagSkill
- verify-proposed-diagSkill
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
- Very specific: line 38
BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY
- Distinctive: line 51
Look for: main commands, primary workflows, user stories
- Distinctive: line 56
Look for: success paths, normal flow, expected behavior
- Distinctive: line 61
Look for: error handling, retry, recovery, fallback
- Distinctive: line 66
Look for: resume, checkpoint, restore, continue
- Distinctive: line 71
Look for: API calls, subprocess, external, integration
- Very specific: line 128
Write the diagram to: temp/arch-lens-scenarios/arch_diag_scenarios_{YYYY-MM-DD_HHMMSS}.md
- Distinctive: line 243
Before creating the diagram, verify:
≈ “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.
Files
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-scenariosor/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
/mermaidskill 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:
- Primary Happy Path: The main use case
- Secondary Use Case: Another important flow
- Resume/Recovery: How to continue after interruption
- Error Handling: How failures are managed
- 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:
cliclass: Entry points (CLI, triggers)phaseclass: Initialization, setuphandlerclass: Processing componentsstateNodeclass: Data/state componentsoutputclass: Outputs, artifactsdetectorclass: 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:
| 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:
- {Step 1}
- {Step 2}
- {Step 3}
Scenario 2: {Name}
Purpose: {What this validates}
Flow:
- {Step 1}
- {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 detailsDoes 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
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.

