| name | backend-quality |
| description | Runs backend code quality checks in two tiers: Pint + related tests (every change), Pint + PHPStan + Rector + full suite (completion only). Activate after making changes to PHP files, or when user mentions: pint, phpstan, rector, code quality, static analysis, code style, run checks. |
Backend Code Quality
Run backend quality checks after making changes to PHP files. Which checks to run depends on where you are in the workflow — see the two tiers below.
When to Use This Skill
Activate this skill when:
- PHP files have been created or modified
- Finalizing a feature, bug fix, or refactor that touched PHP code
- The user asks to run backend checks, Pint, or tests
- Before creating a PR with PHP changes
Two Tiers of Checks
Tier 1: During Development (after each change)
Run these checks every time you modify PHP files — they are fast:
1. Pint (Code Style)
vendor/bin/pint --dirty --format agent
Fix any formatting issues. Re-run until clean.
2. Related Tests Only
Run the minimum scope needed:
vendor/bin/phpunit tests/RelevantTest.php
vendor/bin/phpunit --filter=test_method_name
All related tests must pass.
Tier 2: At Completion (once, at the very end)
Run these checks only when the feature, bug fix, or spec is fully implemented — right before creating a PR or marking work as done.
Order matters: Rector → Pint → PHPStan → tests. Each step can surface work the next one relies on.
1. Rector
vendor/bin/rector process
Must report 0 files changed. If Rector modifies files, review the diff, keep the changes, and re-run until clean. Pint may need a follow-up pass after Rector.
2. Pint (after any Rector fixes)
vendor/bin/pint --dirty --format agent
3. PHPStan
vendor/bin/phpstan analyse --memory-limit=2G
Must show 0 errors. Fix real issues — do not pad phpstan-baseline.neon. Only regenerate the baseline after a deliberate strictness ratchet, and have the user confirm.
4. Full Test Suite
vendor/bin/phpunit
Must show 0 failures. This catches cross-cutting regressions.
5. Cross-matrix sanity (when dependencies or version-specific code changed)
The CI matrix runs PHP 8.2/8.3/8.4 × Laravel 12/13 × prefer-lowest/prefer-stable. If your change touched composer.json, version-sensitive API usage, or framework-compat shims, verify both ends of the matrix locally:
composer update --prefer-lowest --prefer-dist --no-interaction
vendor/bin/phpunit
composer update --prefer-stable --prefer-dist --no-interaction
vendor/bin/phpunit
Quick Reference
| Check | Command | When to run | Pass criteria |
|---|
| Code style | vendor/bin/pint --dirty --format agent | Every change | No changes |
| Related tests | vendor/bin/phpunit [--filter] | Every change | 0 failures |
| Rector | vendor/bin/rector process | Completion only | 0 files changed |
| PHPStan | vendor/bin/phpstan analyse --memory-limit=2G | Completion only | 0 errors |
| Full test suite | vendor/bin/phpunit | Completion only | 0 failures |
| Lowest matrix | composer update --prefer-lowest + phpunit | Completion + dep change | 0 failures |
Shortcut: composer qa chains format → rector → phpstan.
Important
- Do NOT run PHPStan, Rector, or the full test suite mid-feature — they are slow and waste time when the code is still in flux.
- When the user explicitly asks to run any of these, always obey regardless of tier.
- Fix PHPStan errors at the source. Do not add
@phpstan-ignore comments, grow phpstan-baseline.neon, or relax phpstan.neon.dist (level, strictRules, type_coverage, cognitive_complexity) to make errors disappear. The only legitimate exception is an upstream bug — confirm with the user before suppressing.
