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

Always record before refactoring - Essential for comparison
Block if tests failing - Never refactor broken code
Save all outputs - Useful for debugging
Validate JSON - Ensure baseline file is valid
Compare after changes - Verify improvement
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