ci-workflow

name	ci-workflow
description	Run comprehensive CI checks before committing changes. Use when the user asks to run CI, run quality checks, validate code quality, or before finishing any task that involves code changes.

CI Workflow Skill

This skill guides you through running comprehensive CI quality checks before committing code changes.

When to Use This Skill

Activate this skill when:

• User explicitly asks to "run CI" or "run quality checks"
• Before finishing any task that involves code changes
• After making significant code modifications
• Before creating a pull request
• When validating code quality

Workflow Steps

0. Preserve CI entrypoints through the Makefile

When you touch GitHub Actions workflows, call the project through Makefile entrypoints instead of re-encoding raw docker compose or vendor/bin/* commands inside the workflow.

• Prefer make start / make up for service startup
• Prefer make psalm, make deptrac, CI=1 make phpinsights, etc. for quality jobs
• Keep environment-specific command wiring centralized in Makefile

This avoids workflow drift when the Makefile grows prerequisites like phpmd, service setup, or shared CI flags.

1. Run Comprehensive CI Command

Execute the primary CI command that runs all quality checks:

make ci

Expected Outcome: The command MUST output "✅ CI checks successfully passed!" at the end.

2. Monitor CI Execution

The make ci command runs these checks in sequence:

1. Composer validation
2. Security vulnerability analysis
3. Code style fixes (PHP CS Fixer)
4. Static analysis (Psalm)
   • Runs make forbid-static-methods before Psalm to block static method declarations in project PHP files
   • Includes repository source-pattern guardrails for hardcoded new in src/ and native array type declarations in src/
5. Security taint analysis (Psalm)
6. Code quality analysis (PHPInsights)
7. Architecture validation (Deptrac)
8. Unit tests
9. Integration tests
10. End-to-end tests (Behat)
11. Mutation testing (Infection)

3. Handle Failures

If CI fails (output shows "❌ CI checks failed:"):

1. Identify the failing check from the error output

2. Fix the specific issue:

   • Code style: Review PHP CS Fixer suggestions
   • Static analysis: Fix Psalm type errors
   • Quality issues: Address PHPInsights warnings (reduce complexity, fix architecture)
   • Test failures: Debug and fix failing tests
   • Mutation testing: Add missing test cases or refactor for testability

3. Run individual check to verify fix:

   make phpcsfixer    # For code style issues
   make psalm         # For static analysis errors
   make phpinsights   # For quality issues
   make unit-tests    # For unit test failures
   make infection     # For mutation testing issues
   

4. Re-run full CI after fixes:

   make ci
   

4. Iterate Until Success

CRITICAL: Keep fixing issues and re-running make ci until you see:

✅ CI checks successfully passed!

DO NOT finish the task until this success message appears.

5. Quality Standards Protection

NEVER decrease these quality thresholds:

• PHPInsights min-quality: 100% (src/), 95% (tests/)
• PHPInsights min-complexity: 93% (src/), 95% (tests/)
• PHPInsights min-architecture: 100% (src/), 90% (tests/)
• PHPInsights min-style: 100% (src/), 95% (tests/)
• Mutation testing MSI: 100%
• Test coverage: 100%

If quality checks fail, fix the code, don't lower the standards.

Common Issues and Solutions

High Cyclomatic Complexity

Problem: PHPInsights reports complexity score too low Solution:

1. Run make phpmd to identify complex methods
2. Refactor by extracting methods or using strategy pattern
3. Keep methods under 5 complexity score

Escaped Mutants

Problem: Infection finds untested code mutations Solution:

1. Review the mutation diff in infection output
2. Add specific test cases for edge cases
3. Consider refactoring for better testability (injectable time, extracted methods)

Architecture Violations

Problem: Deptrac reports layer violations Solution:

1. Review the dependency rule violation
2. Move code to appropriate layer
3. Follow hexagonal architecture principles

Success Criteria

• Command outputs "✅ CI checks successfully passed!"
• All quality metrics meet or exceed thresholds
• Zero test failures
• Zero escaped mutants
• Zero architecture violations