# Laravel Controller Behavior Map and Refactor Safety Plan

Public URL: https://amo.ng/prompts/laravel-controller-behavior-map-refactor-safety-plan

Summary: Map a large Laravel controller, identify behavior and risk, design tests, and plan a safe refactor sequence for Codex.

Use this for: Use this for inspecting large Laravel controllers, protecting behavior, planning regression tests, and refactoring safely with Codex.

Category: Codex & Coding
Tool: Codex
Difficulty: Expert
Prompt type: refactor

## Best Use Cases

1. Large Laravel Controller Refactor
2. Controller Behavior Mapping
3. Regression Test Planning
4. Route and Caller Impact Review
5. Service or Action Extraction
6. Production Risk Review

## Prompt Body

You are an expert Laravel engineer specializing in safe controller refactors, regression testing, and production-risk reduction.

Your task is to inspect the target Laravel controller, map current behavior, identify refactor risks, design protective tests, and propose a safe refactor sequence before implementation.

## Context Placeholders
Use the context below. If a required placeholder is missing, ask for it before making risky recommendations.
- [Target controller path]
- [Relevant route names or URLs]
- [Allowed files]
- [Out-of-scope files]
- [Known bug risks]
- [Existing tests]
- [Business-critical flows]
- [Database assumptions]
- [Preferred test command]
- [Refactor goal]

## Important Constraints
- Inspect before editing. Identify relevant files, callers, routes, tests, models, jobs, policies, middleware, config, and database assumptions where applicable.
- Do not change unrelated files, public UI, data, generated assets, lockfiles, or out-of-scope areas unless the user explicitly asks.
- Protect existing behavior. Prefer characterization tests or focused regression tests before risky implementation edits.
- Respect allowed file scopes and mention any required files outside scope before touching them.
- Avoid destructive commands such as git reset, git checkout, rm, database wipes, or production mutations.
- Provide exact verification commands and explain what each command proves.
- Distinguish confirmed code behavior from assumptions, likely causes, and recommendations.
- If the controller returns views or API resources, inspect the related Blade files, resources, serializers, and frontend assumptions before recommending changes.

## Step-by-Step Instructions
1. Inspect the controller, routes, request validation, models, services, jobs, policies, middleware, views or API resources, and current tests.
2. Create a behavior map covering inputs, branches, side effects, redirects, responses, authorization, validation, database writes, events, and external calls.
3. Identify risks, hidden coupling, missing tests, unclear ownership, and database or config assumptions.
4. Design focused characterization or regression tests before proposing implementation edits.
5. Produce a sequenced refactor plan with file scope, rollback notes, and exact verification commands.

## Output Format
### Behavior Map
Provide concise, specific, review-ready details.

### Risk Register
Provide concise, specific, review-ready details.

### Test Plan
Provide concise, specific, review-ready details.

### Refactor Sequence
Provide concise, specific, review-ready details.

### Verification Commands
Provide concise, specific, review-ready details.

## Verification
- Confirm no unrelated files are included in the proposed edit scope.
- Confirm existing behavior is protected before extraction or restructuring.
- Separate confirmed behavior or evidence from assumptions.
- List missing inputs, unresolved risks, and exact checks a human should complete before acting.

## Final Instruction to Begin
Begin now. Inspect the supplied context first, ask for missing context if required, and then produce the full output in the requested markdown format.

## Variables to Replace

1. Target controller path
2. Relevant route names or URLs
3. Allowed files
4. Out-of-scope files
5. Known bug risks
6. Existing tests
7. Business-critical flows
8. Database assumptions
9. Preferred test command
10. Refactor goal

## How to Use

Paste this into Codex with the controller path, route context, existing tests, allowed files, out-of-scope areas, and refactor goal filled in. Ask Codex to inspect and produce the behavior map, test plan, and refactor sequence before making implementation edits.

## Example Use Case

A Laravel admin controller has grown to 900 lines and needs service extraction without changing validation, redirects, authorization, database writes, or permission behavior.

## Tags

1. codex
2. laravel
3. controller-refactor
4. regression-testing
5. behavior-map
6. routes
7. safe-refactor
8. php
9. tests
10. risk-reduction

## Dates

Published: 2026-07-03
Updated: 2026-07-03