Run Quality Gates

Purpose

Enforce Definition of Done by detecting and running all quality gates (type checking, linting, dead code detection, tests) for Python, JavaScript, Go, Rust, and other ecosystems. Provides actionable feedback for failures and blocks task completion until all gates pass.

Table of Contents

Quick Start → When to Use | What It Does | Simple Example

How to Implement → Detection Process | Execution Workflow | Outcomes

Automation → Scripts | Templates | Supporting Files

Help → Anti-Patterns | Output Format | Integration

Reference → Tool Reference | Common Failures

---

When to Use This Skill

MANDATORY in these situations:

• Before declaring a task "done" or "complete"
• Before marking a todo as completed
• Before creating a commit or pull request
• When user says "check all", "run quality gates", "validate code"
• After implementing new features or bug fixes
• After refactoring code

User trigger phrases:

• "run quality gates"
• "check all"
• "run tests and linting"
• "validate code quality"
• "is this done?"
• "run checks"
• "check before commit"

Additional detection patterns:

• After manually running individual tools (e.g., "I ran ruff check")
• When user says "I fixed linting" but hasn't run other gates
• After code changes but before marking task complete
• When only partial quality checks were performed

What This Skill Does

Enforces the Definition of Done by:

1. Detecting project type (Python, JavaScript, TypeScript, etc.)
2. Identifying quality gate tools (check_all.sh script or individual tools)
3. Running all quality gates in parallel when possible
4. Capturing and categorizing failures (type errors, lint errors, dead code, test failures)
5. Providing actionable fixes for each failure category
6. Re-running gates after fixes until all pass
7. Confirming zero errors before declaring success

Result: ✅ All gates pass (task truly done) or ❌ Failures (with specific fixes needed)

Quick Start

Example 1: Task Completion Check

User: "I'm done implementing the new feature"

Claude invokes skill:
→ Detects Python project with check_all.sh
→ Runs: ./scripts/check_all.sh
→ Reports results

Output:
✅ All 6 checks passed (pyright, vulture, pytest, ruff, ruff format, ty)
✅ DEFINITION OF DONE: MET
Task is complete and ready for commit.

Example 2: Failures Detected

User: "Run quality gates"

Claude invokes skill:
→ Runs quality gates
→ Detects 3 failures

Output:
❌ 3 of 6 checks failed: pyright, pytest, ruff

📋 pyright failures (3 errors):
  src/services/search.py:45 - Type "None" cannot be assigned to "str"
  src/utils/helper.py:12 - Argument of type "int" cannot be assigned to "Optional[str]"

📋 pytest failures (2 errors):
  tests/unit/test_search.py::test_search_empty - AssertionError

📋 ruff failures (1 error):
  src/services/search.py:23 - F401 Unused import: logging

Next steps:
1. Fix type errors (make parameters non-optional)
2. Fix test assertions
3. Remove unused imports
4. Re-run quality gates

❌ DEFINITION OF DONE: NOT MET
Task is NOT complete until all gates pass.

Instructions

Overview

Running quality gates involves 5 key steps:

1. Detect project type and tools - Identify language and available quality gate tools
2. Run quality gates - Execute all gates (unified script or individual tools)
3. Parse results - Categorize failures by type (type errors, lint, tests, dead code)
4. Provide actionable fixes - Generate specific fix recommendations for each failure
5. Re-run after fixes - Validate that all issues are resolved

See detailed workflow in Execution Workflow section below.

Quality Gate Detection

Detection Process

1. Check for unified script (preferred):

   • ./scripts/check_all.sh (Python projects)
   • npm run check (JavaScript/TypeScript projects)
   • make check (Makefile-based projects)

2. Fallback to individual tools by detecting project type:

Python Projects

Detect via: pyproject.toml, requirements.txt, setup.py

Tools to run:

• Type checking: uv run pyright or mypy
• Linting: uv run ruff check or pylint or flake8
• Dead code: uv run vulture src/ --min-confidence 80
• Tests: uv run pytest tests/ -q
• Formatting: uv run ruff format --check or black --check

JavaScript/TypeScript Projects

Detect via: package.json, tsconfig.json

Tools to run:

• Type checking: npx tsc --noEmit
• Linting: npx eslint src/
• Tests: npm test or npx jest or npx vitest
• Formatting: npx prettier --check src/

Go Projects

Detect via: go.mod

Tools to run:

• Type checking: go build ./...
• Linting: golangci-lint run
• Tests: go test ./...
• Formatting: go fmt ./...

Rust Projects

