audit-flow

Files (6)

• COMMANDS.md
• EXAMPLES.md
• SKILL.md
• schema.sql
• audit.py · scripts/
• setup.sh

SKILL.md (first lines)

## ⚠️ MANDATORY ENTRY POINT — Execute Before ANY Other Action

**Step 1: Read schema.sql**

```bash
# 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**

```bash
# 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**

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

From zebbern/claude-code-guide, MIT.

More from zebbern/claude-code-guide