audit-flow

name	audit-flow
description	Interactive system flow tracing across CODE, API, AUTH, DATA, NETWORK layers with SQLite persistence and Mermaid export. Use for security audits, compliance documentation, flow tracing, feature ideation, brainstorming, debugging, architecture reviews, or incident post-mortems. Triggers on audit, trace flow, document flow, security review, debug flow, brainstorm, architecture review, post-mortem, incident review.
license	MIT
compatibility	Requires Python 3.8+ (stdlib only, zero dependencies). Optional pyyaml for YAML export. Git for merge/diff driver features.
metadata	{"author":"ArunJRK","version":"1.0.0"}

⚠️ MANDATORY ENTRY POINT — Execute Before ANY Other Action

Step 1: Read schema.sql

# ALWAYS read the schema first to understand tables, constraints, views
cat .claude/skills/audit-flow/schema.sql

Step 2: Check if DB exists — NEVER recreate

# Check for existing database
ls -la .audit/audit.db 2>/dev/null && echo "DB EXISTS - DO NOT RECREATE" || echo "No DB - safe to init"

Step 3: If DB exists, show current state

python .claude/skills/audit-flow/scripts/audit.py list

🚫 FORBIDDEN ACTIONS

Action	Why Forbidden
rm .audit/audit.db	Destroys audit history
audit.py init when DB exists	Overwrites existing data
DROP TABLE	Destroys audit history
sqlite3 .audit/audit.db < schema.sql when DB exists	Overwrites existing data

Rule: If .audit/audit.db exists, ONLY use audit.py list, show, export, or INSERT operations. NEVER recreate.

---

Audit Flow

Interactive tracing of system flows with SQLite persistence. Supports multiple named flows per session, non-linear flows (branching/merging), and multi-format exports.

Organization Principles

Directory structure by purpose:

• Audits/Documentation/Compliance: docs/audits/{name}-{YYYY-MM-DD}/
• Ideation/Brainstorming: docs/ideation/{name}-{YYYY-MM-DD}.md (single file, no subdirectory unless artifacts needed)
• Debugging/Incident Review: docs/audits/{name}-{YYYY-MM-DD}/ (same as audits — captures evidence)
• Architecture Review: docs/audits/{name}-{YYYY-MM-DD}/ (same as audits — captures structural analysis)

Required files:

• INDEX.md (manifest, entry point)
• README.md (executive summary)
• {name}-audit.md (flow trace)

Lazy initialization: Create subdirectories only when artifacts exist

• screenshots/ network-traces/ diagrams/ code-samples/ test-results/ evidence/

Naming: {audit-name}-{type}.md

DB-First Discipline

Invariant: SQLite = sole source of truth. Context window: volatile, compacts without notice, hallucinates state.

🚨 CRITICAL: NEVER DESTROY EXISTING DATA

• If .audit/audit.db exists → it contains irreplaceable audit history
• NEVER run init when DB exists — use list to see what's there
• NEVER delete, drop, or recreate — only append

Constraints:

Operation	Rule	Blocked rationalization
Entry	Read schema.sql FIRST, check if DB exists SECOND	"I'll just start working"
Init	ONLY if .audit/audit.db does NOT exist	"Let me reinitialize to start fresh"
Schema	Read schema.sql BEFORE any SQLite command — understand tables, constraints, views first	"I know the schema from context"
Write	INSERT each tuple/edge/finding before moving to the next code location	"I'll batch-insert at the end"
Read	SELECT from DB before referencing tuple IDs, counts, or flow structure	"I remember the flow so far"
Export	audit.py export only — never generate mermaid/markdown from context	"Let me generate mermaid directly"
Resume	audit.py show <session> before any operation that references prior tuples	"I have the full trace in context"
Reference	Query tuple IDs from DB — IDs are DB-assigned, never inferred	"The tuple ID should be N"
Default	When uncertain of flow state → query DB before proceeding	(any unlisted rationalization)

Checkpoint: Every 5 tuples → audit.py show <session> <flow>

---

Interactive Workflow - ALWAYS ASK USER

1. Session Start - Ask:

Name: ___
Purpose: security-audit | documentation | compliance | ideation | brainstorming | debugging | architecture-review | incident-review
Description: ___ (optional)

Initialize directory immediately. Lazily create subdirectories when artifacts are generated.

2. Granularity - Ask:

[fine]   Function-level trace (~50-200 tuples)
         Use: Security audits, debugging

[coarse] Boundary-level trace (~10-30 tuples)
         Use: Documentation, high-level flows

Choose: fine / coarse

3. During Trace:

Ask at decision points: trace deeper? mark concern? add finding (severity)? note?

4. On Export:

