vembed-quality

name	vembed-quality
description	| Use when this capability is needed.

VEmbed Quality Check Skill

Run comprehensive code quality checks for the vembed-factory project using the project's CI/CD pipeline tools.

When to Use This Skill

Use this skill whenever you need to:

• Validate code quality before committing changes
• Check formatting compliance (Black line-length=100)
• Verify import ordering (Isort with Black profile)
• Run linting checks (Ruff for PEP 8 and security)
• Execute unit tests (with optional coverage reports)
• Auto-fix formatting issues
• Prepare for code review or pull requests

Quick Start

The skill runs a series of code quality checks in sequence:

1. Black - Code formatting validation (line-length=100)
2. Isort - Import ordering verification (Black-compatible)
3. Ruff - Linting for PEP 8 and security issues
4. Compilation - Python syntax validation

Then optionally: 5. Pytest - Unit tests with coverage (if --full flag used)

Usage Modes

Quick Check (Recommended for Development)

/vembed-quality

Runs: Black + Isort + Ruff + Compilation checks Perfect for: Before committing code, validating changes locally

Full Check with Tests

/vembed-quality --full

Runs: All basic checks + Unit tests (pytest) Perfect for: Pre-release validation, feature completion

Full Check with Coverage Reports

/vembed-quality --full --coverage

Runs: All checks + Tests + Coverage metrics Perfect for: Release preparation, coverage goals

Auto-Format Code

/vembed-quality --format

Runs: Auto-format with Black + Isort, then validate Perfect for: Fixing formatting issues before commit

What Each Check Does

Tool	Check	Config	Purpose
Black	Code formatting	line-length=100	Ensures consistent code style
Isort	Import ordering	profile=black	Organizes imports correctly
Ruff	Linting	PEP 8 + security	Detects code issues and vulnerabilities
Pytest	Unit tests	(optional)	Verifies functionality with tests

Requirements

• Python: 3.10+
• Virtual Environment: Must be activated (source .venv/bin/activate)
• Tools: Pre-installed in venv (black, isort, ruff)
• Optional: pytest for --full mode

Expected Output

Success

✨ All checks passed!
  ✓ Black formatting
  ✓ Isort import ordering
  ✓ Ruff linting
  ✓ Python compilation

Failure

❌ Black formatting issues detected
  Run: black --line-length=100 <files>

  Error output:
    [specific formatting issues]

Common Workflows

Before Committing Code

# 1. Make your changes
# 2. Activate environment
source .venv/bin/activate

# 3. Run quality checks
/vembed-quality

# 4. If passed, commit
git add .
git commit -m "your message"

# 5. If failed, fix issues and rerun

Fixing Formatting Issues

# 1. Auto-format
/vembed-quality --format

# 2. Verify it worked
/vembed-quality

# 3. Commit the fixes
git add .
git commit -m "style: auto-format code"

Release Checklist

# 1. Full validation with tests
/vembed-quality --full --coverage

# 2. Review coverage report
# (check that coverage meets project standards)

# 3. Fix any remaining issues
# 4. All green? Ready to merge!

Troubleshooting

"Virtual environment not activated"

source .venv/bin/activate
/vembed-quality

"Command not found: black/isort/ruff"

Reinstall tools:

source .venv/bin/activate
pip install -r requirements-dev.txt

"Black formatting issues"

Let the skill auto-format:

/vembed-quality --format

"Ruff linting errors"

Fix high-priority errors first:

1. Read the error output carefully
2. Some errors are auto-fixable: ruff check --fix
3. Others require manual fixes

Test failures (--full mode)

# Run tests directly to debug
source .venv/bin/activate
pytest -v tests/

# Run with coverage
pytest -v --cov=vembed --cov-report=html tests/

Integration with CI/CD

This skill mirrors the GitHub Actions pipeline (.github/workflows/ci.yml), so passing locally guarantees passing in CI. Use before pushing to avoid failed CI checks.

Related Documentation

• Python Coding Standards: .claude/skills/python-coding-standards.md
• CI/CD Configuration: .github/workflows/ci.yml
• CI Quality Report: .claude/CI_QUALITY_REPORT.md
• Usage Guide: .claude/USAGE_GUIDE.md

See Also

• Linting error details: Run ruff check --show-source for line-by-line explanations
• Black formatting guide: black --help for formatting options
• Test execution: pytest -v for verbose test output

---

Source: fangzhensheng/vembed-factory — distributed by TomeVault.