name	code-compliance
description	Validate code against established best practices during code reviews. Use when checking if code follows team standards, during /4_review workflow, or for pre-commit validation. Triggers include "check code compliance", "validate against best practices", "does this follow our standards", or automatically invoked by /4_review command.

Code Compliance Validator

Overview

This skill ensures code quality by validating implementations against your team's established best practices. It loads best practices documentation, maps changed files to relevant categories, and reports violations with specific references and fix examples.

Purpose: Content Validation Input: .claude/best-practices/ directory (generated by best-practices-extractor skill) Output: Compliance reports with violations and fix suggestions Complements: best-practices-extractor skill (which generates the standards)

When to Use This Skill

Automatic Usage (Recommended)

Automatically invoked by /4_review command
No manual invocation needed
Checks compliance for every code review

Manual Usage

"Check if this code follows our best practices"
"Validate compliance for file X"
"Does this implementation follow our standards?"
Pre-commit validation in CI/CD

How It Works

Step 1: Check for Best Practices

# Manual check
bash scripts/check_compliance.sh [BEST_PRACTICES_DIR] [FILES_TO_CHECK...]

# Examples:
bash scripts/check_compliance.sh .claude/best-practices/
bash scripts/check_compliance.sh .claude/best-practices/ src/api/users.ts src/utils/jwt.ts

Output:

╔════════════════════════════════════════╗
║  Best Practices Compliance Check       ║
╚════════════════════════════════════════╝

📚 Found 5 best practices documents

Available Best Practices Categories:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  • naming-conventions
  • error-handling
  • type-safety
  • testing
  • security

🔍 Files to check: 2

Checking: src/api/users.ts
  → Relevant: naming-conventions, error-handling, security, type-safety

Checking: src/utils/jwt.ts
  → Relevant: error-handling, security, type-safety

Step 2: Load Best Practices

The compliance checker:

Discovers all best practice files
```
ls .claude/best-practices/*.md
```
Reads each category
- naming-conventions.md
- error-handling.md
- type-safety.md
- testing.md
- security.md
- performance.md
- etc.
Parses guidelines
- Extracts each numbered guideline
- Notes rationale and examples
- Prepares for validation

Step 3: File-to-Category Mapping

Intelligent mapping based on file patterns:

File Pattern	Relevant Best Practices
`.ts`, `.tsx`	naming-conventions, error-handling, type-safety, code-organization
`.test.ts`, `.spec.ts`	testing, naming-conventions
`components/*.tsx`	react-patterns, performance, accessibility, naming-conventions
`api/*.ts`	api-design, error-handling, security
`.prisma`, `db/.ts`	database-queries, security

Step 4: Validate Code

For each changed file:

Identify relevant categories (from mapping above)
Load applicable guidelines
Check code against each guideline
Record violations with:
- File and line number
- Guideline reference (document + number)
- Quoted guideline text
- Concrete fix example

Step 5: Generate Report

Compliance report includes:

## Best Practices Compliance

**Overall Compliance**: 85% (17/20 guidelines checked)

### ✅ Compliant Guidelines