Ask format: json | yaml | md | mermaid | all

Post-export: Generate INDEX.md manifest. Organize artifacts by type. Prune empty directories.

Quick Reference

Command	Purpose
/audit-flow start	New session (name, purpose, granularity)
/audit-flow flow {name}	Add new flow to session
/audit-flow add {layer} {desc}	Add tuple to current flow
/audit-flow link {from} {to} {rel}	Create edge (supports conditions for branches)
/audit-flow finding {desc}	Record finding
/audit-flow show	View session/flow details
/audit-flow export	Export (json/yaml/md/mermaid)
/audit-flow git-setup	Configure git merge/diff drivers (once)

Layers: CODE | API | NETWORK | AUTH | DATA

Relations: TRIGGERS | READS | WRITES | VALIDATES | TRANSFORMS | BRANCHES | MERGES

Semantic Rules for Relations

Relation	Meaning	Use When	NOT For
TRIGGERS	A causes B to execute	Function calls, event handlers, HTTP requests	Static observations
READS	A consumes data from B	Cookie reads, DB queries, config lookups	Mutations
WRITES	A mutates data in B	Cookie writes, DB inserts, state updates	Read-only access
VALIDATES	A checks/verifies B	Auth checks, input validation, expiry checks	Chaining analyst observations
TRANSFORMS	A converts/maps data for B	Token exchange, response formatting	Unrelated processing
BRANCHES	A has conditional paths	if/else, switch, error vs success	Must have condition label
MERGES	Multiple paths converge at B	Parallel paths rejoin, error recovery	Single-path flow

CRITICAL: BRANCHES Must Have Conditions. Every BRANCHES edge requires a condition describing which path. Example: BRANCHES [token expired] vs BRANCHES [token valid].

Observations vs Flow Steps

Flow steps = things the SYSTEM DOES (function calls, data reads, network requests). Verified by tracing code.

Observations = things the ANALYST NOTES (missing features, potential risks). Record as findings, not tuples.

Wrong pattern:

T50 "NO cross-tab sync"       ← observation, not a system action
T51 "React state NOT shared"  ← observation
T50 --VALIDATES--> T51         ← chaining observations as flow

Correct pattern:

-- Record as finding instead:
INSERT INTO findings (flow_id, session_id, severity, category, description)
VALUES (?, ?, 'medium', 'state-management',
        'No cross-tab sync: React state not shared across tabs');

Rule: NEVER chain observations with VALIDATES. If describing what the system DOESN'T do, use a finding.

Data Model

Session (audit container)
  └── Flow (named DAG with entry point)
       └── Tuple (node: layer + action + subject)
            └── Edge (relation + optional condition)

Storage & CLI

# Core
python .claude/skills/audit-flow/scripts/audit.py init              # Initialize DB
python .claude/skills/audit-flow/scripts/audit.py list              # List sessions
python .claude/skills/audit-flow/scripts/audit.py show <session>    # Show flows
python .claude/skills/audit-flow/scripts/audit.py show <session> <flow>  # Show flow details
python .claude/skills/audit-flow/scripts/audit.py export <session>  # Export all
python .claude/skills/audit-flow/scripts/audit.py export <session> -f <flow>  # Export one flow
python .claude/skills/audit-flow/scripts/audit.py validate <session>         # Validate flows

# Git integration
python .claude/skills/audit-flow/scripts/audit.py git-setup         # Configure merge/diff drivers (once)
python .claude/skills/audit-flow/scripts/audit.py db-merge %O %A %B # Git merge driver (auto-called)

# CSV backup/portability (optional)
python .claude/skills/audit-flow/scripts/audit.py csv-export               # DB → .audit/csv/*.csv
python .claude/skills/audit-flow/scripts/audit.py csv-import               # .audit/csv/*.csv → DB
python .claude/skills/audit-flow/scripts/audit.py csv-merge <theirs_dir>   # Merge two CSV sets

Non-Linear Flows

Branching: One tuple → multiple outgoing edges with conditions

INSERT INTO edges (from_tuple, to_tuple, relation, condition)
VALUES (5, 6, 'BRANCHES', 'token valid'),
       (5, 7, 'BRANCHES', 'token expired');

Merging: Multiple tuples → one tuple

INSERT INTO edges (from_tuple, to_tuple, relation)
VALUES (6, 8, 'TRIGGERS'),
       (9, 8, 'MERGES');  -- refresh path merges back

Files

• scripts/audit.py - CLI for all commands (init, list, show, export, validate, db-merge, git-setup, csv-*)
• COMMANDS.md - Detailed SQL reference
• EXAMPLES.md - Full examples with non-linear flows
• schema.sql - Database schema
• .gitattributes - Git merge/diff driver config for audit.db

