Baseline Check Skill

Purpose

This skill maintains code quality throughout development by:

• •Establishing baseline quality metrics before development
• •Detecting regressions after code changes
• •Tracking quality trends over time
• •Providing clear feedback on code health

When to Use

Invoke this skill:

1. •Before starting development work - Establish current baseline
2. •After completing changes - Check for regressions
3. •After GREEN phase - Verify tests exist and pass
4. •After REFACTOR phase - Verify tests still pass after refactoring
5. •Before committing code - Verify quality standards
6. •When explicitly requested - User asks for quality check, baseline, or regression analysis
7. •During code review - Validate changes meet quality bar

How to Execute

Step 1: Run the Baseline Check

Execute the wrapper script (from project root):

./.claude/skills/baseline-check/baseline-check.sh

The script will:

• •Run RuboCop (if available)
• •Run RSpec (if available)
• •Generate a timestamped JSON report
• •Output the filepath to the generated report

Expected output:

Running baseline checks...
✓ RuboCop check completed
✓ RSpec check completed
Baseline saved to: .claude/baseline/main-20251117-084523.json

Error handling:

• •If script fails, report the error to user
• •If tools are unavailable, the JSON will reflect "available": false
• •Empty test suite is acceptable (allows pre-implementation baselines)

Step 2: Read the Results

Parse the generated JSON file to extract metrics:

{
  "timestamp": "2025-11-17T08:45:23Z",
  "branch": "main",
  "commit": "168d4ea",
  "checks": {
    "rubocop": {
      "available": true,
      "status": "passed",
      "files_inspected": 15,
      "offenses": 3,
      "offenses_by_severity": {
        "convention": 2,
        "warning": 1,
        "error": 0,
        "fatal": 0
      },
      "execution_time": 1.45
    },
    "rspec": {
      "available": true,
      "status": "passed",
      "examples": 42,
      "failures": 0,
      "pending": 2,
      "execution_time": 3.21
    }
  },
  "overall_status": "passed",
  "summary": "All checks passed"
}

Step 3: Find Previous Baseline (If Any)

Search for previous baselines on the current branch:

ls -t .claude/baseline/{current-branch}-*.json 2>/dev/null | head -2

This returns the two most recent baseline files (including the one just created).

Scenarios:

• •One file returned: This is the first baseline (nothing to compare)
• •Two files returned: Compare the newest against the previous
• •Zero files returned: This should not happen if Step 1 succeeded

Step 4: Compare Baselines

If a previous baseline exists, compare key metrics:

RuboCop Comparison

Classifications:

• •Improvement: Offenses decreased, files inspected increased
• •Regression: Offenses increased (especially errors/fatals)
• •Stable: No change in offense counts

RSpec Comparison

Classifications:

• •Improvement: More tests, fewer failures, fewer pending
• •Regression: New failures introduced, test count decreased
• •Stable: Metrics unchanged or expected changes (e.g., pending tests fixed)

Step 5: Report Findings

Provide a clear, actionable summary.

Report Format: First Baseline

When no previous baseline exists:

Baseline Quality Check - Initial Assessment
==========================================

Branch: main
Commit: 168d4ea
Timestamp: 2025-11-17T08:45:23Z

RuboCop Analysis:
  Status: passed
  Files Inspected: 15
  Total Offenses: 3
    - Convention: 2
    - Warning: 1
    - Error: 0
    - Fatal: 0

RSpec Analysis:
  Status: passed
  Examples: 42
  Failures: 0
  Pending: 2

Overall Status: PASSED ✓

This is the first baseline for this branch. Future checks will compare against these metrics.

Baseline file: .claude/baseline/main-20251117-084523.json

Report Format: Comparison with Previous Baseline

When comparing against previous baseline:

Baseline Quality Check - Regression Analysis
============================================

Branch: feat/ssh-integration
Commit: abc123d
Timestamp: 2025-11-17T09:15:42Z
Previous: 2025-11-17T08:45:23Z

RuboCop Changes:
  Status: passed → passed
  Files Inspected: 15 → 18 (+3)
  Total Offenses: 3 → 5 (+2) ⚠️ REGRESSION
    - Convention: 2 → 3 (+1)
    - Warning: 1 → 2 (+1)
    - Error: 0 → 0 (stable)
    - Fatal: 0 → 0 (stable)

RSpec Changes:
  Status: passed → passed
  Examples: 42 → 48 (+6) ✓ IMPROVEMENT
  Failures: 0 → 0 (stable)
  Pending: 2 → 1 (-1) ✓ IMPROVEMENT

Overall Status: PASSED (with quality regressions)

FINDINGS:
⚠️  2 new RuboCop offenses introduced
✓  6 new tests added
✓  1 pending test resolved

RECOMMENDATION:
Address the new RuboCop offenses before committing. Run 'bundle exec rubocop' for details.

Baseline file: .claude/baseline/feat-ssh-integration-20251117-091542.json
Previous baseline: .claude/baseline/feat-ssh-integration-20251117-084523.json

Report Format: Critical Regression

When significant regressions occur:

Baseline Quality Check - CRITICAL REGRESSIONS DETECTED
======================================================

Branch: feat/provider-class
Commit: def456e
Timestamp: 2025-11-17T10:30:15Z

⚠️  CRITICAL ISSUES DETECTED ⚠️

RuboCop Changes:
  Status: passed → FAILED ❌
  Total Offenses: 3 → 12 (+9) ❌ CRITICAL REGRESSION
    - Error: 0 → 2 (+2) ❌ NEW ERRORS
    - Fatal: 0 → 1 (+1) ❌ NEW FATAL

