controller-cleanup_skill

Overview

This skill standardizes controller cleanup for Symfony projects, applying production-grade architecture and execution workflows with controlled scope and clear checkpoints. It guides safe, incremental changes to controllers while preserving existing patterns and reducing risk. Use it to produce auditable decisions, validated checkpoints, and a clear follow-up backlog.

How this skill works

The skill inspects controller boundaries, coupling points, and request/response handling to identify the smallest coherent architectural adjustments. It proposes a step-by-step plan, executes changes in checkpoints, runs validation at each stage (tests, smoke checks, static analysis), and records tradeoffs and residual risks. Output includes applied changes, checkpoint results, and a prioritized next-steps backlog.

When to use it

• Refactoring controllers that are too large or tightly coupled to services.
• Introducing consistent request/context handling across controllers.
• Preparing controllers for async processing, API versioning, or middleware extraction.
• Performing medium or complex changes that require staged validation.
• Creating an auditable decision log for architecture changes.

Best practices

• Default to existing project patterns and conventions unless there is a clear benefit to change.
• Limit each checkpoint to a minimal, testable scope to make rollbacks easy.
• Run unit and integration tests plus basic smoke testing after each checkpoint.
• Document decisions, alternatives considered, and the rationale in a clear decision log.
• Avoid broad sweeping refactors—prefer incremental improvements with measurable validation.

Example use cases

• Extracting common request validation and context population into a reusable service or middleware.
• Splitting a monolithic controller action into smaller actions or dedicated services with clear inputs/outputs.
• Migrating controller logic to domain services while preserving routing and API contracts.
• Introducing consistent error handling and response formatting across a controller group.
• Staging a change for async job dispatch while validating sync fallback behavior.