/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`