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 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 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:

Error Handling

Integration Points

• Complements feature workflow: /feature-plan → implement → /feature-audit → /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!