when-validating-code-works-use-functionality-audit

What this skill does

# Functionality Audit - Code Execution Validation

## When to Use This Skill

**Trigger Conditions:**
- After generating new code or modifying existing code
- When code appears complete but actual functionality is uncertain
- Before merging PRs or deploying to production
- When debugging reported issues or unexpected behavior
- As part of quality assurance workflows
- When validating third-party code integrations

**Situations Requiring Functionality Audit:**
- Code generated by AI that needs execution validation
- Complex logic changes requiring runtime verification
- Integration of new libraries or dependencies
- Refactoring that may have introduced regressions
- Migration to new frameworks or language versions

## Overview

This skill systematically validates that code delivers its intended behavior through actual execution rather than static analysis alone. It creates isolated testing environments (sandboxes), executes code with realistic inputs, captures outputs and errors, identifies root causes of failures through systematic debugging, and applies fixes using best practices that preserve existing functionality.

The skill emphasizes **genuine functionality over appearance**, detecting "theater code" that looks correct but fails during execution. It combines automated testing, manual validation, and debugging expertise to ensure code reliability.

## Phase 1: Setup Testing Environment (Sequential)

**Agents**: tester (lead), coder (support)
**Duration**: 10-15 minutes

**Scripts**:
```bash
# Initialize phase
npx claude-flow hooks pre-task --description "Phase 1: Setup Testing Environment"
npx claude-flow swarm init --topology hierarchical --max-agents 2

# Spawn agents
npx claude-flow agent spawn --type tester --capabilities "sandbox-setup,environment-config,dependency-management"
npx claude-flow agent spawn --type coder --capabilities "tooling-setup,script-generation"

# Memory coordination - store environment config
npx claude-flow memory store --key "testing/functionality-audit/phase-1/tester/sandbox-config" --value '{"isolated":true,"snapshot_enabled":true}'
npx claude-flow memory store --key "testing/functionality-audit/phase-1/coder/dependencies" --value '{"package_manager":"npm","install_command":"npm install"}'

# Execute phase work
# 1. Create isolated sandbox environment
echo "Creating sandbox for code execution..."
mkdir -p /tmp/functionality-audit-sandbox
cd /tmp/functionality-audit-sandbox

# 2. Install dependencies and setup tools
npm init -y 2>/dev/null || true
npm install --save-dev jest @types/jest ts-node typescript 2>/dev/null || true

# 3. Configure testing framework
cat > jest.config.js << 'EOF'
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  collectCoverage: true,
  coverageDirectory: 'coverage',
  testMatch: ['**/*.test.ts', '**/*.test.js'],
  verbose: true
};
EOF

# Complete phase
npx claude-flow hooks post-task --task-id "phase-1-setup"
npx claude-flow memory store --key "testing/functionality-audit/phase-1/output" --value '{"status":"complete","sandbox_ready":true}'
```

**Memory Pattern**:
- Input: `testing/functionality-audit/phase-0/user/code-to-validate`
- Output: `testing/functionality-audit/phase-1/tester/sandbox-ready`
- Shared: `testing/functionality-audit/shared/environment-config`

**Success Criteria**:
- [ ] Isolated sandbox environment created successfully
- [ ] All required dependencies installed without errors
- [ ] Testing framework configured and operational
- [ ] Environment snapshot created for rollback capability
- [ ] Sandbox validation completed (basic sanity checks pass)

**Deliverables**:
- Configured sandbox environment
- Dependency manifest (package.json or requirements.txt)
- Testing framework configuration files
- Environment setup documentation

## Phase 2: Execute Code with Realistic Inputs (Parallel)

**Agents**: tester (lead), production-validator (support)
**Duration**: 15-20 minutes