- **Naming Conventions** (naming-conventions.md #1-5)
  - All functions use camelCase
  - All interfaces use PascalCase
  - File names match exports

### ❌ Violations

#### High Severity

- **Type Safety Violation** (type-safety.md #3)
  - **File**: src/api/auth.ts:45
  - **Issue**: Using `any` type instead of specific interface
  - **Guideline**: "Avoid using 'any' type. Create specific interfaces."
  - **Fix**: Define AuthRequest interface

  ```typescript
  // Current (violates guideline)
  function authenticate(req: any) { ... }

  // Expected (follows guideline)
  interface AuthRequest {
    email: string;
    password: string;
  }
  function authenticate(req: AuthRequest) { ... }


---

## Integration with /4_review

This skill is **automatically invoked** by the `/4_review` command.

### Workflow

```bash
# 1. Implement feature
/3_implement .claude/tasks/add-user-auth

# 2. Run review (compliance checking happens automatically)
/4_review .claude/tasks/add-user-auth

What happens:

Check for best practices

✅ Best practices found - will validate compliance
📚 Found 5 best practices documents

Load all categories
- Reads all .md files from .claude/best-practices/
Get changed files
```
git diff --name-only main...HEAD
```

Map files to categories

Changed files:
  - src/api/auth.ts → api-design, error-handling, security, type-safety
  - src/utils/jwt.ts → error-handling, security, type-safety
  - tests/auth.test.ts → testing, naming-conventions

Validate and report
- Checks ONLY changed code (not entire codebase)
- Reports violations in review.md
- Includes compliance percentage

Review Scope

CRITICAL: Compliance checking focuses ONLY on code changed in the task.

What Gets Checked

✅ Files in git diff --name-only main...HEAD ✅ Lines modified in the git diff (shown with +/- markers) ✅ New code added in this task

What Gets Ignored

❌ Unchanged lines in modified files ❌ Files not touched by this task ❌ Pre-existing issues in other parts of codebase

Example

Task: "Add user authentication endpoint"

Git Diff Shows:

✅ src/api/auth.ts (new file)
✅ src/middleware/verify-token.ts (lines 15-30 modified)

Compliance Check:

✅ Validates all code in auth.ts
✅ Validates lines 15-30 in verify-token.ts
❌ Ignores lines 1-14, 31+ in verify-token.ts
❌ Ignores other files in src/api/

Prerequisites

Required

Best Practices Must Exist

# Check if best practices exist
ls -la .claude/best-practices/

# Should see:
.claude/best-practices/
├── README.md
├── naming-conventions.md
├── error-handling.md
└── ...

Generate if Missing

# Option 1: Use /best-practices command
/best-practices

# Option 2: Use best-practices-extractor skill
cd skills/best-practices-extractor
bash scripts/incremental_update.sh owner repo

Optional

jq: For JSON processing in scripts
git: For determining changed files

Compliance Report Format

Report Structure

# Code Review

**Date**: 2025-12-28
**Quality**: 8/10
**Best Practices Compliance**: 85% (17/20 guidelines)
**Status**: Warning

## Best Practices Compliance

**Overall Compliance**: 85% (17/20 guidelines checked)

### ✅ Compliant Guidelines

- **Category Name** (filename.md #guideline_numbers)
  - Brief summary of compliance

### ❌ Violations

#### High Severity

- **Category Violation** (filename.md #number)
  - **File**: path/to/file.ts:line
  - **Issue**: Description of violation
  - **Guideline**: "Quoted text from best practices"
  - **Fix**: Concrete code example

  ```typescript
  // Current (violates)
  [actual code]

  // Expected (compliant)
  [corrected code]

Medium Severity

[Similar format]


### Compliance Metrics

- **Percentage**: (Compliant guidelines / Total checked) × 100
- **Counts**: X/Y guidelines followed
- **Severity Levels**:
  - High: Breaks type safety, security, or critical best practices
  - Medium: Code quality, minor best practice violations
  - Low: Style improvements, documentation

---

## Fallback Behavior

### If No Best Practices Exist

⚠️ Best Practices Check Skipped

No best practices found in .claude/best-practices/

To generate best practices:

Run: /best-practices
Or use best-practices-extractor skill

Review will proceed without best practices validation.


**What happens:**
- Review continues normally
- No compliance checking
- Warning shown in report
- Other review steps (linting, security, etc.) still run

---

## Configuration

### Custom Best Practices Location

Modify the compliance checker to use a custom path:

```bash
bash scripts/check_compliance.sh /path/to/custom/best-practices/

Selective Category Checking

Modify /4_review command to check only specific categories:

<categories-to-check>
  - naming-conventions
  - security
  - type-safety
</categories-to-check>

Compliance Thresholds

Set minimum compliance scores in your project:

<compliance-requirements>
  - Minimum overall: 80%
  - Critical guidelines: 100%
  - High severity: 90%
</compliance-requirements>

Troubleshooting

Issue: Best practices not being checked

Check:

# 1. Does directory exist?
ls -la .claude/best-practices/

# 2. Are there .md files?
find .claude/best-practices -name "*.md"

# 3. Run compliance check manually
bash skills/code-compliance/scripts/check_compliance.sh

Solution:

# Generate best practices first
/best-practices

# Or use extractor skill
cd skills/best-practices-extractor
bash scripts/incremental_update.sh owner repo

Issue: Too many false positives

Causes:

Best practices are too strict
Guidelines don't match current patterns
Outdated standards

Solutions:

Refine best practices documents
- Edit .claude/best-practices/*.md
- Add context and exceptions
- Update examples

Update standards

cd skills/best-practices-extractor
bash scripts/incremental_update.sh owner repo
# Re-analyze and regenerate best practices

Add exemptions
- Document known exceptions in guidelines
- Add "When to break this rule" sections

Issue: Missing relevant categories

Solution: Add custom category files to .claude/best-practices/:

# Create new category
touch .claude/best-practices/my-custom-category.md

# Edit and add guidelines
# Compliance checker will automatically discover it

Advanced Usage

Pre-commit Hook Integration

#!/bin/bash
# .git/hooks/pre-commit

# Get staged files
STAGED_FILES=$(git diff --cached --name-only)

# Run compliance check
bash skills/code-compliance/scripts/check_compliance.sh .claude/best-practices/ $STAGED_FILES

# Warn if issues found (don't block commit)

CI/CD Integration

# .github/workflows/compliance.yml
- name: Check Best Practices Compliance
  run: |
    # Get changed files in PR
    FILES=$(git diff --name-only origin/main...HEAD)

    # Run compliance check
    bash skills/code-compliance/scripts/check_compliance.sh .claude/best-practices/ $FILES

Custom Reporting

Extend check_compliance.sh to generate custom reports:

# Add JSON output
--format json

# Add CSV export
--format csv

# Add HTML report
--format html

Integration Guide

For detailed integration instructions, see:

review-integration-guide.md - Comprehensive integration documentation
/4_review command - Automatic compliance checking workflow
code-reviewer agent - Best practices validation instructions

Best Practices for Using This Skill

✅ Do

Keep best practices current - Update regularly with extractor skill
Review generated docs - Validate before enforcing
Be specific - Clear guidelines with examples
Iterate - Refine based on false positives/negatives
Team buy-in - Get team to adopt standards

❌ Don't

Over-engineer - Don't create too many narrow guidelines
Be inflexible - Document exceptions and context
Ignore feedback - Update standards based on team input
Block progress - Use as guidance, not gates
Forget updates - Refresh periodically with new patterns

Quick Reference

# Check compliance manually
bash scripts/check_compliance.sh .claude/best-practices/

# Check specific files
bash scripts/check_compliance.sh .claude/best-practices/ file1.ts file2.ts

# Automatic checking (in /4_review)
/4_review .claude/tasks/my-feature

Related Resources

Integration Guide: review-integration-guide.md
Extractor Skill: Use best-practices-extractor to generate standards
/4_review Command: Automatic compliance validation
code-reviewer Agent: Best practices validation logic

Workflow Summary

┌─────────────────────────────────────────┐
│  1. Generate Best Practices             │
│     (best-practices-extractor skill)    │
│     → Creates .claude/best-practices/   │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  2. Implement Feature                   │
│     /3_implement .claude/tasks/my-task  │
│     → Makes code changes                │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│  3. Validate Compliance                 │
│     /4_review .claude/tasks/my-task     │
│     → Automatically uses THIS skill     │
│     → Checks changed code only          │
│     → Reports violations with fixes     │
└─────────────────────────────────────────┘

Next Steps:

Ensure .claude/best-practices/ exists (use best-practices-extractor if needed)
Run /4_review to automatically validate compliance
Review compliance report and address violations
Iterate on best practices based on feedback

Install Skill

SKILL.md