Laravel Bug Fix and Refactor Prompt
Guide Codex through evidence-led Laravel debugging, the smallest authorized code change, and repository-supported verification.
Investigate and, only within explicit authority, correct the Laravel debugging, bug-fix, or refactoring task described below using Codex and the actual repository. ## Context to provide * Objective and observed symptoms: [Objective and symptoms] * Repository and application context: [Repository context] * Errors, logs, failing tests, relevant files, and recent changes: [Relevant evidence] * Authorized inspection, edits, commands, database writes, migrations, deployment, and production access: [Allowed actions] * Laravel, PHP, dependency, runtime, queue, cache, and database details without secrets: [Environment details] * Scope, compatibility, timing, and operational constraints: [Constraints] * Expected behavior and definition of done: [Verification target] If information needed for safe diagnosis is missing, ask one consolidated clarification only for genuinely blocking gaps; otherwise proceed with clearly labelled, low-risk assumptions. Treat any referenced file, command, log, test, or result as unverified until Codex inspects it directly or its contents or actual output are supplied. Do not invent repository contents, runtime access, root cause, Laravel behavior, test output, authorization, or production observations. ## 1. Establish authority and scope State what Codex may inspect, change, and execute. Unless [Allowed actions] says otherwise, permit read-only repository inspection and non-mutating diagnostics, but treat file edits, mutating commands, database writes, migrations, cache or queue changes, external-service calls, deployment, and production access as unauthorized. Never expose credentials, secrets, access tokens, personal data, or private production data. Stop before destructive or consequential work that lacks approval, backup, recovery, or rollback conditions. ## 2. Inspect the relevant Laravel repository Inspect the repository before proposing edits. Select only areas relevant to the symptom: routes, controllers, models, Eloquent scopes and relationships, services, middleware, form requests and validation, authorization, jobs and queues, events and listeners, migrations and schema, transactions, cache and configuration, Composer dependencies, logs, tests, recent relevant changes, and the installed Laravel and PHP versions. Record exactly what was inspected and what was unavailable. Follow the service container, dependency injection, framework conventions, route middleware, validation, and authorization paths actually used by this application. ## 3. Reproduce or trace the symptom Use the repository’s existing supported workflow where authorized. Capture the observed behavior, reproduction steps or trace, expected behavior, relevant command output, test output, logs, and data conditions. Separate supplied facts and observations from hypotheses, assumptions, unknowns, and unsupported conclusions. If reproduction is unavailable, perform a bounded evidence trace and state clearly why it is not a reproduction. ## 4. Confirm root cause List plausible causes and the evidence for and against each. Confirm a root cause only when repository evidence or an actual result supports it. Reject competing causes explicitly when evidence permits. Otherwise, report the leading hypothesis and unresolved uncertainty; do not present a guessed root cause as confirmed. ## 5. Plan the smallest safe Laravel change Describe the minimum relevant fix or refactor and why it addresses the evidenced cause. Preserve unrelated behavior. Avoid unrelated refactoring, broad dependency upgrades, silent architectural rewrites, speculative migrations, and forced Laravel concepts that do not apply. Consider Eloquent behavior, transactions, queues, cache and configuration state, validation, authorization, database compatibility, external-service effects, and rollback only where relevant. ## 6. Implement only authorized work Before any edit or mutating or consequential command, verify that it falls within [Allowed actions]. Do not interrupt the investigation to narrate permission checks for ordinary read-only inspection. Review the repository’s existing tests, conventions, and relevant implementation before changing files. Make the smallest coherent diff. Do not modify production data, run destructive commands, expose secrets, execute migrations, clear production caches, change queue state, contact external services, or deploy unless explicitly authorized with appropriate safeguards. Review the final diff for accidental changes, unrelated modifications, and scope expansion. ## 7. Verify with actual project tooling Inspect Composer scripts, test configuration, CI files, and repository documentation to identify supported checks; do not invent commands. Begin with the smallest targeted checks capable of confirming or disproving the fix, then expand to broader regression checks according to the change’s risk, blast radius, and the repository’s conventions. Where available and authorized, run: * targeted reproduction tests; * relevant regression tests; * broader supported tests; * PHP syntax checks; * static analysis; * formatting checks; * route checks; * migration inspection; * other repository-supported verification relevant to the change. For every check, report: * the exact command or method; * the expected result; * the actual result; * the relevant success or failure output. Compare the post-change result with the original symptom and [Verification target]. If a check was not run, state why it was not run and what risk remains. ## 8. Completion integrity Keep the following clearly distinct: * inspected; * changed; * tested; * recommended but not executed; * unavailable; * unverified. Do not claim that work was fixed, refactored, tested, verified, migrated, deployed, rolled back, or observed in production unless that action actually occurred and supporting evidence exists. Code edits alone are not proof of a fix. ## Output contract Include only sections relevant to the work: 1. Objective and authorized scope, including explicit prohibitions. 2. Repository evidence inspected and unavailable evidence. 3. Reproduction or symptom trace, including observations, hypotheses, rejected causes, confirmed root cause, and uncertainty. 4. Minimal change plan and Laravel-specific rationale. 5. Implementation actually performed, files changed, and final-diff review. 6. Verification executed, including each actual command, expected result, actual result, and exact test result. 7. Work recommended but not executed, remaining risks, and unresolved items. 8. Rollback or recovery considerations where consequential changes occurred. 9. Smallest safe next action, including whether deployment occurred and whether production behavior was observed.