**Scripts**:
```bash
# Initialize phase
npx claude-flow hooks pre-task --description "Phase 2: Execute Code with Realistic Inputs"
npx claude-flow swarm scale --target-agents 2

# Retrieve sandbox config from Phase 1
npx claude-flow memory retrieve --key "testing/functionality-audit/phase-1/output"

# Memory coordination - define test scenarios
npx claude-flow memory store --key "testing/functionality-audit/phase-2/tester/test-scenarios" --value '{"unit_tests":true,"integration_tests":true,"edge_cases":true}'

# Execute phase work
# 1. Copy code to sandbox
echo "Copying code to sandbox environment..."
# (Code paths retrieved from memory)

# 2. Generate test cases with realistic inputs
cat > sandbox-tests.test.js << 'EOF'
// Auto-generated test cases for functionality validation
describe('Functionality Audit Tests', () => {
  test('Happy path with valid inputs', async () => {
    // Test implementation with realistic data
  });

  test('Edge cases and boundary conditions', async () => {
    // Test edge cases
  });

  test('Error handling with invalid inputs', async () => {
    // Test error scenarios
  });
});
EOF

# 3. Execute tests and capture output
npm test -- --coverage --verbose > test-output.log 2>&1
TEST_EXIT_CODE=$?

# 4. Store results in memory
npx claude-flow memory store --key "testing/functionality-audit/phase-2/tester/execution-results" --value "{\"exit_code\":$TEST_EXIT_CODE,\"timestamp\":\"$(date -Iseconds)\"}"

# Complete phase
npx claude-flow hooks post-task --task-id "phase-2-execute"
```

**Memory Pattern**:
- Input: `testing/functionality-audit/phase-1/tester/sandbox-ready`
- Output: `testing/functionality-audit/phase-2/tester/execution-results`
- Shared: `testing/functionality-audit/shared/test-logs`

**Success Criteria**:
- [ ] All test cases executed without environment errors
- [ ] Output captured completely (stdout, stderr, exit codes)
- [ ] Code coverage metrics collected successfully
- [ ] Performance metrics recorded (execution time, memory usage)
- [ ] Results stored in structured format for analysis

**Deliverables**:
- Test execution logs with full output
- Code coverage reports
- Performance metrics
- Captured errors and stack traces
- Test results summary

## Phase 3: Debug Issues (Sequential)

**Agents**: coder (lead), tester (support), reviewer (validation)
**Duration**: 20-30 minutes

**Scripts**:
```bash
# Initialize phase
npx claude-flow hooks pre-task --description "Phase 3: Debug Issues"
npx claude-flow swarm scale --target-agents 3

# Retrieve execution results from Phase 2
npx claude-flow memory retrieve --key "testing/functionality-audit/phase-2/tester/execution-results"

# Memory coordination - analyze failures
npx claude-flow memory store --key "testing/functionality-audit/phase-3/coder/debugging-strategy" --value '{"method":"systematic-root-cause","tools":["debugger","logs","profiler"]}'

# Execute phase work
# 1. Analyze test failures systematically
echo "Analyzing failures and errors..."
grep -E "(FAIL|ERROR|Exception)" test-output.log > failures.txt || true

# 2. Identify root causes using debugging techniques
# - Stack trace analysis
# - Variable inspection
# - Logic flow validation
# - Dependency conflict detection

# 3. Categorize issues by type
cat > issue-analysis.json << 'EOF'
{
  "syntax_errors": [],
  "runtime_errors": [],
  "logic_errors": [],
  "integration_failures": [],
  "dependency_issues": []
}
EOF

# 4. Prioritize fixes by impact
# Critical: Code doesn't run at all
# High: Core functionality broken
# Medium: Edge cases failing
# Low: Minor issues, optimizations

# Store debugging results
npx claude-flow memory store --key "testing/functionality-audit/phase-3/coder/root-causes" --value "$(cat issue-analysis.json)"

# Complete phase
npx claude-flow hooks post-task --task-id "phase-3-debug"
```

**Memory Pattern**:
- Input: `testing/functionality-audit/phase-2/tester/execution-results`
- Output: `testing/functionality-audit/phase-3/coder/root-causes`
- Shared: `testing/functionality-audit/shared/issue-tracker`

**Success