RSpec Changes:
  Status: passed → FAILED ❌
  Examples: 42 → 42 (stable)
  Failures: 0 → 3 (+3) ❌ NEW FAILURES

Overall Status: FAILED ❌

CRITICAL FINDINGS:
❌ 1 fatal RuboCop offense (code will not run correctly)
❌ 2 error-level RuboCop offenses (serious code issues)
❌ 3 failing tests (broken functionality)

REQUIRED ACTIONS:
1. Run 'bundle exec rubocop' to see fatal/error details
2. Run 'bundle exec rspec' to see test failures
3. Fix all critical issues before proceeding
4. Re-run baseline check to verify fixes

DO NOT COMMIT until these critical issues are resolved.

Baseline file: .claude/baseline/feat-provider-class-20251117-103015.json

Interpretation Guidelines

Status Indicators

Use these indicators in reports:

• •✓ IMPROVEMENT - Metrics got better
• •⚠️ REGRESSION - Metrics got worse (non-critical)
• •❌ CRITICAL REGRESSION - Serious issues (errors, fatals, test failures)
• •(stable) - No change
• •PASSED - All checks passed
• •FAILED - One or more checks failed

Severity Assessment

Critical (❌):

• •RuboCop fatal offenses
• •RuboCop error offenses
• •RSpec test failures
• •Overall status changed to "failed"

Warning (⚠️):

• •Increased convention offenses
• •Increased warning offenses
• •Decreased test count
• •Increased pending tests

Positive (✓):

• •Decreased offenses
• •Increased test count
• •Decreased pending tests
• •Resolved failures

Recommendations

Based on findings, provide actionable guidance:

No regressions:

• •"Quality baseline looks good. Proceed with confidence."

Minor regressions:

• •"Consider addressing new offenses before committing."
• •"Run 'bundle exec rubocop -a' to auto-fix some issues."

Critical regressions:

• •"DO NOT COMMIT until critical issues are resolved."
• •"Run diagnostic commands to investigate failures."
• •"Re-run baseline check after fixes to verify."

Edge Cases

No Tools Available

If both RuboCop and RSpec are unavailable:

Baseline Quality Check - Tools Not Available
============================================

Neither RuboCop nor RSpec are available in this environment.

To enable quality checks:
1. Run 'bundle install' to install dependencies
2. Ensure RuboCop and RSpec gems are in Gemfile
3. Re-run this baseline check

Baseline file: .claude/baseline/main-20251117-084523.json

Empty Test Suite

If no tests exist yet (pre-implementation):

Baseline Quality Check - Pre-Implementation
===========================================

RuboCop: passed (3 files inspected, 0 offenses)
RSpec: No tests exist yet

This appears to be a pre-implementation baseline. As you add tests,
future checks will track test coverage growth.

Baseline file: .claude/baseline/feat-new-feature-20251117-084523.json

Branch Comparison

If comparing across branches (e.g., feature branch vs main):

Note: Previous baseline is from a different branch or significantly
older commit. Comparison may include expected differences from other work.

TDD Integration

baseline-check plays a critical role in TDD workflow:

After GREEN Phase (before REFACTOR):

• •Verify tests exist for new implementation (test count must increase)
• •Confirm all tests are passing (0 failures required)
• •Measure test coverage increase compared to pre-GREEN baseline
• •Flag if implementation added code without corresponding tests
• •Confirm implementation met minimum requirements (tests green)
• •Establish pre-REFACTOR baseline for comparison

After REFACTOR Phase:

• •Confirm all tests STILL pass after refactoring (no regressions)
• •Verify test count unchanged (refactoring doesn't need new tests)
• •Compare RuboCop metrics (offenses should decrease or stay stable)
• •Verify no test coverage regression from refactoring changes

Quality Gate:

• •No implementation accepted without tests
• •Test count should increase with new features (GREEN phase)
• •Test pass rate must remain 100% (always)
• •REFACTOR cannot introduce test failures or reduce coverage

Best Practices

1. •Run before starting work - Establishes clean baseline
2. •Run after each significant change - Catches issues early
3. •Run after GREEN phase - Verify tests exist and pass
4. •Run after REFACTOR phase - Confirm tests still pass
5. •Don't ignore warnings - Small regressions accumulate
6. •Celebrate improvements - Acknowledge quality improvements
7. •Block on critical issues - Never commit with fatals/errors/failures

Technical Notes

• •Baseline files are timestamped: {branch}-{YYYYMMDD-HHMMSS}.json
• •Files are stored in .claude/baseline/ (gitignored)
• •Script exits 0 even if checks fail (allows baseline capture)
• •Execution times are informational only (don't compare)
• •Branch name is sanitized (slashes replaced with dashes)

Example Workflow

Starting new feature:

1. User: "I want to add SSH support"
2. Claude: Runs baseline-check skill → establishes baseline
3. Claude: Reports current state (e.g., "15 files, 0 offenses, 42 passing tests")
4. Claude: Proceeds with implementation
5. Claude: After implementation, runs baseline-check again
6. Claude: Compares results, reports findings
7. Claude: If regressions, recommends fixes before commit

Output Files

The skill reads but does not create files (wrapper script creates them):

• •Input: .claude/baseline/{branch}-{timestamp}.json
• •Format: See Step 2 for JSON structure

Success Criteria

The skill succeeds when it:

• •Executes the wrapper script without errors
• •Reads and parses the JSON results
• •Compares against previous baseline (if available)
• •Provides clear, actionable report
• •Highlights any regressions prominently
• •Guides next steps based on findings

The skill fails when:

• •Wrapper script cannot be executed
• •JSON file cannot be read or parsed
• •Report is unclear or incomplete