Detect via: Cargo.toml

Tools to run:

• Type checking: cargo check
• Linting: cargo clippy
• Tests: cargo test
• Formatting: cargo fmt --check

Project-Specific Configuration

Read project-specific quality gates from:

• CLAUDE.md (Definition of Done section)
• pyproject.toml (Python)
• package.json (JavaScript/TypeScript)
• .pre-commit-config.yaml (Pre-commit hooks)

Execution Workflow

Step 1: Detect Project and Tools

# Check for unified script
if [ -f ./scripts/check_all.sh ]; then
    RUNNER="./scripts/check_all.sh"
elif [ -f package.json ] && grep -q '"check"' package.json; then
    RUNNER="npm run check"
elif [ -f Makefile ] && grep -q "^check:" Makefile; then
    RUNNER="make check"
else
    # Fallback to individual tools (detect project type)
    ...
fi

Step 2: Run Quality Gates

# Run unified script or individual tools
$RUNNER

# Capture output and exit code
EXIT_CODE=$?

Step 3: Parse and Categorize Failures

Extract failures by tool:

• Type errors: Lines matching error: or error[
• Lint errors: Lines matching .py:line:col: or .js:line:col:
• Dead code: Lines matching unused or dead code
• Test failures: Lines matching FAILED or ERROR collecting

Step 4: Provide Actionable Fixes

For each failure category, provide:

1. File:line reference (exact location)
2. Error description (what's wrong)
3. Suggested fix (how to resolve)
4. Priority (HIGH/MEDIUM/LOW based on error type)

Step 5: Re-run After Fixes

After user applies fixes:

# Re-run quality gates
$RUNNER

# Verify all pass
if [ $? -eq 0 ]; then
    echo "✅ All quality gates passed"
    echo "✅ DEFINITION OF DONE: MET"
else
    echo "❌ Some gates still failing"
    # Repeat steps 3-4
fi

Anti-Pattern Prevention

❌ Anti-Pattern 1: Declaring Done Without Running Gates

User: "I'm done with the feature"

Wrong Response:

✅ Great! The feature is complete.

Correct Response (Invoke Skill):

Let me verify the feature meets Definition of Done by running quality gates...

→ Runs quality gates
→ Reports results (pass/fail)
→ Only declares "done" if all gates pass

❌ Anti-Pattern 2: Ignoring Quality Gate Failures

User: "Some tests are failing but the main logic works"

Wrong Response:

✅ The core functionality is complete. The test failures are minor.

Correct Response:

❌ DEFINITION OF DONE: NOT MET

Quality gates must pass before declaring done:
- 2 tests failing in tests/unit/test_search.py
- 1 type error in src/services/search.py

Let me fix these issues...
[Proceeds to fix each failure]

❌ Anti-Pattern 3: "Will Fix Later" Mentality

User: "Let's commit this and fix the lint errors later"

Wrong Response:

✅ Creating commit...

Correct Response:

❌ Cannot commit - quality gates failing:
- 3 ruff lint errors
- 1 unused import

Project policy: All gates must pass before commit.
Let me fix these now (takes ~30 seconds)...

❌ Anti-Pattern 4: Skipping Tests

User: "I added the feature but didn't write tests yet"

Wrong Response:

✅ Feature added successfully.

Correct Response:

⚠️ DEFINITION OF DONE: INCOMPLETE

Feature implemented but missing:
- Unit tests for new functionality
- Integration tests for end-to-end flow

Project policy: Tests required before declaring done.
Let me add tests now...

❌ Anti-Pattern 5: Partial Quality Check (NEW)

User: "I ran ruff check and fixed all linting errors"

Wrong Response:

✅ Code quality verified - all linting issues resolved.

Correct Response:

⚠️ PARTIAL QUALITY CHECK DETECTED

You ran: ruff check ✅ (linting passed)
Missing: type checking, tests, dead code detection

Running complete quality gate suite...
→ pyright (type checking)
→ pytest (tests)
→ vulture (dead code)
→ ruff format (formatting)

[Runs all gates and reports results]

Detection signals:

• User mentions running only ONE tool (ruff, eslint, tsc, etc.)
• User says "fixed linting" but no mention of tests/types
• Only one command executed (e.g., ruff check --fix)
• No mention of running check_all.sh or equivalent

Why this matters: Linting alone doesn't verify:

• ❌ Type safety (pyright/mypy catch type errors)
• ❌ Correctness (pytest catches logic errors)
• ❌ Unused code (vulture detects dead code)
• ❌ Formatting consistency (ruff format)

Real-world example:

User ran: ruff check --fix
Missed issues:
- 3 type errors in src/layout_io.py (pyright would catch)
- 1 failing test in tests/test_save.py (pytest would catch)
- 2 unused imports (ruff found but user only ran check, not full suite)

Output Format

Success Output

🚦 Quality Check Results
──────────────────────────────────────────────────
✅ pyright [2s]
✅ vulture [1s]
✅ pytest [3s]
✅ ruff [1s]
✅ ruff format [1s]
✅ ty [2s]
──────────────────────────────────────────────────
✅ All 6 checks passed

✅ DEFINITION OF DONE: MET
- All type checks passed
- All linting passed
- All tests passed (100% pass rate)
- No dead code detected
- Code formatting correct

Task is complete and ready for commit.

Failure Output with Fixes

🚦 Quality Check Results
──────────────────────────────────────────────────
❌ pyright [2s]

📋 pyright failures:
  src/services/search.py:45 - error: Type "None" cannot be assigned to type "str"
  src/utils/helper.py:12 - error: Argument of type "int" cannot be assigned to parameter of type "Optional[str]"

❌ pytest [3s]

📋 pytest failures:
  FAILED tests/unit/test_search.py::test_search_empty - AssertionError: Expected [] but got None

❌ ruff [1s]

📋 ruff failures:
  src/services/search.py:23 - F401 [*] `logging` imported but unused

──────────────────────────────────────────────────
❌ 3 of 6 checks failed: pyright, pytest, ruff

❌ DEFINITION OF DONE: NOT MET

Required fixes:
1. Type Errors (HIGH priority):
   - src/services/search.py:45 - Make return type non-optional or handle None case
   - src/utils/helper.py:12 - Convert int to str or change parameter type

2. Test Failures (HIGH priority):
   - tests/unit/test_search.py::test_search_empty - Update assertion to handle None case

3. Lint Errors (MEDIUM priority):
   - src/services/search.py:23 - Remove unused logging import

Next steps:
1. Fix each issue systematically (start with HIGH priority)
2. Re-run quality gates after each fix
3. Repeat until all gates pass

Integration with Existing Tools

With check_all.sh Script

If project has ./scripts/check_all.sh:

# Skill detects script and uses it directly
./scripts/check_all.sh

# Parses output (already formatted for agent consumption)
# Returns structured results

With Pre-Commit Hooks

Skill can be invoked by pre-commit hooks:

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: quality-gates
      name: Run Quality Gates
      entry: claude-skill run-quality-gates
      language: system
      pass_filenames: false

With TodoWrite Tool

Before marking todo as completed:

# ❌ WRONG - Mark completed without validation
TodoWrite([{"content": "Implement search", "status": "completed"}])

# ✅ CORRECT - Validate first
run_quality_gates()  # Invoke skill
if all_gates_pass:
    TodoWrite([{"content": "Implement search", "status": "completed"}])

With Agent Workflows

Agents should invoke this skill before declaring tasks complete:

@implementer completes feature implementation
→ @implementer invokes run-quality-gates skill
→ Skill runs all gates
→ If pass: Mark todo as completed
→ If fail: Fix issues, re-run gates

Configuration

Project-Specific Quality Gates

Projects can define custom quality gates in CLAUDE.md:

## Quality Gates (MANDATORY)

Run before saying "done":

```bash
./scripts/check_all.sh  # Runs all checks in parallel

Individual checks if needed:

uv run pyright          # Type checking
uv run vulture src/     # Dead code detection
uv run pytest tests/    # Test suite
uv run ruff check src/  # Linting

Non-negotiable: Task is NOT done if quality gates fail. Fix or explain why.

Skill will read this section and use the specified commands.

### Custom Tool Detection

For projects with non-standard setups, create `.claude/quality-gates.json`:

```json
{
  "runner": "./custom_check_script.sh",
  "tools": {
    "type_checker": "uv run pyright",
    "linter": "uv run ruff check",
    "dead_code": "uv run vulture src/",
    "tests": "uv run pytest tests/",
    "formatter": "uv run ruff format --check"
  },
  "required": ["type_checker", "linter", "tests"],
  "optional": ["dead_code", "formatter"]
}

Expected Outcomes

Outcome 1: All Gates Pass

✅ All 6 checks passed
✅ DEFINITION OF DONE: MET
Task is complete and ready for commit.

Agent response:

• Marks todo as completed
• Creates commit if requested
• Declares task done

Outcome 2: Some Gates Fail

❌ 3 of 6 checks failed: pyright, pytest, ruff
❌ DEFINITION OF DONE: NOT MET

Agent response:

• Does NOT mark todo as completed
• Provides specific fixes for each failure
• Re-runs gates after fixes
• Repeats until all pass

Outcome 3: Persistent Failures

❌ After 3 fix attempts, 1 gate still failing
❌ Type error may require architectural change

Agent response:

• Escalates to user
• Explains root cause
• Suggests options:
  1. Make architectural change
  2. Update test expectations
  3. Request guidance

Outcome 4: No Quality Gate Tools Found

⚠️ No quality gate tools detected
⚠️ Cannot validate Definition of Done

Agent response:

• Asks user which tools to use
• Suggests standard tools for detected project type
• Offers to create check_all.sh script

Supporting Files

• references/shared-quality-gates.md - Shared quality gates documentation and patterns
• references/quality-gate-tools.md - Complete list of tools by ecosystem
• references/common-failures.md - Common failure patterns and fixes
• references/detection-rules.md - How to detect project type and tools
• templates/check_all_template.sh - Template for creating check_all.sh

Utility Scripts

• Detect Quality Gates Script - Tool detection script

Success Metrics

Metric	Target	Current
Gates run before declaring "done"	100%	TBD
False "done" declarations	0%	TBD
Quality gate pass rate	100%	TBD
Time to run gates	<10s	TBD
Fix accuracy (first attempt)	>80%	TBD

Usage Examples

Example 1: Pre-Commit Quality Check

# User: "I'm done implementing the feature"
# Skill invocation:
Skill(command: "run-quality-gates")

# Output: All gates pass, ready to commit
✅ All 6 checks passed
✅ DEFINITION OF DONE: MET

Example 2: Failed Gates with Fixes

# User: "Run quality gates"
# Skill invocation:
Skill(command: "run-quality-gates")

# Output: 3 failures with specific fixes
❌ 3 of 6 checks failed
Fix pyright errors, pytest failures, ruff violations

Troubleshooting

Issue: Quality gates take too long (>5 minutes)

Solution:

# Use optimized check_all.sh (runs in parallel: 8s vs 31s)
./scripts/check_all.sh

# For incremental changes, run only affected checks
uv run pyright --files-changed
uv run ruff check --diff

Issue: False positives from vulture

Solution:

# Add exclusions to pyproject.toml
[tool.vulture]
exclude = ["tests/", "*.pyi"]
min_confidence = 80

Issue: Tests pass locally but fail in CI

Solution:

# Ensure same environment
uv sync
uv run pytest tests/ -v

# Check for environment-specific issues
# - Database connections
# - File paths
# - Network dependencies

Additional Resources

See Troubleshooting and Usage Examples sections above for comprehensive guidance including:

• Python project with check_all.sh
• JavaScript project with npm scripts
• Go project with Makefile
• Multi-language monorepo
• Project without existing quality gates

Integration Points

With Other Skills

run-quality-gates integrates with:

• git-commit-push - MANDATORY integration before any commit
• code-review - Invoked as Step 7 of code review process
• detect-quality-regressions - Uses quality gate results for regression detection
• capture-quality-baseline - Establishes baseline metrics for comparison

With Agent Workflows

Agents should invoke this skill:

• @implementer - Before marking tasks complete
• @code-review-expert - During pre-commit review
• @debugging-expert - After fixing bugs to verify quality

With TodoWrite Tool

Integration pattern:

# Before marking todo as completed
run_quality_gates()  # Invoke skill
if all_gates_pass:
    TodoWrite([{"content": "Task", "status": "completed"}])
else:
    # Fix issues first
    pass

Expected Benefits

Metric	Without Quality Gates	With Quality Gates	Improvement
Bugs in production	15-20 per release	2-3 per release	85% reduction
Time to fix bugs	2-4 hours	15-30 min	75% faster
Code review time	30-60 min	10-20 min	60% faster
Test coverage	60-70%	85-95%	30% increase
Merge conflicts	5-10 per week	1-2 per week	80% reduction
Rework after review	40-60% of PRs	5-10% of PRs	85% reduction

Requirements

No external dependencies - Skill adapts to whatever tools are already installed in the project.

Minimum requirements:

• Bash shell (for running scripts)
• Read access to project files (for detection)
• Execute permissions on quality gate scripts

Optional:

• CLAUDE.md with Definition of Done section (for custom configuration)
• .claude/quality-gates.json (for explicit tool specification)