feature-audit

Runtime Audit Command

You are executing the RUNTIME AUDIT workflow - a process that bridges static analysis with actual execution observation. Unlike static code analysis, this command actively injects logs, captures runtime data, and produces verifiable reports.

Contents

• Audit Target
• What Makes This Different
• File Organization
• Workflow Overview
• Phase Details
• Log Injection Design
• Error Handling

---

Audit Target

$ARGUMENTS

If no specific process was provided above, you will help the user identify what they want to audit.

---

What Makes This Different

Static analysis (code-archaeologist): Reads code, infers behavior Runtime audit (this command): Injects logs, observes actual behavior, confirms expectations

Key capability: "I think this code does X" → run audit → "Confirmed: this code actually does X"

This provides evidence-based verification rather than inference.

---

File Organization

All audit artifacts are stored in:

docs/audits/
├── registry.json                   # Index of all audits
└── [audit-id]/
    ├── report.md                   # Final audit report
    ├── session.json                # Audit metadata
    ├── injections.json             # Track all injected logs for cleanup
    └── logs/
        └── captured-[timestamp].log

Key Principles:

• Every injected log is tracked in injections.json
• Complete cleanup is always possible via the manifest
• Reports persist as permanent verification records

---

Workflow Overview

This command orchestrates a 7-phase workflow:

Phase	Name	Purpose
1	Target Identification	User describes process to audit, identify entry points
2	Code Exploration	Map execution paths, identify strategic log points
3	Injection Strategy	Plan non-invasive logs, get user approval
4	Log Injection	Add approved log statements (tracked for cleanup)
5	Runtime Capture	User executes process, capture log output
6	Analysis & Report	Analyze data, verify behavior, generate report
7	Cleanup	Remove injected logs, restore code to pre-audit state

---

Phase Details

Phase 1: Target Identification

See: target.md

• Understand what process/behavior to audit
• Identify entry points and key questions
• Create audit session with unique ID
• Initialize audit directory structure

Phase 2: Code Exploration

See: exploration.md

• Map execution paths from entry points
• Identify data flows and transformations
• Find strategic locations for log injection
• Document assumptions to verify

Phase 3: Injection Strategy

See: injection-strategy.md

• Plan specific log statements for each location
• Use language-appropriate patterns
• Present plan to user for approval
• Explain what each log will reveal

Phase 4: Log Injection (Requires Approval)

See: injection-active.md

• Inject approved log statements
• Mark each with // AUDIT-INJECTED comment
• Track all changes in injections.json
• Verify code still compiles/runs

Phase 5: Runtime Capture

See: runtime-capture.md

• User chooses capture method (paste or direct execution)
• Capture log output from process execution
• Store captured data in audit directory
• Support multiple capture rounds if needed

Phase 6: Analysis & Report

See: analysis.md

• Parse captured log output
• Compare actual behavior to expectations
• Identify verified behaviors vs unexpected findings
• Generate comprehensive audit report

Phase 7: Cleanup

See: cleanup.md

• Remove all injected log statements
• Verify code is restored to pre-audit state
• Update audit session as complete
• Present final report summary

---

Log Injection Design

Safety Principles

• All injected code tagged with language-appropriate marker
• Tracked in injections.json for reliable cleanup
• User approval required before any code modification
• Logs are observational only (no behavior changes)

Language-Agnostic Templates

Language	Log Pattern	Marker
TypeScript/JS	console.log('[AUDIT:id:N]', data);	// AUDIT-INJECTED
Python	print(f'[AUDIT:id:N] {data}')	# AUDIT-INJECTED
Go	fmt.Printf("[AUDIT:id:N] %v\n", data)	// AUDIT-INJECTED
Rust	println!("[AUDIT:{}:{}] {:?}", id, n, data);	// AUDIT-INJECTED
Java	System.out.println("[AUDIT:id:N] " + data);	// AUDIT-INJECTED

Language is detected from file extension and appropriate template applied.

Rollback Guarantee

Every modification is tracked in injections.json:

{
  "auditId": "auth-flow-001",
  "injections": [
    {
      "id": 1,
      "file": "src/auth/login.ts",
      "line": 42,
      "originalContent": "",
      "injectedContent": "console.log('[AUDIT:auth-flow-001:1]', user);",
      "purpose": "Log user object at login entry"
    }
  ]
}

Cleanup phase uses this manifest to restore exact original state.

---

Runtime Capture Options

User chooses per-audit:

Method	Use When	How It Works
Paste output	Complex environments, CI/CD, remote systems	User runs process externally, pastes logs back
Direct execution	Local development, simple commands	Command runs via Bash, captures stdout/stderr

---

Error Handling

Error	Resolution
Cannot identify entry point	Ask user for more specific process description
Injection causes compile error	Rollback that injection, try different approach
No logs captured	Verify process was executed with injected code
Partial cleanup failure	Show remaining injections, offer manual cleanup
Audit directory missing	Create docs/audits/ if needed

---

Integration Points

• Complements feature workflow: /feature-plan → /feature-implement → /feature-audit → /feature-submit → /feature-ship
• Standalone use: Audit any existing process without feature context
• Works with code-archaeologist: Static analysis → audit to verify assumptions

---

Philosophy: "Trust, But Verify"

Static analysis tells you what code should do. Runtime auditing shows you what code actually does.

This command helps you:

• Verify assumptions about code behavior
• Debug unexpected runtime behavior
• Document actual execution paths
• Build confidence before shipping

---

Let's identify what you want to audit!