home / skills / makfly / superpowers-symfony / controller-cleanup

controller-cleanup skill

safe

This skill refactors Symfony controllers with controlled checkpoints, delivering architecture improvements and auditable decisions while minimizing risk.

npx playbooks add skill makfly/superpowers-symfony --skill controller-cleanup

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.1 KB

---

name: symfony:controller-cleanup
allowed-tools:
  - Read
  - Glob
  - Grep
description: Apply production-grade Symfony architecture and execution workflows with controlled scope and clear checkpoints. Use for controller cleanup tasks.
---

# Controller Cleanup (Symfony)

## Use when
- Refining architecture/workflows/context handling in Symfony projects.
- Planning and executing medium/complex changes safely.

## Default workflow
1. Establish current boundaries, constraints, and coupling points.
2. Propose smallest coherent architectural adjustment.
2. Execute in checkpoints with validation at each stage.
2. Summarize tradeoffs and follow-up backlog.

## Guardrails
- Use existing project patterns by default.
- Avoid broad refactors without explicit need.
- Keep decision log clear and auditable.

## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.

## Output contract
- Architecture/workflow changes.
- Checkpoint validation outcomes.
- Residual risks and next steps.

## References
- `reference.md`
- `docs/complexity-tiers.md`

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.

FAQ

How big should each checkpoint be?

Keep checkpoints small and focused: one logical change with full test and smoke validation. This minimizes blast radius and simplifies rollbacks.

What validation is required at each checkpoint?

At minimum run unit tests, relevant integration tests, static analysis (e.g., PHPStan), and a quick smoke test exercising the affected endpoints. Record results in the checkpoint log.