audit-flow

⚠️ 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