Concurrency Architecture Lens
Cognitive Mode: Physiological
Primary Question: "How does parallelism work?"
Focus: Parallel Execution, Thread Pools, Synchronization, Barriers
When to Use
- Need to understand concurrent execution patterns
- Documenting thread pools and worker management
- Analyzing synchronization and thread safety
- User invokes
/autoskillit:arch-lens-concurrency or /autoskillit:make-arch-diag concurrency
Critical Constraints
NEVER:
- Modify any source code files
- Conflate with general process flow (that's a different lens)
- Ignore thread safety implications
- Run subagents in the background (
run_in_background: true is prohibited)
ALWAYS:
Arguments
/autoskillit:arch-lens-concurrency [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:
- Read the file at
context_path
- Extract: new files list (★-prefixed), modified files list (●-prefixed)
- Focus Step 1 exploration on the modules/components these files belong to
- Apply ★ prefix on diagram nodes representing new files/components
- 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:
Concurrency Model
- Find the primary concurrency approach
- Is it threading, asyncio, multiprocessing, coroutines?
- Look for: ThreadPoolExecutor, asyncio, ProcessPoolExecutor, async/await, goroutines, threads
Worker Pools
- Find thread/process pool configurations
- Identify max_workers settings
- Look for: Executor, Pool, workers, max_*, thread pool, worker pool
Parallel Operations
- Find what work is parallelized
- Identify parallel patterns (map, submit, gather)
- Look for: executor.submit, asyncio.gather, pool.map, parallel processing
Synchronization Points
- Find barriers and coordination
- Identify how parallel work is collected
- Look for: as_completed, wait, gather, Lock, Semaphore, barriers, sync points
State Access
- Find shared state access
- Identify thread safety mechanisms
- Look for: Lock, RLock, Queue, thread-local, immutable, atomic, mutex
Sequential Boundaries
- Find what MUST run sequentially
- Identify the main thread/process responsibilities
- Look for: main(), single-threaded, atomic updates
Step 2: Map Concurrency Boundaries
Document:
- Main Thread: What runs sequentially
- Worker Pool: What runs in parallel
- Barriers: Where parallel work converges
- Atomic Operations: What requires exclusive access
CRITICAL - Analyze Read/Write Direction:
For EVERY concurrent component and shared resource:
- Reads from shared state: What data do workers READ?
- Writes to shared state: What data do workers WRITE?
- Return values: Do workers return data (read by main thread)?
- Side effects: Do workers write to storage directly?
Identify:
- Read-only access (safe for parallelism)
- Write access (needs synchronization)
- Worker isolation (no shared state during execution)
Step 3: Identify Thread Safety
For each shared resource:
- How is it protected?
- Who can read/write?
- Are there race conditions?
Step 4: Create the Diagram
Use flowchart with:
Direction: TB for spawn-barrier-collect pattern
Subgraphs:
- Main Thread (sequential operations)
- Thread/Process Pool (parallel workers)
- Subprocess/External (if spawned processes)
- Isolation (thread safety guarantees)
Node Styling:
terminal class: Start/end points
phase class: Sequential nodes
newComponent class: Parallel workers (green)
detector class: Spawn and barrier points
handler class: Processing within workers
output class: Atomic state updates
stateNode class: Thread safety mechanisms
Special Elements:
- Show fork/join points clearly
- Use edge labels for conditions
- Group parallel workers visually
Step 5: Write Output
Write the diagram to: {{AUTOSKILLIT_TEMP}}/arch-lens-concurrency/arch_diag_concurrency_{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
# Concurrency Diagram: {System Name}
**Lens:** Concurrency (Physiological)
**Question:** How does parallelism work?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}
## Concurrency Model
| Aspect | Value | Notes |
|--------|-------|-------|
| Primary Model | {threading/asyncio/multiprocessing} | |
| Worker Pool Type | {ThreadPoolExecutor/etc} | |
| Max Workers | {count} | |
| Parallel Operations | {what is parallelized} | |
## Concurrency 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;
classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
subgraph MainThread ["MAIN THREAD (Sequential)"]
direction TB
START([START])
INIT["Initialize<br/>━━━━━━━━━━<br/>Setup state"]
DECISION{"Multiple<br/>items?"}
SEQ["Sequential Path<br/>━━━━━━━━━━<br/>Single thread"]
SPAWN["Spawn Workers<br/>━━━━━━━━━━<br/>Fork point"]
BARRIER["Barrier<br/>━━━━━━━━━━<br/>Wait for all"]
ATOMIC["Atomic Update<br/>━━━━━━━━━━<br/>Main thread only"]
COMPLETE([COMPLETE])
end
subgraph ThreadPool ["THREAD POOL (Parallel)"]
direction TB
W1["Worker 1<br/>━━━━━━━━━━<br/>Task execution"]
W2["Worker 2<br/>━━━━━━━━━━<br/>Task execution"]
WN["Worker N<br/>━━━━━━━━━━<br/>Task execution"]
end
subgraph Isolation ["THREAD SAFETY"]
direction TB
ISO1["Isolated state"]
ISO2["No shared writes"]
ISO3["Return data only"]
end
%% MAIN FLOW %%
START --> INIT
INIT --> DECISION
DECISION -->|"1 item"| SEQ
DECISION -->|"N items"| SPAWN
SEQ --> COMPLETE
%% PARALLEL FLOW %%
SPAWN --> W1
SPAWN --> W2
SPAWN --> WN
W1 --> BARRIER
W2 --> BARRIER
WN --> BARRIER
BARRIER --> ATOMIC
ATOMIC --> COMPLETE
%% ISOLATION %%
W1 -.-> ISO1
W2 -.-> ISO2
WN -.-> ISO3
%% CLASS ASSIGNMENTS %%
class START,COMPLETE terminal;
class INIT,SEQ phase;
class DECISION stateNode;
class SPAWN,BARRIER detector;
class W1,W2,WN newComponent;
class ATOMIC output;
class ISO1,ISO2,ISO3 stateNode;
Color Legend:
| Color |
Category |
Description |
| Dark Blue |
Terminal |
Start and end points |
| Purple |
Sequential |
Single-threaded nodes |
| Green |
Workers |
Parallel workers |
| Red |
Synchronization |
Spawn and barrier points |
| Dark Teal |
Atomic |
Main-thread-only state updates |
| Teal |
Isolation |
Thread safety guarantees |
Concurrency Boundaries
| Component |
Model |
Synchronization |
| {component} |
{single-threaded/parallel} |
{mechanism} |
Thread Safety Guarantees
- Isolation: {how workers are isolated}
- State Access: {who can modify shared state}
- Barrier: {how results are collected}
---
## 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 general workflow view
- `/autoskillit:arch-lens-error-resilience` - For parallel failure handling
1---2name: arch-lens-concurrency3categories: [arch-lens]4activate_deps: [mermaid]5description: Create Concurrency architecture diagram showing parallel execution patterns, thread pools, synchronization, and barriers. Physiological lens answering "How does parallelism work?"6hooks:7 PreToolUse:8 - matcher: "*"9 hooks:10 - type: command11 command: "echo 'Concurrency Lens - Analyzing parallel execution...'"12 once: true13metadata:14 source: https://skillmd.com/skills/talont-org/arch-lens-concurrency15---1617# Concurrency Architecture Lens1819**Cognitive Mode:** Physiological20**Primary Question:** "How does parallelism work?"21**Focus:** Parallel Execution, Thread Pools, Synchronization, Barriers2223## When to Use2425- Need to understand concurrent execution patterns26- Documenting thread pools and worker management27- Analyzing synchronization and thread safety28- User invokes `/autoskillit:arch-lens-concurrency` or `/autoskillit:make-arch-diag concurrency`2930## Critical Constraints3132**NEVER:**33- Modify any source code files34- Conflate with general process flow (that's a different lens)35- Ignore thread safety implications36- Run subagents in the background (`run_in_background: true` is prohibited)3738**ALWAYS:**39- Focus on PARALLEL execution specifically40- Show synchronization barriers and coordination41- Identify thread safety guarantees42- Document the concurrency MODEL used43- BEFORE creating any diagram, LOAD the `/autoskillit:mermaid` skill using the Skill tool - this is MANDATORY44- 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.45- After writing the diagram file, emit the **absolute path** as a structured output46 token as your final output. Resolve the relative `temp/arch-lens-concurrency/...`47 save path to absolute by prepending the full CWD:48 ```49 diagram_path = /absolute/cwd/temp/arch-lens-concurrency/{filename}.md50 ```51 This token is MANDATORY — the pipeline cannot proceed without it.5253## Arguments5455`/autoskillit:arch-lens-concurrency [context_path]`5657- **context_path** (optional) — Absolute path to a PR context file containing new files58 (★-prefixed) and modified files (●-prefixed) from the PR diff. When provided, read59 this file before beginning analysis and focus the diagram on the architectural areas60 affected by these specific files. When absent, explore the full CWD.6162---6364## Analysis Workflow6566### Step 0: Read PR context (when provided)6768If a `context_path` positional argument is present:691. Read the file at `context_path`702. Extract: new files list (★-prefixed), modified files list (●-prefixed)713. Focus Step 1 exploration on the modules/components these files belong to724. Apply ★ prefix on diagram nodes representing new files/components735. Apply ● prefix on diagram nodes representing modified files/components7475If no `context_path` is provided, skip this step and explore the full CWD in Step 1.7677### Step 1: Launch Parallel Exploration Subagents7879Spawn Explore subagents to investigate:8081**Concurrency Model**82- Find the primary concurrency approach83- Is it threading, asyncio, multiprocessing, coroutines?84- Look for: ThreadPoolExecutor, asyncio, ProcessPoolExecutor, async/await, goroutines, threads8586**Worker Pools**87- Find thread/process pool configurations88- Identify max_workers settings89- Look for: Executor, Pool, workers, max_*, thread pool, worker pool9091**Parallel Operations**92- Find what work is parallelized93- Identify parallel patterns (map, submit, gather)94- Look for: executor.submit, asyncio.gather, pool.map, parallel processing9596**Synchronization Points**97- Find barriers and coordination98- Identify how parallel work is collected99- Look for: as_completed, wait, gather, Lock, Semaphore, barriers, sync points100101**State Access**102- Find shared state access103- Identify thread safety mechanisms104- Look for: Lock, RLock, Queue, thread-local, immutable, atomic, mutex105106**Sequential Boundaries**107- Find what MUST run sequentially108- Identify the main thread/process responsibilities109- Look for: main(), single-threaded, atomic updates110111### Step 2: Map Concurrency Boundaries112113Document:114- **Main Thread**: What runs sequentially115- **Worker Pool**: What runs in parallel116- **Barriers**: Where parallel work converges117- **Atomic Operations**: What requires exclusive access118119**CRITICAL - Analyze Read/Write Direction:**120For EVERY concurrent component and shared resource:121- **Reads from shared state**: What data do workers READ?122- **Writes to shared state**: What data do workers WRITE?123- **Return values**: Do workers return data (read by main thread)?124- **Side effects**: Do workers write to storage directly?125126Identify:127- Read-only access (safe for parallelism)128- Write access (needs synchronization)129- Worker isolation (no shared state during execution)130131### Step 3: Identify Thread Safety132133For each shared resource:134- How is it protected?135- Who can read/write?136- Are there race conditions?137138### Step 4: Create the Diagram139140Use flowchart with:141142**Direction:** `TB` for spawn-barrier-collect pattern143144**Subgraphs:**145- Main Thread (sequential operations)146- Thread/Process Pool (parallel workers)147- Subprocess/External (if spawned processes)148- Isolation (thread safety guarantees)149150**Node Styling:**151- `terminal` class: Start/end points152- `phase` class: Sequential nodes153- `newComponent` class: Parallel workers (green)154- `detector` class: Spawn and barrier points155- `handler` class: Processing within workers156- `output` class: Atomic state updates157- `stateNode` class: Thread safety mechanisms158159**Special Elements:**160- Show fork/join points clearly161- Use edge labels for conditions162- Group parallel workers visually163164### Step 5: Write Output165166Write the diagram to: `{{AUTOSKILLIT_TEMP}}/arch-lens-concurrency/arch_diag_concurrency_{YYYY-MM-DD_HHMMSS}.md` (relative to the current working directory)167168After writing the diagram file, emit a structured output line:169170> **IMPORTANT:** Emit the structured output tokens as **literal plain text with no171> markdown formatting on the token names**. Do not wrap token names in `**bold**`,172> `*italic*`, or any other markdown. The adjudicator performs a regex match on the173> exact token name — decorators cause match failure.174175```176diagram_path = {absolute_path_to_diagram_file}177```178179---180181## Output Template182183```markdown184# Concurrency Diagram: {System Name}185186**Lens:** Concurrency (Physiological)187**Question:** How does parallelism work?188**Date:** {YYYY-MM-DD}189**Scope:** {What was analyzed}190191## Concurrency Model192193| Aspect | Value | Notes |194|--------|-------|-------|195| Primary Model | {threading/asyncio/multiprocessing} | |196| Worker Pool Type | {ThreadPoolExecutor/etc} | |197| Max Workers | {count} | |198| Parallel Operations | {what is parallelized} | |199200## Concurrency Diagram201202```mermaid203%%{init: {'flowchart': {'nodeSpacing': 40, 'rankSpacing': 50, 'curve': 'basis'}}}%%204flowchart TB205 %% CLASS DEFINITIONS %%206 classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;207 classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;208 classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;209 classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;210 classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;211 classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;212 classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;213214 subgraph MainThread ["MAIN THREAD (Sequential)"]215 direction TB216 START([START])217 INIT["Initialize<br/>━━━━━━━━━━<br/>Setup state"]218 DECISION{"Multiple<br/>items?"}219 SEQ["Sequential Path<br/>━━━━━━━━━━<br/>Single thread"]220 SPAWN["Spawn Workers<br/>━━━━━━━━━━<br/>Fork point"]221 BARRIER["Barrier<br/>━━━━━━━━━━<br/>Wait for all"]222 ATOMIC["Atomic Update<br/>━━━━━━━━━━<br/>Main thread only"]223 COMPLETE([COMPLETE])224 end225226 subgraph ThreadPool ["THREAD POOL (Parallel)"]227 direction TB228 W1["Worker 1<br/>━━━━━━━━━━<br/>Task execution"]229 W2["Worker 2<br/>━━━━━━━━━━<br/>Task execution"]230 WN["Worker N<br/>━━━━━━━━━━<br/>Task execution"]231 end232233 subgraph Isolation ["THREAD SAFETY"]234 direction TB235 ISO1["Isolated state"]236 ISO2["No shared writes"]237 ISO3["Return data only"]238 end239240 %% MAIN FLOW %%241 START --> INIT242 INIT --> DECISION243 DECISION -->|"1 item"| SEQ244 DECISION -->|"N items"| SPAWN245 SEQ --> COMPLETE246247 %% PARALLEL FLOW %%248 SPAWN --> W1249 SPAWN --> W2250 SPAWN --> WN251252 W1 --> BARRIER253 W2 --> BARRIER254 WN --> BARRIER255256 BARRIER --> ATOMIC257 ATOMIC --> COMPLETE258259 %% ISOLATION %%260 W1 -.-> ISO1261 W2 -.-> ISO2262 WN -.-> ISO3263264 %% CLASS ASSIGNMENTS %%265 class START,COMPLETE terminal;266 class INIT,SEQ phase;267 class DECISION stateNode;268 class SPAWN,BARRIER detector;269 class W1,W2,WN newComponent;270 class ATOMIC output;271 class ISO1,ISO2,ISO3 stateNode;272```273274**Color Legend:**275| Color | Category | Description |276|-------|----------|-------------|277| Dark Blue | Terminal | Start and end points |278| Purple | Sequential | Single-threaded nodes |279| Green | Workers | Parallel workers |280| Red | Synchronization | Spawn and barrier points |281| Dark Teal | Atomic | Main-thread-only state updates |282| Teal | Isolation | Thread safety guarantees |283284## Concurrency Boundaries285286| Component | Model | Synchronization |287|-----------|-------|-----------------|288| {component} | {single-threaded/parallel} | {mechanism} |289290## Thread Safety Guarantees291292- **Isolation**: {how workers are isolated}293- **State Access**: {who can modify shared state}294- **Barrier**: {how results are collected}295```296297---298299## Pre-Diagram Checklist300301Before creating the diagram, verify:302303- [ ] LOADED `/autoskillit:mermaid` skill using the Skill tool304- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)305- [ ] Diagram will include a color legend table306307---308309## Related Skills310311- `/autoskillit:make-arch-diag` - Parent skill for lens selection312- `/autoskillit:mermaid` - MUST BE LOADED before creating diagram313- `/autoskillit:arch-lens-process-flow` - For general workflow view314- `/autoskillit:arch-lens-error-resilience` - For parallel failure handling