SourceAtlas: Flow Analysis Skill

SourceAtlas: Flow Analysis

Target: $ARGUMENTS

STEP 0: Mode Detection (EXECUTE IMMEDIATELY)

IMPORTANT: Check these patterns FIRST before doing anything else.

Check for Tier 2-3 Keywords (External Mode Required)

Scan $ARGUMENTS for these keywords. If ANY match, load external file and STOP reading this document:

| If arguments contain... | Then execute this action | |------------------------|--------------------------| | "dead code" OR "unreachable" OR "unused" | Read scripts/atlas/flow-modes/mode-13-dead-code.md then follow its instructions | | "async" OR "thread" OR "concurrent" OR "race" | Read scripts/atlas/flow-modes/mode-14-concurrency.md then follow its instructions | | "taint" OR "injection" OR "untrusted" | Read scripts/atlas/flow-modes/mode-12-taint-analysis.md then follow its instructions | | "state" OR "status" OR "lifecycle" | Read scripts/atlas/flow-modes/mode-04-state-machine.md then follow its instructions | | "transaction" OR "rollback" OR "commit" | Read scripts/atlas/flow-modes/mode-09-transaction.md then follow its instructions | | "log" OR "logging" OR "from logs" | Read scripts/atlas/flow-modes/mode-06-log-discovery.md then follow its instructions | | "compare" OR "diff" OR "vs" | Read scripts/atlas/flow-modes/mode-05-flow-comparison.md then follow its instructions | | "feature toggle" OR "feature flag" | Read scripts/atlas/flow-modes/mode-07-feature-toggle.md then follow its instructions | | "cache" OR "redis" OR "TTL" | Read scripts/atlas/flow-modes/mode-11-cache-flow.md then follow its instructions |

If a keyword matched above: Load the file NOW, then execute ONLY that mode's instructions. Do NOT continue reading this document.

Check for Tier 1 Keywords (Built-in Modes)

If none of the above matched, check for these Tier 1 patterns:

| If arguments contain... | Mode to use | |------------------------|-------------| | "who calls" OR "callers" OR "called by" | Mode 1: Reverse Tracing (see below) | | "error" OR "failure" OR "exception" OR "fail" | Mode 2: Error Path (see below) | | "data flow" OR "how is X calculated" OR "trace variable" | Mode 3: Data Flow (see below) | | "event" OR "message" OR "pub/sub" OR "listener" | Mode 8: Event Tracing (see below) | | "permission" OR "role" OR "auth" OR "access control" | Mode 10: Permission Flow (see below) | | (none of the above) | Standard Flow Tracing (default) |

STEP 1: Cache Check

If --force NOT in arguments:

Convert flow name to filename: lowercase, spaces→hyphens, max 50 chars
Check: ls .sourceatlas/flows/{name}.md 2>/dev/null
If exists: Load and output cache, then STOP
If not exists: Continue

STEP 2: Find Entry Point

If explicit path given (e.g., "from OrderService.create()"): → Start tracing immediately

If flow description only (e.g., "checkout flow"): → Search for entry points:

grep -rn "{keyword}" --include="*.ts" --include="*.js" --include="*.py" src/ app/ lib/ 2>/dev/null | head -15

→ Present options if multiple matches

STEP 3: Trace Flow

From entry point, trace each step:

Read the function
Identify what it calls
Follow the chain (depth: 5 levels default)
Stop at boundaries (DB, external API, third-party)

For each step capture:

Function name
File:line location
Business meaning
Notable patterns (🔒 security, 💾 DB, 🌐 API, ⚡ async, ⚠️ risk)

STEP 4: Output Format

{Flow Name}
===========

Entry Point: {file}:{line}

┌──────┬──────────────────────────────┬───────────────────────┐
│ Step │ Operation                    │ Location              │
├──────┼──────────────────────────────┼───────────────────────┤
│  1   │ {description}                │ {file}:{line}         │
│  2   │ {description}                │ {file}:{line}         │
└──────┴──────────────────────────────┴───────────────────────┘

Flow Diagram:
{entry}() → {step1}() → {step2}() → {step3}()

Notable Patterns:
├── 🔒 {pattern1}
├── 💾 {pattern2}
└── ⚠️ {pattern3}

───────────────────────────────────
📊 Mode: Standard | Confidence: ~85% | Depth: 5
───────────────────────────────────

Tier 1 Mode: Reverse Tracing

Trigger: "who calls", "callers", "called by"

Find all callers of target function:

Who calls {function}?
=====================

Callers (N found):
├── {Caller1}()  → {description}
│   📍 {file}:{line}
├── {Caller2}()  → {description}
│   📍 {file}:{line}
└── {Caller3}()  → {description}
    📍 {file}:{line}

💡 Modifying {function} affects these {N} callers

Tier 1 Mode: Error Path

Trigger: "error", "failure", "exception", "fail"

Trace failure scenarios:

{Flow} Error Paths
==================

1. {Step}
   📍 {file}:{line}
   ⚠️ Failure → {ErrorType}
      └── {what happens}

📌 Risk: {identified risk}

Tier 1 Mode: Data Flow

Trigger: "data flow", "how is X calculated", "trace variable"

Track data transformations:

Data Flow: {variable}
=====================

[Input] {source}
   ↓
1. {Transform}  → {result}
   📍 {file}:{line}
   ↓
[Output] {final}

Tier 1 Mode: Event Tracing

Trigger: "event", "message", "pub/sub", "listener"

{EVENT} Tracing
===============

📤 Emission: {Publisher}() → emit("{EVENT}")
   📍 {file}:{line}

📥 Listeners:
├── {Listener1}()  → {action}
│   📍 {file}:{line}
└── {Listener2}()  → {action}
    📍 {file}:{line}

Tier 1 Mode: Permission Flow

Trigger: "permission", "role", "auth", "access control"

{Operation} by Role
===================

[ADMIN] → Full access
├── {check}  🔐 @RequireRole("ADMIN")
└── 📍 {file}:{line}

[USER] → Limited access
├── {check}  🔐 @CheckOwnership
└── 📍 {file}:{line}

Self-Verification

Before output, verify:

File paths exist: test -f {path}
Methods exist: grep -q "{method}" {file}

Add to footer: ✅ Verified: [N] paths, [M] methods

Auto-Save (Default Behavior)

After analysis completes, automatically:

mkdir -p .sourceatlas/flows
Save to .sourceatlas/flows/{name}.md
Append: 💾 Saved to .sourceatlas/flows/{name}.md

Deprecated: --save flag

If --save is in arguments:

Show: ⚠️ --save is deprecated, auto-save is now default
Remove --save from arguments
Continue normal execution (still auto-saves)

🗺️ SourceAtlas v3.0 │ Tiered Architecture

Agent Skills: SourceAtlas: Flow Analysis

Install this agent skill to your local

Skill Files