record-quality-baseline

Purpose

Capture current code quality metrics before making changes to enable before/after comparison and ensure refactoring improves (or maintains) quality standards.

When to Use

• Refactor agent Step 1 (Pre-Refactor Validation)
• Before any code restructuring or simplification
• Before technical debt reduction
• When establishing quality improvement targets
• Before major feature implementation

Instructions

Step 1: Run Baseline Tests

echo "→ Recording quality baseline..."
echo ""

# Run tests with coverage
echo "Running tests..."
if npm run test -- --coverage --silent 2>&1 | tee .claude/baseline/test-output.txt; then
  TEST_STATUS="passing"
  TEST_EXIT_CODE=0
else
  TEST_STATUS="failing"
  TEST_EXIT_CODE=$?
fi

# Extract test metrics
TOTAL_TESTS=$(grep -oP '\d+ tests?' .claude/baseline/test-output.txt | head -1 | grep -oP '\d+' || echo "0")
PASSED_TESTS=$(grep -oP '\d+ passed' .claude/baseline/test-output.txt | grep -oP '\d+' || echo "0")
FAILED_TESTS=$(grep -oP '\d+ failed' .claude/baseline/test-output.txt | grep -oP '\d+' || echo "0")

Step 2: Extract Coverage Metrics

# Parse coverage from output or coverage file
if [ -f coverage/coverage-summary.json ]; then
  COVERAGE=$(jq -r '.total.lines.pct' coverage/coverage-summary.json)
  STMT_COVERAGE=$(jq -r '.total.statements.pct' coverage/coverage-summary.json)
  BRANCH_COVERAGE=$(jq -r '.total.branches.pct' coverage/coverage-summary.json)
  FUNCTION_COVERAGE=$(jq -r '.total.functions.pct' coverage/coverage-summary.json)
else
  # Fallback: parse from text output
  COVERAGE=$(grep -oP 'All files.*?\|\s+(\d+\.\d+)' .claude/baseline/test-output.txt | grep -oP '\d+\.\d+' || echo "0")
  STMT_COVERAGE=$COVERAGE
  BRANCH_COVERAGE=$COVERAGE
  FUNCTION_COVERAGE=$COVERAGE
fi

echo "✅ Test baseline recorded"
echo "   Tests: $PASSED_TESTS/$TOTAL_TESTS passing"
echo "   Coverage: ${COVERAGE}%"

Step 3: Run Code Quality Audit

# Run audit if available
if npm run audit:code --silent 2>&1 | tee .claude/baseline/audit-output.txt; then
  AUDIT_STATUS="success"
else
  AUDIT_STATUS="not_available"
fi

# Parse audit score (if available)
if [ "$AUDIT_STATUS" = "success" ]; then
  AUDIT_SCORE=$(grep -oP 'Score:\s+(\d+\.\d+)' .claude/baseline/audit-output.txt | grep -oP '\d+\.\d+' || echo "0")
  echo "✅ Audit baseline recorded"
  echo "   Score: ${AUDIT_SCORE}/10"
else
  AUDIT_SCORE="N/A"
  echo "ℹ️ Code audit not available"
fi

Step 4: Check TypeScript Errors

# Run TypeScript check
if command -v tsc &>/dev/null; then
  if tsc --noEmit 2>&1 | tee .claude/baseline/tsc-output.txt; then
    TS_ERRORS=0
    TS_STATUS="passing"
  else
    TS_ERRORS=$(grep -c 'error TS' .claude/baseline/tsc-output.txt || echo "0")
    TS_STATUS="failing"
  fi

  echo "✅ TypeScript baseline recorded"
  echo "   Errors: $TS_ERRORS"
else
  TS_ERRORS="N/A"
  TS_STATUS="not_available"
  echo "ℹ️ TypeScript not available"
fi

Step 5: Analyze Code Complexity (Optional)

# If complexity analysis tool available
if command -v complexity &>/dev/null; then
  COMPLEXITY=$(complexity analyze src/ --json 2>/dev/null || echo "{}")
  echo "✅ Complexity baseline recorded"
else
  COMPLEXITY="N/A"
  echo "ℹ️ Complexity analysis not available"
fi

Step 6: Save Baseline to File

mkdir -p .claude/baseline

TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)

cat > .claude/baseline/quality-baseline.json << EOF
{
  "timestamp": "$TIMESTAMP",
  "tests": {
    "status": "$TEST_STATUS",
    "total": $TOTAL_TESTS,
    "passed": $PASSED_TESTS,
    "failed": $FAILED_TESTS,
    "exitCode": $TEST_EXIT_CODE
  },
  "coverage": {
    "overall": $COVERAGE,
    "statements": $STMT_COVERAGE,
    "branches": $BRANCH_COVERAGE,
    "functions": $FUNCTION_COVERAGE
  },
  "audit": {
    "status": "$AUDIT_STATUS",
    "score": "$AUDIT_SCORE"
  },
  "typescript": {
    "status": "$TS_STATUS",
    "errors": $TS_ERRORS
  },
  "complexity": $COMPLEXITY,
  "git": {
    "branch": "$(git branch --show-current)",
    "commit": "$(git rev-parse --short HEAD)"
  }
}
EOF