Git Context

Capture on session start: commit hash, branch, working tree status. Include in all exports.

Mermaid Validation

Run python .claude/skills/audit-flow/scripts/audit.py validate <session> before export.

Check	Severity	Description
BRANCHES without condition	ERROR	Every BRANCHES edge needs a condition label
Node count >= 60	ERROR	Split into sub-flows
Node count >= 40	WARN	Consider splitting
Orphan nodes	WARN	Node with no edges (disconnected)
Duplicate labels	WARN	Same action text without subject disambiguation
No entry point	WARN	All nodes have incoming edges

Post-export features (automatic):

• Step numbers: BFS topological order from entry point (1. action, 2. action)
• Entry point: Stadium shape with green styling
• Edge arrows: --> solid (TRIGGERS/VALIDATES/TRANSFORMS/BRANCHES/MERGES), -.-> dotted (READS), ==> thick (WRITES)
• Observations: Separated into dashed-border OBSERVATIONS subgraph
• Direction: --direction LR flag for horizontal layouts

Diagram Readability Requirements

All diagrams MUST be produced by audit.py export. Never hand-craft mermaid. The exporter enforces:

1. Entry point marker — Green stadium-shape node ([label]):::entryPoint
2. Step numbers — BFS topological order: 1. action, 2. action, 3. action
3. Legend block — classDef styles for entryPoint, concern, observation
4. Observation separation — Concern-only chains go to OBSERVATIONS subgraph, not main flow
5. Label safety — HTML entities for (), "", <>, |, [] characters (auto-sanitized)

Reading flow must be obvious. A reader opening the diagram cold must immediately see:

• WHERE to start (green entry node)
• WHAT ORDER to read (step numbers)
• WHICH PATH is happy vs error (branch conditions on edges)
• WHAT THE COLORS MEAN (legend)

Node label rules:

• Use concrete nouns/verbs: handleCallback(), exchangeCodeForTokens()
• NOT bare verbs: "Configure", "Select", "Enable"
• Disambiguate duplicates: auto-suffixed with subject when action repeats

Size limits:

• 40+ nodes → warning, consider splitting
• 60+ nodes → error, MUST split into sub-flows
• If flow has 5+ independent sub-flows → split by purpose

---

Git Workflow — Custom Merge Driver

Problem: SQLite is binary — git merge can't auto-resolve .audit/audit.db.

Solution: Custom git merge driver. audit.db stays in git (small, single file). On conflict, git calls audit.py db-merge to auto-merge using SQL.

One-Time Setup

python .claude/skills/audit-flow/scripts/audit.py git-setup

This configures (in .git/config):

• Merge driver: merge.sqlite-audit — calls audit.py db-merge %O %A %B on conflict
• Diff driver: diff.sqlite — sqlite3 .dump for readable git diff output

Also requires .gitattributes (already in repo):

.audit/audit.db diff=sqlite merge=sqlite-audit

How It Works

1. You commit audit.db normally — git add .audit/audit.db && git commit
2. git diff shows SQL text (via textconv)
3. On git merge with conflict → git calls the merge driver automatically
4. Driver opens both DBs, merges sessions by name (later updated_at wins), remaps IDs
5. Result written to ours — merge completes cleanly

Merge Strategy

Table	Merge Key	Conflict Resolution
sessions	name (unique)	Keep later updated_at
flows	(session_name, flow_name)	Follow parent session winner
tuples	Parent flow	All tuples from winning flow kept
edges	Both endpoint tuples	Kept if both endpoints survive
findings	(session_name, category, description)	Dedup by content

All INTEGER PKs remapped sequentially. Foreign keys updated.

CSV Backup (Optional)

CSV export/import still available for portability and backup:

python .claude/skills/audit-flow/scripts/audit.py csv-export   # DB → .audit/csv/*.csv (QUOTE_ALL)
python .claude/skills/audit-flow/scripts/audit.py csv-import   # CSV → DB (recreates from scratch)

---

Output Quality

Principles:

• ASCII sequence diagrams for complex flows
• Side-by-side tables for alternatives
• Real code from traced files with file:line references
• What/Why/Example pattern
• No generic templates

Completion Checklist

• Directory exists with ISO date suffix
• INDEX.md manifest generated
• README.md (executive summary)
• Naming convention: {name}-{type}.md
• Artifacts in typed subdirectories (lazy init)
• Git context captured
• Git merge driver configured (audit.py git-setup)
• No orphaned files
• Diagrams pass audit.py validate

Anti-Patterns

Flat structure, empty directories, orphan nodes, unlabeled branches, generic identifiers, missing git context, no manifest, hand-crafted mermaid, bare-verb labels.