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

Metric	Check
Total offenses	current.offenses vs previous.offenses
Convention offenses	current.offenses_by_severity.convention vs previous
Warning offenses	current.offenses_by_severity.warning vs previous
Error offenses	current.offenses_by_severity.error vs previous
Fatal offenses	current.offenses_by_severity.fatal vs previous
Files inspected	current.files_inspected vs previous.files_inspected

Classifications:

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

RSpec Comparison

Metric	Check
Test count	current.examples vs previous.examples
Failures	current.failures vs previous.failures
Pending tests	current.pending vs previous.pending

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:

During GREEN Phase:

• Verify tests exist for new implementation
• Confirm tests are passing
• Measure test coverage increase
• Flag if implementation has no corresponding tests

During REFACTOR Phase:

• Confirm all tests still pass after refactoring
• Verify no test coverage regression
• Compare before/after refactor metrics

Quality Gate:

• No implementation accepted without tests
• Test count should increase with new features
• Test pass rate should remain 100%

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