echo ""
echo "✅ Quality baseline saved to .claude/baseline/quality-baseline.json"

Step 7: Validate Baseline Requirements

# Check if baseline meets minimum requirements for refactoring
CAN_REFACTOR=true

if [ "$TEST_STATUS" != "passing" ]; then
  echo "❌ Cannot proceed - tests failing before refactoring"
  CAN_REFACTOR=false
fi

if [ "$TS_STATUS" = "failing" ]; then
  echo "⚠️ Warning: TypeScript errors exist before refactoring"
fi

if [ "$CAN_REFACTOR" = true ]; then
  echo "✅ Quality baseline acceptable - safe to proceed with refactoring"
else
  echo "❌ Quality baseline unacceptable - fix test failures first"
  exit 1
fi

Output Format

Successful Baseline

{
  "status": "success",
  "baseline": {
    "timestamp": "2025-10-21T14:30:00Z",
    "tests": {
      "status": "passing",
      "total": 45,
      "passed": 45,
      "failed": 0
    },
    "coverage": {
      "overall": 87.5,
      "statements": 88.2,
      "branches": 84.1,
      "functions": 89.3
    },
    "audit": {
      "status": "success",
      "score": 7.5
    },
    "typescript": {
      "status": "passing",
      "errors": 0
    },
    "canProceed": true
  },
  "file": ".claude/baseline/quality-baseline.json"
}

Baseline with Failing Tests

{
  "status": "error",
  "baseline": {
    "tests": {
      "status": "failing",
      "total": 45,
      "passed": 42,
      "failed": 3
    }
  },
  "canProceed": false,
  "error": "Tests failing before refactoring - fix failures first"
}

Integration with Refactor Agent

Used in refactor workflow Step 1:

### Step 1: Pre-Refactor Validation

Use `record-quality-baseline` skill to capture current state:

Expected output:
- Tests: All passing ✅
- Coverage: 87.5%
- Audit: 7.5/10
- TypeScript: 0 errors

If baseline tests fail:
  ❌ BLOCK refactoring
  → Fix test failures first
  → Re-run baseline

If baseline acceptable:
  ✅ Proceed to Step 2 (Target Analysis)
  → Save baseline for comparison after refactoring

Comparison After Refactoring

After refactoring, compare to baseline:

# Load baseline
BASELINE_SCORE=$(jq -r '.audit.score' .claude/baseline/quality-baseline.json)
BASELINE_COVERAGE=$(jq -r '.coverage.overall' .claude/baseline/quality-baseline.json)

# Get current metrics
CURRENT_SCORE=8.5
CURRENT_COVERAGE=89.2

# Compare
SCORE_DELTA=$(echo "$CURRENT_SCORE - $BASELINE_SCORE" | bc)
COVERAGE_DELTA=$(echo "$CURRENT_COVERAGE - $BASELINE_COVERAGE" | bc)

echo "Quality Improvement:"
echo "  Audit score: $BASELINE_SCORE → $CURRENT_SCORE (${SCORE_DELTA:+}$SCORE_DELTA)"
echo "  Coverage: $BASELINE_COVERAGE% → $CURRENT_COVERAGE% (${COVERAGE_DELTA:+}$COVERAGE_DELTA%)"

Related Skills

• quality-gate - Comprehensive quality validation
• validate-typescript - TypeScript-specific validation
• validate-coverage-threshold - Coverage threshold checking

Baseline Storage

• Location: .claude/baseline/quality-baseline.json
• Git: Should be in .gitignore (temporary)
• Lifetime: Valid for single refactoring session
• Cleanup: Delete after refactoring complete

Best Practices

1. Always record before refactoring - Essential for comparison
2. Block if tests failing - Never refactor broken code
3. Save all outputs - Useful for debugging
4. Validate JSON - Ensure baseline file is valid
5. Compare after changes - Verify improvement
6. Clean up baseline files - Don't commit to repo

Error Handling

Test Command Not Found

if ! npm run test --dry-run &>/dev/null; then
  echo "❌ Error: No test script configured"
  echo "Add test script to package.json"
  exit 1
fi

Coverage Data Missing

if [ ! -f coverage/coverage-summary.json ]; then
  echo "⚠️ Warning: Coverage data not found"
  echo "Ensure tests run with --coverage flag"
  COVERAGE="0"
fi

Notes

• Baseline is essential for safe refactoring
• Tests must pass before refactoring begins
• Audit score should improve or stay same after refactoring
• Coverage should not decrease after refactoring
• TypeScript errors should not increase