Amo.ng curated workflow
Plan and Review a Complex Laravel Feature for Safe Release
Turn an evidence-supported product opportunity into a phased Laravel implementation plan, conditionally review migration safety, and—after separately authorized implementation produces a real change set—review the pull request and prepare a risk-based release gate.
# Plan and Review a Complex Laravel Feature for Safe Release Workflow ID: AMO-W-000010 ## Outcome An approval-ready package for a complex Laravel feature, including the product decision, repository-aware plan, applicable migration controls, pull-request findings, and release verification criteria. Implementation remains a separately authorized phase and is never implied by planning alone. ## Before you begin - Customer feedback, product usage evidence, commercial signals, and delivery constraints - Feature requirements and acceptance criteria - Access to the relevant Laravel repository and repository instructions - Proposed schema or data migrations when applicable, or confirmation that none are required - Explicit implementation authority and, before PR review, the actual change set and test evidence - Deployment, observability, rollback, and CI/CD context ## Step 1 — Make the Evidence-Gated Roadmap Decision **Prompt** Product Feedback Evidence to Roadmap Decision Brief **Instructions** Assess the customer, product, commercial, and delivery evidence to determine whether the feature should proceed to discovery, implementation, experimentation, deferral, or rejection. Define the intended outcome, constraints, decision gates, and evidence gaps. **Input for this step** Provide source-linked feedback, usage data, affected customer segments, expected value, known alternatives, technical constraints, and decision deadlines. Separate observed evidence from assumptions. **Carry forward** Pass the selected direction, scoped outcome, acceptance evidence, constraints, unresolved questions, and approval conditions to the implementation-planning step. **Review note** A product and engineering owner should approve the feature direction and scope before repository-level implementation planning proceeds. **Prompt content** Analyze the supplied product evidence and produce a traceable roadmap decision brief. Claude may synthesize only the materials included in this conversation. It cannot inspect product analytics, ticketing systems, CRM records, roadmaps, contracts, or engineering tools unless their contents are supplied. It must not approve, publish, promise, schedule, or execute a roadmap decision. ## Supplied inputs - Feedback and feature requests: [Feedback and feature requests] - Customer segments and affected users: [Customer segments and affected users] - Support, sales, and customer success signals: [Support, sales, and customer success signals] - Usage or product data: [Usage or product data] - Strategic goals and business impact: [Strategic goals and business impact] - Engineering constraints and dependencies: [Engineering constraints and dependencies] - Decision owner and deadline: [Decision owner and deadline] ## Input requirements Treat these as blocking prerequisites for a final roadmap recommendation: 1. The decision or feature area under consideration. 2. At least one identifiable item of customer, behavioral, support, commercial, or discovery evidence. 3. The affected or hypothesized customer segment. 4. The decision owner or the role authorized to accept the recommendation. If a blocking prerequisite is absent or too ambiguous, ask focused clarification questions and return an intake-gap notice instead of a final recommendation. You may still organize available evidence and identify safe discovery work, but label the decision state as blocked. Useful but non-blocking context includes evidence dates, source identifiers, corpus size, account value, retention relevance, strategic goals, current workarounds, product usage, engineering estimates, dependencies, deadline, and prior decisions. Preserve missing items as unknown rather than estimating them. If inputs conflict, record each conflicting claim, its source, and the decision consequence. Do not silently reconcile disagreement. If the material contains personal data, credentials, confidential contract language, or unnecessary customer identifiers, avoid reproducing them and recommend redaction or restricted review. ## Evidence rules 1. Assign stable identifiers to supplied evidence, problems, themes, options, assumptions, and open questions so conclusions can be traced. 2. Distinguish: - supplied fact or direct observation - verbatim customer statement - stakeholder interpretation - behavioral product evidence - commercial signal - engineering constraint or estimate - assumption - hypothesis - unknown - conflict 3. Never invent quotes, request counts, account values, usage rates, revenue effects, retention effects, dates, estimates, approvals, research findings, or commitments. 4. Do not treat repeated mentions as independent validation when they come from the same account, copied ticket, sales thread, or underlying incident. Identify possible duplication. 5. Do not describe request frequency as representative without a known corpus, time window, and denominator. Use qualitative wording when those are unavailable. 6. Separate the requested solution from the user job, observed pain, workflow consequence, current workaround, and desired outcome. 7. Treat sales urgency, executive sponsorship, competitive claims, and high-value accounts as relevant signals, not proof that a proposed feature is the correct solution. 8. Attribute business impact only when supplied. Otherwise state the impact hypothesis and evidence needed to test it. 9. Use High, Medium, or Low confidence for major conclusions: - High: multiple relevant and reasonably independent sources converge, critical evidence is current enough for the decision, and no material contradiction remains. - Medium: useful evidence exists but has limitations in coverage, independence, recency, or behavioral support. - Low: evidence is sparse, indirect, anecdotal, materially conflicted, or missing on a decision-critical dimension. Explain the basis; do not convert these levels into invented numerical scores. ## Decision workflow ### 1. Frame the decision State the decision question, affected product area, target segment, decision owner, deadline, strategic objective, known constraints, and choices actually available. Mark anything not supplied as unknown. ### 2. Build and normalize the evidence inventory Extract discrete evidence items without changing their meaning. Identify source type, source date if supplied, segment, direct observation, relevance, independence or duplication concern, limitation, and confidence. Preserve exact quotes only when present and clearly mark them as verbatim. ### 3. Map problems separately from solutions For each candidate problem, identify the user job, pain or blocker, context, consequence, affected segment, current workaround, requested solution, supporting evidence identifiers, contradicting evidence, and unanswered questions. Do not promote a requested solution into a validated problem statement. ### 4. Cluster signals without inflating demand Group related evidence into themes. Explain whether each theme represents breadth across accounts or segments, depth within a small number of accounts, behavioral evidence, commercial pressure, support burden, or an internal hypothesis. Note overlap and likely duplicate signals. ### 5. Evaluate evidence sufficiency Assess directness, segment relevance, independence, recency, behavioral corroboration, severity, strategic fit, commercial relevance, and engineering knowledge. Identify which unknowns could change the decision and which are tolerable for the proposed next action. ### 6. Compare viable roadmap options Consider only relevant options from: ship, improve an existing capability, prototype or experiment, conduct discovery, use documentation or onboarding, defer, decline, and monitor. For each option, show expected customer outcome, strategic fit, supporting and contradicting evidence, engineering or dependency status, opportunity cost, maintenance and UX implications, commercial or support effects, risks, reversibility, validation needed, and confidence. A ship recommendation is eligible only when the problem and target segment are sufficiently supported, strategic fit is explicit, feasibility and dependencies have been reviewed by authorized engineering owners, material security, privacy, legal, compliance, contractual, and commercial concerns have appropriate review paths, and a decision owner is identified. If any gate lacks evidence, mark it unverified and recommend the narrower next action justified by the evidence. A discovery or experiment recommendation must name the decision-changing hypotheses, target participants or cohort, method, evidence to collect, completion signal, and decision rule. A defer, decline, or monitor recommendation must include rationale, affected stakeholders, revisit trigger, and the evidence that could reverse the decision. ### 7. Form the recommendation Choose one primary disposition and, when useful, one contingent alternative. Tie the rationale to evidence identifiers. State confidence, assumptions, unresolved conflicts, opportunity cost, required approvals, owner, timing constraint, and next decision point. Do not imply that the recommendation is approved or committed. ### 8. Verify and reconcile Run the acceptance checks below against the drafted brief. For each check, record the expected condition, actual observation from the draft, evidence inspected, and status as Pass, Fail, or Blocked. Revise correctable failures before presenting the final brief. Preserve failures or blocked checks that require new evidence or human judgment. Required checks: - Every material problem, impact, and recommendation claim traces to supplied evidence or is explicitly labeled as an assumption or hypothesis. - Requested solutions remain distinct from validated problems and desired outcomes. - Counts, frequency claims, quotes, dates, segment labels, and commercial impacts match the supplied material. - Duplicate or dependent signals are not counted as independent corroboration. - Supporting evidence, contradicting evidence, and material source conflicts are visible. - Engineering constraints, dependencies, estimates, and unknown feasibility are represented without invented certainty. - Options are compared against consistent decision dimensions and include opportunity cost. - The primary disposition does not exceed the weakest unmet decision-critical gate. - Discovery or experiment plans contain a completion signal and decision rule; defer, decline, and monitor paths contain revisit triggers. - The named owner, deadline, approvals, and customer-facing commitments are supplied or marked unassigned, unknown, or pending review. - No output wording claims approval, validation, measurement, delivery, or customer commitment without corresponding evidence. ## Required output ### 1. Decision frame Provide the decision question, product area, target segment, owner, deadline, strategic objective, constraints, available dispositions, blocking gaps, and current brief status. ### 2. Evidence inventory | Evidence ID | Source Type | Supplied Observation or Claim | Segment | Date or Window | Independence or Duplication | Limitation | Confidence | | --- | --- | --- | --- | --- | --- | --- | --- | Follow with a short source-coverage note stating which relevant systems or records were not supplied and therefore were not inspected. ### 3. Problem-to-request map | Problem ID | User Job and Context | Observed Pain or Consequence | Requested Solution | Current Workaround | Segment | Supporting Evidence IDs | Contradicting Evidence IDs | Status | | --- | --- | --- | --- | --- | --- | --- | --- | --- | Use status values such as validated, partially supported, hypothesized, conflicted, or unknown, with a brief justification. ### 4. Signal clusters and demand quality | Theme ID | Related Evidence IDs | Breadth and Depth | Source Pattern | Severity | Strategic Relevance | Duplication Risk | Key Unknown | | --- | --- | --- | --- | --- | --- | --- | --- | Do not provide an exact frequency unless the supplied corpus and denominator support it. ### 5. Decision-critical evidence assessment | Dimension | Supporting Evidence | Contradicting or Missing Evidence | Decision Consequence | Confidence | | --- | --- | --- | --- | --- | Include problem validity, segment fit, behavioral support, strategic fit, business impact, support burden, commercial relevance, feasibility, dependencies, and risk review where relevant. ### 6. Roadmap option comparison | Option ID | Disposition | Customer Outcome | Supporting and Contradicting Evidence IDs | Strategic Fit | Feasibility Status | Opportunity Cost | Material Risks | Reversibility | Validation or Approval Needed | Confidence | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | Use not evidenced or unknown instead of filling gaps with assumptions. ### 7. Decision-gate register | Gate | Required Evidence or Review | Actual Evidence Available | Status | Owner Role | Consequence if Unmet | | --- | --- | --- | --- | --- | --- | Include problem validation, segment definition, strategic alignment, engineering feasibility and dependencies, material risk reviews, decision authority, and customer-communication review as applicable. ### 8. Recommendation record State: - primary disposition - contingent alternative - rationale linked to evidence identifiers - confidence and its basis - assumptions and unresolved conflicts - expected benefit stated without unsupported quantification - opportunity cost and rejected alternatives - required human approvals - accountable owner or unassigned status - next decision point and timing constraint - whether the recommendation is decision-ready, conditionally ready, or blocked Explicitly state: Recommendation only; not an approval, roadmap commitment, engineering estimate, or customer promise. ### 9. Validation and handoff plan | Action ID | Hypothesis or Question | Method | Target Segment or Cohort | Evidence Needed | Owner Role | Completion Signal | Decision Rule | Handoff Recipient | | --- | --- | --- | --- | --- | --- | --- | --- | --- | Separate proposed work from work already completed. If completion evidence was not supplied, do not mark an action complete. ### 10. Verification and acceptance ledger | Check | Expected Condition | Actual Observation | Evidence Inspected | Status | Reconciliation or Required Action | | --- | --- | --- | --- | --- | --- | After the table, assign both states independently: - Brief quality state: accepted only if all correctable checks pass and every remaining blocked item is explicit. - Decision authorization state: pending unless an authorized human approval is supplied; never infer authorization from the brief quality state. ### 11. Executive decision memo Provide a concise memo covering the customer problem, affected segment, evidence strength, primary disposition, alternatives considered, opportunity cost, unresolved risks, required validation, owner, and next decision point. Preserve uncertainty and avoid unsupported commitments. ### 12. Open issues and human review List missing inputs, assumptions, conflicts, failed or blocked acceptance checks, unassigned owners, and required product, engineering, commercial, customer-success, security, privacy, legal, compliance, or leadership reviews that are relevant to the supplied decision. Do not add irrelevant review categories. Begin by checking the blocking prerequisites. If they are sufficient, produce the complete brief. If not, provide the intake-gap notice, focused clarification questions, and any bounded evidence organization that can be completed safely. ## Step 2 — Create the Repository-Aware Feature Build Plan **Prompt** Codex Evidence-Grounded Long-Horizon Feature Build Planner **Instructions** Inspect the approved scope against the Laravel repository and produce a phased implementation plan covering affected routes, policies, models, queues, interfaces, migrations, compatibility, tests, rollout, and recovery. **Input for this step** Supply the approved roadmap brief, repository access, relevant architecture documentation, coding conventions, current deployment topology, and any protected paths or prohibited actions. **Carry forward** Pass the phased change manifest, applicable migration requirements, compatibility constraints, verification matrix, rollout stages, and rollback paths to any required migration review. Implementation is a separately authorized phase; resume pull-request review only after a real change set and test evidence exist. **Review note** Engineering should approve any consequential architecture, data-model, or rollout decisions before changes are authorized. **Prompt content** Develop an evidence-grounded plan for the following long-horizon feature change. ## Change inputs Feature goal: [Feature goal] Repository context and architecture: [Repository context and architecture] Current and expected behavior: [Current and expected behavior] Scope and non-goals: [Scope and non-goals] Relevant paths: [Relevant paths] Technical constraints: [Technical constraints] Data and migration requirements: [Data and migration requirements] Interface and integration requirements: [Interface and integration requirements] Access and security requirements: [Access and security requirements] Operational requirements: [Operational requirements] Verification commands and environments: [Verification commands and environments] Release and rollback policy: [Release and rollback policy] Definition of done: [Definition of done] Codex authorization mode: [Codex authorization mode] ## Operating boundaries Use the authorization mode to determine what Codex may do: - Plan-only: analyze supplied material without changing files or running commands. - Inspect-and-plan: inspect accessible repository files and read-only project state, then produce the plan. - Execute approved phases: inspect first and modify or run commands only within the explicitly approved phase and accessible environment. Do not assume repository, shell, network, database, CI, deployment, monitoring, or production access. State which capabilities are available and which are unavailable. Never invent file contents, command results, test outcomes, approvals, deployments, or production observations. Require human authorization before destructive migrations, data mutation, credential or permission changes, external side effects, dependency upgrades with broad impact, deployment, rollback, or production operations. Do not expose secrets, tokens, personal data, or sensitive configuration. Stop and request direction if a proposed action could cause irreversible data loss, security exposure, an uncontrolled outage, or work outside the approved scope. ## Input and uncertainty rules Treat the feature goal, observable current behavior, expected behavior, repository or source snapshot, applicable constraints, definition of done, and authorization mode as blocking inputs for an implementation-ready plan. If one is missing or materially conflicting, ask the smallest set of clarifying questions needed for safe progress. You may still provide a bounded preliminary plan, but mark affected decisions as blocked. Treat architecture diagrams, issue history, traffic profiles, incident records, API specifications, schema documentation, deployment runbooks, and monitoring details as useful optional context. Do not infer them as facts when absent. Classify important statements as one of: - Supplied fact: stated in the inputs but not independently confirmed. - Observed: confirmed from an accessible file, symbol, configuration, schema artifact, or command result; cite the path and symbol, line range, command, or artifact. - Assumption: a bounded premise needed to continue; explain its effect and how to validate it. - Hypothesis: a possible explanation or design implication requiring inspection or testing. - Unknown: information not available. - Conflict: incompatible evidence or requirements requiring reconciliation. Prefer repository evidence over convention. If the repository differs from the supplied description, record the discrepancy rather than silently choosing one account. ## Planning workflow ### 1. Establish the evidence baseline - Record the repository revision, branch, working-tree state, environment, accessible tools, and authorization mode when observable. - List supplied artifacts and inspected artifacts separately. - Identify blocking gaps, conflicting requirements, and any uncommitted changes that must not be overwritten. ### 2. Trace current behavior Inspect relevant entry points and follow the behavior through routes or commands, middleware, validation, authorization, controllers or handlers, services, domain logic, persistence, events, queues, caches, templates or clients, integrations, and observability hooks. Cite concrete files and symbols for observed behavior. For Laravel repositories, inspect applicable routes, middleware, Form Requests, policies and gates, controllers, service or action classes, Eloquent models and relationships, casts and scopes, migrations, jobs and listeners, scheduler entries, cache usage, Blade, Livewire or Inertia surfaces, API resources, service providers, configuration, and PHPUnit or Pest tests. Include only components that exist or are supported by evidence. Map callers, callees, state transitions, data ownership, transaction boundaries, synchronous and asynchronous side effects, public contracts, compatibility assumptions, and existing tests. Flag dead paths, duplicated behavior, hidden coupling, and uncertain runtime behavior without presenting them as confirmed defects. ### 3. Analyze change impact and design choices - Compare current and expected behavior using explicit scenarios, actors, permissions, inputs, state transitions, outputs, side effects, and failure responses. - Identify affected API, event, queue, database, UI, cache, configuration, and observability contracts. - Present viable design options where material trade-offs exist. Compare complexity, compatibility, operability, performance, security, reversibility, and testability, then recommend one with evidence and assumptions. - Prefer localized changes. Justify every broad refactor, dependency addition, public contract change, or abstraction. For schema or data changes, assess nullability, defaults, indexes, uniqueness, foreign keys, lock duration, table size, transaction behavior, replication effects, backfill cost, resumability, idempotency, mixed-version compatibility, and downgrade limitations. Use expand-migrate-contract or another justified compatibility strategy when zero-downtime delivery is required. Do not label a migration reversible merely because a down method exists; explain whether rollback would preserve data. For asynchronous or integrated behavior, assess duplicate delivery, ordering, retries, timeouts, idempotency keys, poison messages, partial failure, rate limits, webhook verification, contract versioning, and reconciliation. For access and security, assess authentication, authorization at every entry point, tenant isolation, input validation, mass assignment, injection, CSRF where applicable, sensitive logging, secret handling, file access, and abuse or privilege-escalation paths. ### 4. Build gated implementation phases Create the smallest coherent phases that preserve deployability and existing behavior. Each phase must specify: - Objective and user-visible effect. - Preconditions and required approval. - Exact files and symbols to inspect, add, or modify, with a justification. - Schema, code, configuration, dependency, interface, and observability changes. - Compatibility strategy for old and new application versions. - Tests and commands to run. - Expected observations and evidence to retain. - Failure signals, stop conditions, and recovery action. - Exit gate before the next phase. Separate preparation, compatibility scaffolding, data migration or backfill, behavior activation, cleanup, and contract removal when those operations carry different risks. Use feature flags or staged rollout only when their lifecycle, default state, ownership, monitoring, and removal plan are defined. ### 5. Design verification and acceptance Build a verification matrix covering applicable unit, feature, integration, contract, authorization, migration, regression, concurrency, queue, cache, UI, performance, and security checks. Include negative and boundary cases, not only the happy path. For every check, provide the requirement or risk covered, setup, command or manual procedure, expected observation, actual observation if executed, evidence location, and status. Valid statuses are proposed, unavailable, blocked, failed, passed, and not applicable. Use passed only when the check actually ran successfully and supporting evidence exists. If execution did not occur, actual observation must say not observed. Reconcile verification results against the definition of done. A failing, blocked, unavailable, or contradictory check remains unresolved and must have an owner or decision before acceptance. ### 6. Plan release, monitoring, and recovery Define deployment order, migration timing, worker or scheduler coordination, cache and configuration handling, health checks, canary or staged rollout where justified, relevant metrics and logs, alert thresholds, observation period, and rollback decision authority. Distinguish code rollback, feature disablement, forward fix, schema rollback, and data restoration. Document recovery point limitations, irreversible transformations, backup or restore prerequisites, backfill cancellation behavior, and how partially processed records will be reconciled. ### 7. Execute only when authorized If execution is authorized, work one approved phase at a time. Before each phase, show its scope, commands, side effects, and stop conditions. Preserve unrelated changes. After the phase, report changed files, command results, evidence, deviations, and unresolved issues, then wait for approval when the next phase is consequential. Do not say fixed, tested, verified, approved, deployed, rolled back, or complete unless that action occurred in the accessible environment and evidence is recorded. Keep planned work, inspected findings, executed changes, unavailable checks, and human approvals visibly separate. ## Required deliverable ### A. Capability and Evidence Ledger Provide repository state, authorization mode, available and unavailable capabilities, supplied artifacts, inspected artifacts with citations, assumptions, unknowns, conflicts, and blocking questions. ### B. Current-to-Target Behavior Matrix Use columns for scenario, actor or permission, current behavior and evidence, target behavior, affected contracts, side effects, edge cases, and unresolved questions. ### C. Architecture and Dependency Trace Describe entry points, call paths, state transitions, transaction boundaries, data stores, queues, caches, integrations, user interfaces, and observability. Cite files and symbols for observations. ### D. Design Decision Record For each material decision, provide options considered, evidence, assumptions, trade-offs, recommendation, rejected alternatives, compatibility impact, and approval required. ### E. File and Contract Change Manifest Use columns for phase, path and symbol, change type, intended modification, justification, dependent contracts, compatibility concern, and test coverage. Do not list speculative paths as confirmed files. ### F. Phased Implementation Plan Provide phase objectives, prerequisites, approvals, ordered implementation steps, migration or rollout strategy, verification gate, failure signals, stop conditions, recovery procedure, and handoff state. ### G. Risk and Control Register Use columns for failure mode, trigger or cause, affected users or systems, likelihood, impact, detectability, preventive control, detection signal, mitigation or recovery, owner, phase, and residual risk. Include applicable data-loss, authorization, compatibility, race-condition, migration-lock, queue-duplication, cache-staleness, integration, performance, and deployment risks. ### H. Verification and Acceptance Matrix Use columns for requirement or risk, test level, setup, command or procedure, expected observation, actual observation, evidence, status, and follow-up owner. Clearly separate proposed checks from executed checks. ### I. Release, Monitoring, and Rollback Runbook Specify release sequence, approval points, feature-flag state, migration and backfill coordination, worker handling, health checks, metrics, logs, thresholds, observation window, rollback triggers, recovery path, and irreversible limitations. ### J. Definition-of-Done Reconciliation For each supplied completion criterion, report its evidence, status, unresolved gap, and acceptance authority. End with one handoff state: ready for human review, blocked pending information, ready for an approved implementation phase, or executed with unresolved verification. Do not imply approval or completion from the handoff state alone. ## Step 3 — If Applicable, Review Laravel Migration and Backfill Safety **Prompt** Zero-Downtime Laravel Migration Review **Instructions** When the feature includes schema or data changes, review proposed migrations and backfills for locking risk, rolling-version compatibility, sequencing, pause criteria, reconciliation, and recovery. If no schema or data migration exists, record Not applicable with the reason and continue without inventing migration work. **Input for this step** When applicable, provide migration files or specifications, database engine and version, table sizes and write patterns, deployment sequence, worker behavior, backfill design, and recovery constraints. Otherwise provide confirmation that the change has no schema or data migration. **Carry forward** When applicable, pass required migration revisions, deployment ordering, rehearsal checks, reconciliation queries, stop conditions, and residual risks to implementation and pull-request review. Otherwise pass the recorded Not-applicable decision and continue only when the real change set and test evidence exist. **Review note** When an applicable migration can lock, rewrite, delete, or irreversibly transform production data, a database or production owner should approve it. No migration approval is required when schema and data migration were confirmed Not applicable. **Prompt content** Review the proposed Laravel schema and data migration change set for zero-downtime feasibility and production safety using Codex and the actual repository. Use only repository content, database evidence, command output, and operational facts that are supplied or genuinely accessible in the current Codex workspace. ## Required inputs - Repository and change set: [Repository and change set] - Framework and database versions: [Framework and database versions] - Production schema evidence: [Production schema evidence] - Workload and table evidence: [Workload and table evidence] - Deployment topology and compatibility window: [Deployment topology and compatibility window] - Backfill and recovery constraints: [Backfill and recovery constraints] - Operational limits and approvals: [Operational limits and approvals] - Acceptance evidence: [Acceptance evidence] The repository and change-set input should identify, where relevant: - the exact release, commit, branch, or diff under review; - migration files; - raw SQL; - related models and casts; - accessors and mutators; - validation rules; - services and query builders; - controllers and API resources; - jobs and queue payloads; - events and listeners; - scheduled commands; - factories and seeders; - tests; - feature flags; - application deployment order. Production schema evidence should include, where available: - current columns and data types; - defaults; - nullability; - indexes; - constraints; - foreign keys; - generated columns; - approximate row counts; - duplicate, null, orphan, or invalid-data counts; - relevant database metadata; - observed schema drift. Workload and table evidence should describe, where available: - read and write rates; - transaction duration; - long-running transactions; - high-traffic periods; - table growth; - replica use and acceptable lag; - connection pooling; - lock or statement timeouts; - queue throughput; - scheduled workloads; - disk, transaction-log, or WAL constraints. Deployment topology should identify: - environments; - promotion order; - application instances; - queue workers; - scheduled processes; - deployment strategy; - mixed-version window; - maintenance constraints; - maximum acceptable interruption or degradation. Backfill and recovery constraints should identify: - whether data transformation is required; - acceptable batch and runtime limits; - retry and resume requirements; - backup scope and freshness; - restore evidence; - rollback and roll-forward expectations; - data-loss tolerance. Operational limits and approvals should state: - permitted read-only inspection; - permitted local commands; - whether file edits are permitted; - prohibited actions; - production-access restrictions; - database-owner and release-owner responsibilities; - required human approval gates. Acceptance evidence should define the observable conditions required before: - rehearsal; - schema expansion; - backfill; - read switching; - constraint validation; - contract work; - cleanup; - production completion. ## Zero-downtime standard Do not interpret “zero downtime” as a literal guarantee of zero locks, zero latency change, or zero operational impact. Evaluate zero-downtime feasibility against the supplied service objectives and acceptance constraints, including: - permitted service interruption; - acceptable latency or error-rate change; - write availability; - queue delay; - replica lag; - maintenance allowance; - user-visible degradation; - compatibility requirements. If those thresholds are not supplied, mark zero-downtime feasibility as unverified. Do not invent an acceptable outage or degradation threshold. ## Input and evidence rules 1. Begin with an input-status table. Classify every required input as: - supplied; - observed in the accessible workspace; - missing; - ambiguous; - conflicting; - not applicable. 2. Bind all material evidence to the exact release under review where possible. Record: - commit, revision, or diff; - migration filename and identifier; - database engine and version; - target environment; - schema snapshot date; - workload measurement window; - command or rehearsal timestamp; - artifact or output identity. Evidence from another commit, migration set, database version, schema state, environment, or execution window is not automatically evidence for this release. 3. Cite repository findings using available file paths, line ranges, classes, methods, migration names, or symbols. 4. Cite operational findings by naming the supplied: - schema snapshot; - command output; - metric; - query result; - runbook; - deployment record; - backup record; - rehearsal artifact; - user statement. 5. Label every material statement as one of: - confirmed; - inferred; - assumed; - unknown; - conflicting. Never convert an assumption or generic database practice into a confirmed finding. 6. If migration files are unavailable, stop after listing the exact migrations and related code required. Do not issue a deployment or zero-downtime decision. 7. If the database engine or exact version is missing or conflicting, do not make engine-specific claims about: - locking; - online DDL; - table rewrites; - transactional behavior; - concurrent index creation; - instant or in-place alterations. Request authoritative version output. 8. If table size, write load, production schema, long-running transactions, or deployment topology is unknown, mark lock duration and zero-downtime feasibility unknown. Do not automatically classify the operation as safe or unsafe. 9. Reconcile repository migrations with the actual production schema. Production schema evidence governs operational risk. Repository history remains evidence of intended state. Unexplained schema drift is a release blocker. 10. Distinguish clearly: - requested work; - proposed edits or commands; - executed checks; - supplied execution evidence; - unavailable checks; - unverified results. A command is executed only when Codex actually runs it in an authorized environment and captures its result. Command output supplied by the user is supplied evidence, not independently reproduced evidence. 11. Do not invent: - row counts; - batch sizes; - operation duration; - lock duration; - throughput; - replica lag; - backup validity; - restore success; - database behavior; - test output; - deployment success. 12. When a numerical recommendation cannot be supported, provide a calibration method or bounded range instead of false precision. ## Codex authority boundaries Unless [Operational limits and approvals] explicitly restricts it, permit: - read-only repository inspection; - inspection of supplied schema metadata; - non-mutating local diagnostics; - review of existing test and deployment configuration. Treat the following as unauthorized unless expressly approved: - file edits; - mutating commands; - dependency changes; - database writes; - migrations; - backfills; - destructive SQL; - production queries; - load tests; - cache or queue changes; - deployments; - rollbacks; - external-service changes. Even where local edits are authorized, do not execute: - production migrations; - production backfills; - destructive SQL; - production rollback commands; - deployment; - DNS or infrastructure changes. Production execution, restore decisions, destructive changes, and release approval remain human-controlled actions. Do not expose credentials, connection strings, customer records, personal data, payment data, or confidential production rows. Request redacted schema metadata, aggregate counts, and sanitized samples. If repository edits are separately authorized, make only the smallest reviewable changes required to reduce migration risk. Keep applied changes separate from proposed but unapplied work. ## Focused review workflow ### 1. Establish the release identity and review scope Record: - release or commit identity; - migration files; - related application components; - target database engine and version; - target environment; - deployment strategy; - compatibility window; - maintenance limits; - supplied acceptance criteria. State explicitly what Codex inspected and what remained unavailable. ### 2. Reconcile the migration surface Inventory every `up` and `down` operation and every raw SQL statement. For each operation, identify: - migration file and location; - table or relation; - columns; - data types; - defaults; - nullability; - generated values; - indexes; - uniqueness rules; - foreign keys; - check constraints; - data transformations; - application dependencies. Trace old and new schema names through: - models; - casts; - accessors and mutators; - validation; - services; - queries; - API resources; - events and listeners; - queue payloads; - scheduled work; - reports; - imports and exports; - factories and seeders; - tests. Flag behavior dependent on: - Laravel version; - database driver; - doctrine/dbal; - database-server version; - migration configuration; - transactional DDL support. Do not infer the current production schema solely from migration history. ### 3. Analyze database-engine behavior For MySQL or MariaDB, assess the supplied version and operation against applicable: - instant, in-place, or table-copy behavior; - metadata-lock acquisition; - index-build concurrency; - implicit commits; - foreign-key checks; - generated-column behavior; - default-expression support; - row format; - online-DDL options; - replica effects. Treat `ALGORITHM`, `LOCK`, online DDL, or similar clauses as proposals until their support is validated against the exact engine and version. Identify long transactions that could delay metadata locks. For PostgreSQL, assess: - catalog-only versus table-rewrite behavior; - required lock level and likely duration; - transaction boundaries; - `CREATE INDEX CONCURRENTLY`; - `DROP INDEX CONCURRENTLY`; - invalid indexes after failure; - `NOT VALID` constraints; - later constraint validation; - default-value behavior; - type-change rewrites; - long-running transactions; - dead tuples; - WAL growth; - replica lag. Identify where Laravel migration transaction behavior conflicts with concurrent operations. For another engine, limit conclusions to documented behavior supported by supplied evidence. SQLite development success is not evidence that a MySQL, MariaDB, or PostgreSQL production migration is safe. Do not recommend an external online-schema-change tool unless its suitability, operational ownership, constraints, and approval requirements have been evaluated separately. ### 4. Analyze operation-specific failure modes If this is a prospective review, analyze credible migration failure modes without pretending a failure has already occurred. If an actual migration has failed, reconstruct the failure using supplied evidence and establish root cause only where the causal chain is supported. Check for: - non-null additions before compatible writes and backfill completion; - expensive defaults or table rewrites; - in-place type changes; - truncation; - collation or encoding changes; - lossy casts; - renames or drops while old code still uses the schema; - unique indexes before duplicate and null-semantics checks; - foreign keys before orphan and supporting-index review; - cascade effects; - indexes that do not match observed query predicates or ordering; - blocked writes; - metadata-lock queues; - statement or lock timeouts; - disk or temporary-space pressure; - transaction-log or WAL growth; - replica lag; - failover exposure; - schema and data changes combined into one irreversible unit; - unbounded updates; - offset-based backfills; - mutable pagination keys; - hot-row contention; - retries that duplicate effects; - queue flooding; - `down` methods that destroy data or restore structure without restoring meaning; - migration ordering and timestamp collisions; - environment-dependent migrations; - non-idempotent raw SQL; - mixed-version incompatibility. A migration `down` method is not, by itself, a complete rollback or recovery plan. ### 5. Evaluate mixed-version compatibility Determine whether old and new application versions can coexist with the intermediate schema. Include: - web processes; - API processes; - queue workers; - delayed jobs; - scheduled commands; - reports; - exports; - integrations; - external consumers. Check: - reads from old and new columns; - writes to old and new columns; - dual-write behavior; - default and null handling; - serialized queue payloads; - cache-key or serialization changes; - deployment and worker restart order; - feature-flag ownership and defaults. Do not allow contract work while old application or worker versions may still depend on the old schema. ### 6. Determine the compatible release sequence For every risky change, decide whether it requires: 1. expand; 2. compatibility code; 3. dual write; 4. backfill; 5. reconciliation; 6. read switch; 7. constraint validation; 8. contract; 9. cleanup. For every phase, define: - compatible application versions; - compatible worker versions; - required entry evidence; - proposed action; - monitoring signals; - pause conditions; - acceptance criteria; - recovery path; - approval gate. Use feature flags only where ownership, default state, rollback behavior, and removal criteria are supplied or explicitly proposed. ### 7. Design a controlled backfill Do not place a large backfill inside a schema migration. When a backfill is required, specify: - a versioned Artisan command, controlled job, or reviewed script; - stable keyset batching; - candidate batch-size range; - staging calibration method; - transaction scope; - idempotency predicate or key; - throttling signal; - checkpointing; - progress metrics; - retry behavior; - pause and resume behavior; - failed-record quarantine; - observability; - termination criteria. Base numerical recommendations on supplied measurements. Otherwise mark them for calibration. Define reconciliation using: - candidate count; - processed count; - success count; - skipped count; - failure count; - remaining count; - invariant checks. Unexplained differences must block progression. ### 8. Design rollback and forward recovery Separate: - application rollback; - schema rollback; - backfill pause; - backfill reversal; - data restoration; - forward-compatible recovery. Prefer forward recovery when: - a destructive `down` method would lose data; - old code cannot operate against the new schema; - a partial backfill has changed business meaning; - contract work has already removed compatibility. Identify: - the last reversible phase; - failure indicators; - immediate safe response; - data-loss exposure; - backup dependencies; - restore dependencies; - partial-failure handling; - approval gates; - evidence required before resuming. A backup claim is insufficient without evidence of: - scope; - freshness; - retention; - encryption handling; - access; - restore testing appropriate to the change. ### 9. Define verification and acceptance evidence Propose repository-appropriate checks. Do not imply that SQL generation or `migrate --pretend` proves online execution safety. Where applicable, include: - migration-operation reconciliation; - production-schema reconciliation; - generated-SQL review; - engine-supported DDL validation; - duplicate checks; - orphan checks; - null and range checks; - truncation and cast-failure checks; - representative query plans; - old-version application tests; - mixed-version tests; - new-version tests; - queue-worker compatibility tests; - production-like rehearsal; - lock-wait observations; - blocked-session observations; - disk and temporary-space observations; - transaction-log or WAL growth; - replica-lag observations; - backfill reconciliation; - post-phase schema and data checks; - rollback or forward-recovery rehearsal. For every proposed command or query, state: - purpose; - target environment; - expected observation; - failure meaning; - safety caveat; - work state: proposed, executed, supplied, unavailable, or unverified. Avoid production-wide scans unless an authorized operator confirms: - acceptable execution plan; - timeout; - replica or primary target; - impact window; - cancellation method. ## Risk classification Use only these qualitative states: - Critical — credible risk of data loss, corruption, prolonged outage, irreversible change, uncontrolled production impact, or a release state from which neither old nor new code can recover safely. - High — material lock, availability, compatibility, integrity, backfill, rollback, or recovery risk requiring correction or explicit evidence before progression. - Medium — a meaningful but controllable risk requiring defined safeguards, monitoring, ownership, or a phased release condition. - Low — evidence supports limited blast radius and acceptable behavior within the supplied operational constraints. - Unknown — available evidence is insufficient to classify the risk defensibly. Do not rate a risk Low solely because the migration is small, passes locally, or uses a familiar Laravel schema method. ## Output contract: zero-downtime migration review deliverable Keep the report concise and proportional to the migration scope, risk, and available evidence. Do not repeat the same evidence or limitation across multiple sections. Use operation IDs, finding IDs, and evidence IDs for cross-reference. Where a subsection is genuinely not applicable, retain the heading, state `Not applicable`, and explain briefly why. Never omit: - evidence and coverage; - schema-operation register; - blockers; - compatibility analysis; - recovery; - verification; - release decision. ### A. Review basis and evidence coverage Report: - exact release identity; - target environment; - database engine and version; - migration files and related code inspected; - unavailable materials; - supplied, observed, missing, ambiguous, and conflicting inputs; - zero-downtime acceptance definition; - review limitations. ### B. Schema-operation register For every operation provide: - operation ID; - migration and location; - generated or intended DDL; - affected object; - data touch; - engine and version dependency; - expected lock or rewrite behavior; - rolling-code compatibility; - reversibility; - supporting evidence; - risk state. ### C. Blocking findings and risk register For every material finding provide: - finding ID; - operation or release phase; - failure scenario; - triggering condition; - impact; - risk state; - supporting evidence; - uncertainty; - minimum risk-reducing change; - required owner; - closure evidence. Treat these as blockers until resolved: - unknown engine-specific lock or rewrite behavior for a material operation; - unreconciled production-schema drift; - unbounded backfills; - destructive changes without recovery; - incompatible mixed-version operation; - missing required acceptance evidence. ### D. Compatible phased migration design Provide the ordered release plan. For each phase state: - migration or code change; - compatible application and worker versions; - entry evidence; - proposed action; - monitoring signals; - pause thresholds; - acceptance criteria; - rollback or forward-recovery path; - approval gate. If a single-phase release is sufficient, justify that conclusion using engine-specific, workload, compatibility, and recovery evidence. ### E. Backfill control sheet State: - selection predicate; - stable cursor; - batching method; - calibration method; - idempotency behavior; - transaction boundary; - throttle and pause signals; - retry handling; - checkpoint storage; - progress metrics; - reconciliation equations; - anomaly handling; - completion criteria; - read-switch and contract prerequisites. If no backfill is required, state `Not applicable` and explain why. ### F. Mixed-version compatibility record Report compatibility for: - old application with expanded schema; - new application with intermediate schema; - queue workers and delayed jobs; - scheduled commands; - APIs and integrations; - caches and serialized data; - feature flags; - contract and cleanup timing. Identify the last point at which old code remains safe. ### G. Recovery matrix Cover failure: - before DDL; - during DDL; - after schema expansion; - during backfill; - after read switch; - during contract; - after application rollback. For each case state: - observable symptoms; - immediate safe response; - approval-required action; - data-loss exposure; - recovery evidence; - whether old and new code remain operable. ### H. Verification runbook List commands, SQL, tests, and observations in release order. For each item provide: - check ID; - purpose; - target environment; - command or method; - expected result; - actual supplied or observed result; - evidence; - safety limit; - status: proposed, executed, supplied, unavailable, or unverified; - acceptance result: pass, fail, investigate, or not assessed. Never fabricate command output. ### I. Release decision record Choose exactly one status: - Ready for authorized rehearsal - Ready for authorized phased production rollout - Changes required - Blocked by missing evidence - Unsafe as proposed State: - zero-downtime feasibility; - highest residual risks; - required changes; - unresolved assumptions; - required human approvals; - next evidence-producing action. Do not use “safe to deploy” unless every mandatory acceptance criterion is supported by current, release-bound evidence. ## Final quality gate Before returning the report, verify that: 1. Every migration operation is accounted for. 2. The reviewed evidence is bound to the exact release where possible. 3. Production schema drift is reconciled or explicitly blocking. 4. Database-engine and version dependencies are addressed. 5. Lock, rewrite, index, constraint, and transaction behavior are assessed. 6. Mixed-version application and worker compatibility is evaluated. 7. Backfills are bounded, resumable, idempotent, observable, and reconciled where required. 8. Rollback and forward-recovery paths are distinguished. 9. Proposed commands include expected observations and safety limits. 10. Acceptance criteria reconcile schema, data, application behavior, workers, and operations. 11. Zero-downtime feasibility is tied to supplied service constraints. 12. No execution, verification, approval, deployment, recovery, or completion is claimed without evidence. ## Step 4 — Conduct an Evidence-Grounded Laravel Pull Request Review **Prompt** Evidence-Grounded Laravel Pull Request Review with Codex **Instructions** Begin only after separately authorized implementation has produced a real pull request or change set and test evidence. Review that change against the approved feature scope and applicable migration controls, covering behavior, authorization, tenant isolation, transactions, queues, caches, compatibility, deployment risk, and test coverage. **Input for this step** Provide the actual pull-request diff or change set, linked requirements, implementation plan, applicable migration review or Not-applicable record, real test and CI evidence, and known deviations. Keep merge authority with the designated engineering reviewer. **Carry forward** Pass code-location-specific findings, blocking defects, verification gaps, residual risks, and the evidence-qualified merge recommendation to the production verification step. **Review note** A qualified engineering reviewer should resolve blocking findings and make the merge decision. **Prompt content** Review the supplied Laravel pull request as a bounded, evidence-grounded assessment. Identify defects, security risks, regressions, migration hazards, compatibility problems, and verification gaps without changing the repository or making the merge decision. ## Review inputs - Pull request objective and acceptance criteria: [Pull request objective and acceptance criteria] - Pull request diff or commit range: [Pull request diff or commit range] - Repository context and relevant files: [Repository context and relevant files] - Laravel stack and target environments: [Laravel stack and target environments] - Project conventions and risk constraints: [Project conventions and risk constraints] - Authorized Codex access and execution scope: [Authorized Codex access and execution scope] - Verification commands and supplied evidence: [Verification commands and supplied evidence] - Deployment, migration, and rollback context: [Deployment migration and rollback context] ## Input gate The minimum prerequisites are the pull request objective, acceptance criteria, diff or commit range, Laravel and PHP versions, relevant repository access, and the authorized inspection scope. If the diff, objective, or access boundary is missing or unusable, stop and request it rather than producing a merge assessment. Treat tests, logs, deployment details, schema snapshots, production topology, traffic assumptions, and rollback procedures as optional unless the change affects those areas. When optional context is absent, continue only with a bounded static review, identify the resulting blind spots, and mark affected conclusions as unverified. If inputs conflict, record the conflict and do not silently choose one version. Never infer omitted code, configuration, database state, runtime behavior, or organizational policy. ## Codex access and authority boundaries 1. Inspect only the supplied diff, files, repository content, and artifacts that Codex can actually access. State what was and was not inspected. 2. Default to read-only review. Do not edit files, create commits, push branches, merge or approve the pull request, deploy code, run production migrations, alter data, rotate credentials, contact people, or change external systems. 3. Run commands only when the authorized scope explicitly permits execution and the environment is confirmed non-production. Do not run destructive commands, commands requiring secrets, dependency updates, irreversible migrations, or commands that may affect shared services. Stop and request human authorization if a command could mutate persistent or shared state. 4. Redact secrets, tokens, credentials, personal data, and sensitive tenant data from quotations and command output. Flag exposed secrets without reproducing their values. 5. Recommendations are advisory. A human maintainer retains responsibility for remediation, risk acceptance, merge approval, rollout, and rollback decisions. ## Evidence and claim rules - Separate supplied facts, direct code observations, command execution evidence, assumptions, hypotheses, unknowns, and conflicts. - Support every finding with a file and line, diff hunk, configuration location, schema artifact, log excerpt, or command result. If exact lines are unavailable, cite the nearest symbol or file and say why precision is limited. - Explain the failure mechanism and affected request, job, migration, data path, or deployment phase. Do not report a theoretical pattern as a confirmed defect without showing that the relevant code path is reachable. - Assign confidence as high, medium, or low and explain material uncertainty. Downgrade or omit findings that cannot be connected to the supplied change. - Code inspection is not execution evidence. Supplied historical test output is not evidence that the reviewed commit currently passes unless its commit and environment match. - Use the terms passed, failed, fixed, tested, verified, deployed, approved, or completed only when corresponding actions actually occurred and evidence is available. Otherwise use proposed, not run, unavailable, blocked, or unverified. ## Review workflow ### 1. Establish scope and coverage Summarize the intended behavior, affected entry points, trust boundaries, persistence changes, asynchronous paths, public contracts, and deployment implications. Map changed files to related Laravel components that may need inspection, including routes, middleware, controllers, Form Requests, policies and gates, models, casts, scopes, services, events, listeners, jobs, notifications, API resources, views, configuration, migrations, factories, seeders, and tests. Identify related files that were expected but unavailable. Keep unrelated legacy issues out of scope unless the pull request activates or materially worsens them. ### 2. Trace behavior and framework interactions Trace representative success, validation-failure, authorization-failure, not-found, retry, and exception paths from entry point to side effects. Check Laravel-specific behavior such as route-model binding, middleware order, container bindings, service-provider registration, Eloquent scopes and events, transaction boundaries, exception rendering, configuration caching, and environment-dependent behavior. Compare actual behavior with the stated acceptance criteria. Note backward-compatibility effects on HTTP APIs, console commands, scheduled tasks, events, queue payloads, serialized models, webhooks, and package or PHP requirements. ### 3. Review security and tenant isolation Check authentication and authorization at every protected operation, including policy coverage, ownership checks, tenant scoping, elevated roles, indirect object references, and administrative bypasses. Review validation and normalization, mass assignment, unsafe query construction, output escaping, CSRF exposure, SSRF paths, file uploads, signed URLs, rate limits, secret handling, and sensitive logging where relevant. Treat a plausible cross-tenant access path, authorization bypass, credential disclosure, injection path, or destructive unauthenticated action as blocking unless evidence disproves reachability or impact. ### 4. Review database and rollout safety For schema or data changes, evaluate table locks or rewrites, index creation, foreign keys, defaults, nullability, type narrowing, backfill cost, duplicate or invalid existing data, transaction behavior, and database-engine differences. Determine whether old and new application versions can safely coexist during rolling deployment. Assess expand-and-contract sequencing, read/write compatibility, backfill observability, retry and resume behavior, rollback feasibility, and irreversible data loss. Do not assume a migration down method restores transformed or deleted data. Flag migrations that require production data profiling, maintenance windows, database-specific online DDL, or operator approval. ### 5. Review queues, transactions, caches, and concurrency Where applicable, inspect job serialization, retry policy, idempotency, uniqueness, timeout handling, after-commit dispatch, stale model state, duplicate delivery, dead-letter handling, and side effects. Check race conditions, lost updates, locking, transaction isolation, cache-key scope, invalidation, and tenant leakage. Identify failures that could appear only under retries, concurrent requests, rolling deployment, or partial outages. ### 6. Evaluate tests and verification Map each acceptance criterion and material risk to existing or missing tests. Consider feature, unit, authorization, validation, database, migration, queue, concurrency, contract, and regression coverage as applicable. Check whether assertions prove externally meaningful behavior rather than only status codes or implementation details. If command execution is explicitly authorized, run only the smallest relevant safe commands first. Record the exact command, environment, expected observation, actual observation, exit status, and evidence location. Reconcile failures with the reviewed commit; do not dismiss them as unrelated without evidence. If execution is unavailable or unsafe, provide commands as proposed verification and mark them not run. ### 7. Determine disposition Classify each issue as: - Blocking: credible risk of security breach, cross-tenant exposure, data loss or corruption, production outage, irreversible migration failure, broken acceptance criterion, or incompatible public contract. - Conditional: disposition depends on missing environment, data, traffic, deployment, or policy evidence that must be resolved before merging. - Non-blocking: maintainability, clarity, resilience, or test improvement with no demonstrated merge-stopping impact. Do not inflate severity. State when no blocking issue was found, but never translate that into approval. Base the recommendation on evidence coverage and unresolved blind spots. ## Required deliverable Return Markdown with these sections: # Laravel Pull Request Review ## Scope and Evidence Coverage Include the reviewed objective, diff or commit range, files and components inspected, artifacts unavailable, execution access used, and material assumptions or conflicts. ## Change and Risk Map Provide a table with columns: Area, Changed behavior, Related Laravel components, Trust or data boundary, Deployment concern, Coverage status. ## Findings Register Provide a table with columns: ID, Disposition, Severity, Confidence, Location, Evidence type, Observation, Failure mechanism, Impact, Required remediation, Verification needed. For each blocking or conditional finding, add a short evidence note quoting only the minimum safe excerpt and explain why the issue is reachable. If there are no supported findings in a disposition, write that none were found within inspected scope. ## Migration and Rollout Assessment When relevant, report database engine assumptions, lock or rewrite risk, existing-data prerequisites, old/new version compatibility, expand-and-contract needs, backfill controls, observability, rollback limits, and required operator approval. If not relevant, state why. ## Acceptance and Test Coverage Matrix Provide a table with columns: Acceptance criterion or risk, Existing evidence, Test level, Expected observation, Actual observation, Status, Gap or follow-up. Status must be Passed, Failed, Not run, Blocked, or Unverified and must match the evidence. ## Verification Ledger List each executed or proposed command or manual check with its purpose, target environment, safety prerequisites, expected result, actual result, execution state, and evidence location. Never present proposed commands as executed. ## Merge Guidance and Human Handoff Choose one advisory state: Block pending remediation, Hold pending evidence, or No blocking issue found within reviewed scope. Explain the evidence basis, unresolved unknowns, required owners or approvals, safest next actions, and any rollout or rollback checkpoints. Explicitly state that Codex did not merge, approve, deploy, or modify the pull request. ## Step 5 — Build the Production Verification and Release Gate **Prompt** Production Test and Verification Plan Prompt **Instructions** Convert the approved change package and review findings into a risk-based verification plan covering automated tests, manual checks, CI gates, deployment smoke tests, observability, rollback readiness, and release confidence. **Input for this step** Supply the accepted requirements, final change set, migration controls, pull-request findings, available test evidence, deployment process, monitoring signals, and rollback procedures. **Carry forward** Produce the final release checklist, evidence register, monitoring and rollback triggers, unresolved conditions, and a conditional go, no-go, or defer recommendation for release owners. **Review note** The authorized release owner should make the final deployment decision after reviewing all blockers, unverified checks, and rollback readiness. **Prompt content** Build a risk-based test and verification plan for the following software change or release. Inputs - Change or release under test: [Change or release under test] - Repository and relevant files: [Repository and relevant files] - System and runtime context: [System and runtime context] - Acceptance criteria: [Acceptance criteria] - Test and deployment constraints: [Test and deployment constraints] - Available evidence: [Available evidence] - Authorized actions and environment: [Authorized actions and environment] - CI/CD and rollback context: [CI/CD and rollback context] Codex operating boundaries - Use Codex to inspect supplied repository content, diffs, configuration, test suites, CI definitions, logs, and command output that are actually available in the session. - Run tests or read additional files only when the environment provides that capability and the authorized-actions input permits it. Prefer targeted, read-only inspection before expensive or state-changing commands. - Do not deploy, merge, approve a release, alter production, access undeclared systems, expose secrets, create real customer data, disable safeguards, or run destructive commands. Treat migrations, load tests, security probes, external API calls, and commands that write or delete data as approval-gated. - Stop before an action if its target, blast radius, data handling, cost, reversibility, or authorization is unclear. Record the blocked action, required approval, and a safe alternative. - Never imply that a command ran merely because it was proposed. Never claim that code is fixed, tests passed, coverage improved, a release was approved, a rollback works, or a deployment completed without corresponding execution evidence. Input and evidence rules 1. Treat the change target, acceptance criteria, repository or equivalent technical artifacts, runtime context, and authority scope as prerequisites for an execution-backed assessment. If one is missing, ask only the questions necessary to unblock it. 2. If execution is blocked but supplied artifacts are sufficient, produce a bounded plan and mark execution-dependent conclusions unverified. If the change boundary or acceptance criteria cannot be established, do not issue a release-confidence recommendation. 3. Maintain an evidence ledger that distinguishes supplied facts, direct Codex observations, command execution evidence, assumptions, hypotheses, conflicts, and unknowns. Cite file paths, symbols, diff locations, log excerpts, CI job names, test identifiers, commands, exit codes, or artifact locations where available. 4. Do not resolve conflicting documentation, code behavior, logs, or requirements by guessing. Describe the conflict, its verification impact, and who must resolve it. 5. Do not infer test success from the existence of test files, infer production behavior solely from mocks, or equate code coverage with behavioral correctness. Assessment workflow 1. Establish scope and baseline - Identify changed components, interfaces, dependencies, data stores, feature flags, configuration, infrastructure, schemas, jobs, and user journeys. - Determine the comparison baseline and whether generated files, lockfiles, migrations, API contracts, or deployment manifests changed. - Record exclusions and distinguish intentional scope limits from unavailable evidence. 2. Perform change-impact and risk analysis - Trace affected call paths, consumers, upstream and downstream integrations, shared libraries, background work, cache behavior, concurrency boundaries, and compatibility requirements. - Rate each material risk by likelihood and impact. Include regression, data integrity, authorization, privacy, availability, performance, observability, backward compatibility, migration, retry or idempotency, and rollback risks when relevant. - Prioritize tests by risk reduction rather than test count. 3. Build acceptance traceability - Decompose each acceptance criterion into observable behavior. - Map it to one or more unit, component, integration, contract, end-to-end, migration, security, performance, resilience, or manual checks as appropriate. - Define setup, fixtures or test data, action, expected result, required evidence, cleanup, and ownership for every check. - Include negative paths and boundaries such as empty, null, malformed, duplicate, maximum-size, timeout, partial-failure, retry, race, permission-denied, stale-cache, and dependency-unavailable conditions where applicable. 4. Evaluate existing verification assets - Identify relevant tests and assess whether their assertions prove the required behavior rather than merely execute code. - Detect missing assertions, over-mocking, nondeterministic time or randomness, shared-state leakage, order dependence, brittle snapshots, unsafe fixtures, hidden network access, and flaky retries. - Review CI triggers, path filters, matrices, service dependencies, caches, artifacts, timeouts, required checks, branch protections, and failure propagation for gaps that could produce false confidence. 5. Specify the verification sequence - Order checks from fast and isolated to broad and operational: static checks, targeted unit tests, component or integration tests, contracts, migrations, end-to-end paths, non-functional checks, and manual exploration. - Provide exact commands only when supported by repository evidence. Otherwise label commands as proposed and identify what must be confirmed. - Separate blocking release gates from advisory checks. Define retry policy, flaky-test handling, artifact retention, test-data cleanup, and ownership of failures. 6. Execute only authorized checks - Before each command, state its purpose, environment, expected side effects, and why it is within authority. - Capture the exact command, working directory, relevant environment details with secrets redacted, start and finish state, exit code, actual observation, and artifact reference. - Do not silently rewrite code or tests to make checks pass. If modification is expressly authorized, present the proposed patch and its rationale separately, then verify it with fresh evidence. - Classify each check as passed, failed, blocked, not run, or inconclusive. A zero exit code is not sufficient when assertions, logs, skipped-test counts, or produced artifacts contradict success. 7. Assess deployment and recovery readiness - Verify pre-deployment prerequisites, configuration compatibility, secret references without revealing values, migration ordering, backward and forward compatibility, feature-flag behavior, health checks, and capacity assumptions where relevant. - Define post-deployment smoke tests and observability signals with query or dashboard source, baseline, threshold, observation window, and owner. Cover errors, latency, saturation, queue lag, data reconciliation, and key business behavior as applicable. - Specify rollback or roll-forward triggers, decision owner, procedure reference, data consequences, compatibility limits, recovery verification, and cases where rollback is unsafe, such as irreversible schema or data transformations. 8. Reconcile evidence and determine confidence - Reconcile every acceptance criterion, risk, test result, defect, skipped check, and conflicting observation. - Recommend exactly one state: Ready, Conditionally ready, Not ready, or Unassessed. This is a technical recommendation, not release approval. - Ready requires all blocking criteria to have passing evidence and no unresolved release-blocking defect or unknown. Conditionally ready requires explicit conditions, owners, and deadlines. Not ready requires named blockers. Unassessed applies when evidence is insufficient to support a conclusion. Required deliverable A. Scope and evidence ledger - Change boundary, baseline, affected systems, exclusions, authority scope, and environment. - Evidence table with ID, classification, source or artifact, observation, reliability limitation, and related conclusion. - Assumptions, unknowns, and conflicts, each with impact and resolution owner. B. Change-impact and risk register - Component or behavior, change mechanism, dependent systems, failure mode, likelihood, impact, detectability, risk priority, proposed control, and residual risk. C. Acceptance-to-test matrix - Criterion ID, observable behavior, risk covered, test level, setup and data, procedure or command, expected observation, required evidence, cleanup, owner, priority, and status. D. Existing test and CI assessment - Relevant test or job, what it proves, identified gap, flakiness or isolation concern, CI gate status, and recommended correction. E. Execution record - Check ID, proposed or executed state, exact command or manual procedure, environment, expected observation, actual observation, exit code when applicable, duration when known, evidence reference, and result classification. F. Defect and unresolved-work register - Defect or gap ID, reproduction evidence, affected criterion, severity, release impact, workaround, owner, and retest requirement. Keep proposed fixes separate from applied changes. G. Deployment, observability, and recovery checks - Pre-deployment gates, smoke tests, monitored signals, baselines and thresholds, observation windows, rollback or roll-forward triggers, recovery procedure references, data reconciliation, and responsible approvers. H. Verification verdict - Recommended state, evidence-backed rationale, passed blocking gates, failed or missing gates, residual risks, approval still required, and the smallest safe next action. Use concise technical language. Preserve unresolved states and make every consequential conclusion traceable to evidence. ## Completion criteria The package traces the approved product outcome through implementation scope, any applicable migration safety review, an actual change set, pull-request findings, tests, deployment checks, monitoring, and rollback readiness. Separately authorized implementation, unexecuted work, Not-applicable migration review, unresolved blockers, and unverified checks remain explicit. # Plan and Review a Complex Laravel Feature for Safe Release Use this Amo.ng workflow with your preferred AI tool. Complete the steps in order and carry the specified output forward. Outcome: An approval-ready package for a complex Laravel feature, including the product decision, repository-aware plan, applicable migration controls, pull-request findings, and release verification criteria. Implementation remains a separately authorized phase and is never implied by planning alone. Required inputs: - Customer feedback, product usage evidence, commercial signals, and delivery constraints - Feature requirements and acceptance criteria - Access to the relevant Laravel repository and repository instructions - Proposed schema or data migrations when applicable, or confirmation that none are required - Explicit implementation authority and, before PR review, the actual change set and test evidence - Deployment, observability, rollback, and CI/CD context ## Step 1 — Make the Evidence-Gated Roadmap Decision **Instructions** Assess the customer, product, commercial, and delivery evidence to determine whether the feature should proceed to discovery, implementation, experimentation, deferral, or rejection. Define the intended outcome, constraints, decision gates, and evidence gaps. **Input for this step** Provide source-linked feedback, usage data, affected customer segments, expected value, known alternatives, technical constraints, and decision deadlines. Separate observed evidence from assumptions. **Carry forward** Pass the selected direction, scoped outcome, acceptance evidence, constraints, unresolved questions, and approval conditions to the implementation-planning step. **Review note** A product and engineering owner should approve the feature direction and scope before repository-level implementation planning proceeds. **Prompt** Product Feedback Evidence to Roadmap Decision Brief **Prompt URL** https://amo.ng/prompts/product-feedback-evidence-roadmap-decision-brief ## Step 2 — Create the Repository-Aware Feature Build Plan **Instructions** Inspect the approved scope against the Laravel repository and produce a phased implementation plan covering affected routes, policies, models, queues, interfaces, migrations, compatibility, tests, rollout, and recovery. **Input for this step** Supply the approved roadmap brief, repository access, relevant architecture documentation, coding conventions, current deployment topology, and any protected paths or prohibited actions. **Carry forward** Pass the phased change manifest, applicable migration requirements, compatibility constraints, verification matrix, rollout stages, and rollback paths to any required migration review. Implementation is a separately authorized phase; resume pull-request review only after a real change set and test evidence exist. **Review note** Engineering should approve any consequential architecture, data-model, or rollout decisions before changes are authorized. **Prompt** Codex Evidence-Grounded Long-Horizon Feature Build Planner **Prompt URL** https://amo.ng/prompts/codex-long-horizon-feature-build-planner ## Step 3 — If Applicable, Review Laravel Migration and Backfill Safety **Instructions** When the feature includes schema or data changes, review proposed migrations and backfills for locking risk, rolling-version compatibility, sequencing, pause criteria, reconciliation, and recovery. If no schema or data migration exists, record Not applicable with the reason and continue without inventing migration work. **Input for this step** When applicable, provide migration files or specifications, database engine and version, table sizes and write patterns, deployment sequence, worker behavior, backfill design, and recovery constraints. Otherwise provide confirmation that the change has no schema or data migration. **Carry forward** When applicable, pass required migration revisions, deployment ordering, rehearsal checks, reconciliation queries, stop conditions, and residual risks to implementation and pull-request review. Otherwise pass the recorded Not-applicable decision and continue only when the real change set and test evidence exist. **Review note** When an applicable migration can lock, rewrite, delete, or irreversibly transform production data, a database or production owner should approve it. No migration approval is required when schema and data migration were confirmed Not applicable. **Prompt** Zero-Downtime Laravel Migration Review **Prompt URL** https://amo.ng/prompts/zero-downtime-laravel-migration-review ## Step 4 — Conduct an Evidence-Grounded Laravel Pull Request Review **Instructions** Begin only after separately authorized implementation has produced a real pull request or change set and test evidence. Review that change against the approved feature scope and applicable migration controls, covering behavior, authorization, tenant isolation, transactions, queues, caches, compatibility, deployment risk, and test coverage. **Input for this step** Provide the actual pull-request diff or change set, linked requirements, implementation plan, applicable migration review or Not-applicable record, real test and CI evidence, and known deviations. Keep merge authority with the designated engineering reviewer. **Carry forward** Pass code-location-specific findings, blocking defects, verification gaps, residual risks, and the evidence-qualified merge recommendation to the production verification step. **Review note** A qualified engineering reviewer should resolve blocking findings and make the merge decision. **Prompt** Evidence-Grounded Laravel Pull Request Review with Codex **Prompt URL** https://amo.ng/prompts/safe-thorough-pull-request-review-laravel-codex ## Step 5 — Build the Production Verification and Release Gate **Instructions** Convert the approved change package and review findings into a risk-based verification plan covering automated tests, manual checks, CI gates, deployment smoke tests, observability, rollback readiness, and release confidence. **Input for this step** Supply the accepted requirements, final change set, migration controls, pull-request findings, available test evidence, deployment process, monitoring signals, and rollback procedures. **Carry forward** Produce the final release checklist, evidence register, monitoring and rollback triggers, unresolved conditions, and a conditional go, no-go, or defer recommendation for release owners. **Review note** The authorized release owner should make the final deployment decision after reviewing all blockers, unverified checks, and rollback readiness. **Prompt** Production Test and Verification Plan Prompt **Prompt URL** https://amo.ng/prompts/test-and-verification-prompt Completion criteria: The package traces the approved product outcome through implementation scope, any applicable migration safety review, an actual change set, pull-request findings, tests, deployment checks, monitoring, and rollback readiness. Separately authorized implementation, unexecuted work, Not-applicable migration review, unresolved blockers, and unverified checks remain explicit.Copy workflow includes every step and the full linked Prompt content. Use with AI copies a shorter guide with Prompt links; neither action runs the Workflow.
Outcome
An approval-ready package for a complex Laravel feature, including the product decision, repository-aware plan, applicable migration controls, pull-request findings, and release verification criteria. Implementation remains a separately authorized phase and is never implied by planning alone.
Before you begin
Have all or some of the following available before you start. The more relevant context you can provide, the stronger the workflow output will be.
- Customer feedback, product usage evidence, commercial signals, and delivery constraints
- Feature requirements and acceptance criteria
- Access to the relevant Laravel repository and repository instructions
- Proposed schema or data migrations when applicable, or confirmation that none are required
- Explicit implementation authority and, before PR review, the actual change set and test evidence
- Deployment, observability, rollback, and CI/CD context
Ordered sequence
Workflow steps
Complete the steps in order. For each step, provide the listed context, carry its result into the next step, and pause wherever a review note is shown.
-
Step 1 Make the Evidence-Gated Roadmap Decision
Assess the customer, product, commercial, and delivery evidence to determine whether the feature should proceed to discovery, implementation, experimentation, deferral, or rejection. Define the intended outcome, constraints, decision gates, and evidence gaps.
Prompt: Product Feedback Evidence to Roadmap Decision BriefAnalyze the supplied product evidence and produce a traceable roadmap decision brief. Claude may synthesize only the materials included in this conversation. It cannot inspect product analytics, ticketing systems, CRM records, roadmaps, contracts, or engineering tools unless their contents are supplied. It must not approve, publish, promise, schedule, or execute a roadmap decision. ## Supplied inputs - Feedback and feature requests: [Feedback and feature requests] - Customer segments and affected users: [Customer segments and affected users] - Support, sales, and customer success signals: [Support, sales, and customer success signals] - Usage or product data: [Usage or product data] - Strategic goals and business impact: [Strategic goals and business impact] - Engineering constraints and dependencies: [Engineering constraints and dependencies] - Decision owner and deadline: [Decision owner and deadline] ## Input requirements Treat these as blocking prerequisites for a final roadmap recommendation: 1. The decision or feature area under consideration. 2. At least one identifiable item of customer, behavioral, support, commercial, or discovery evidence. 3. The affected or hypothesized customer segment. 4. The decision owner or the role authorized to accept the recommendation. If a blocking prerequisite is absent or too ambiguous, ask focused clarification questions and return an intake-gap notice instead of a final recommendation. You may still organize available evidence and identify safe discovery work, but label the decision state as blocked. Useful but non-blocking context includes evidence dates, source identifiers, corpus size, account value, retention relevance, strategic goals, current workarounds, product usage, engineering estimates, dependencies, deadline, and prior decisions. Preserve missing items as unknown rather than estimating them. If inputs conflict, record each conflicting claim, its source, and the decision consequence. Do not silently reconcile disagreement. If the material contains personal data, credentials, confidential contract language, or unnecessary customer identifiers, avoid reproducing them and recommend redaction or restricted review. ## Evidence rules 1. Assign stable identifiers to supplied evidence, problems, themes, options, assumptions, and open questions so conclusions can be traced. 2. Distinguish: - supplied fact or direct observation - verbatim customer statement - stakeholder interpretation - behavioral product evidence - commercial signal - engineering constraint or estimate - assumption - hypothesis - unknown - conflict 3. Never invent quotes, request counts, account values, usage rates, revenue effects, retention effects, dates, estimates, approvals, research findings, or commitments. 4. Do not treat repeated mentions as independent validation when they come from the same account, copied ticket, sales thread, or underlying incident. Identify possible duplication. 5. Do not describe request frequency as representative without a known corpus, time window, and denominator. Use qualitative wording when those are unavailable. 6. Separate the requested solution from the user job, observed pain, workflow consequence, current workaround, and desired outcome. 7. Treat sales urgency, executive sponsorship, competitive claims, and high-value accounts as relevant signals, not proof that a proposed feature is the correct solution. 8. Attribute business impact only when supplied. Otherwise state the impact hypothesis and evidence needed to test it. 9. Use High, Medium, or Low confidence for major conclusions: - High: multiple relevant and reasonably independent sources converge, critical evidence is current enough for the decision, and no material contradiction remains. - Medium: useful evidence exists but has limitations in coverage, independence, recency, or behavioral support. - Low: evidence is sparse, indirect, anecdotal, materially conflicted, or missing on a decision-critical dimension. Explain the basis; do not convert these levels into invented numerical scores. ## Decision workflow ### 1. Frame the decision State the decision question, affected product area, target segment, decision owner, deadline, strategic objective, known constraints, and choices actually available. Mark anything not supplied as unknown. ### 2. Build and normalize the evidence inventory Extract discrete evidence items without changing their meaning. Identify source type, source date if supplied, segment, direct observation, relevance, independence or duplication concern, limitation, and confidence. Preserve exact quotes only when present and clearly mark them as verbatim. ### 3. Map problems separately from solutions For each candidate problem, identify the user job, pain or blocker, context, consequence, affected segment, current workaround, requested solution, supporting evidence identifiers, contradicting evidence, and unanswered questions. Do not promote a requested solution into a validated problem statement. ### 4. Cluster signals without inflating demand Group related evidence into themes. Explain whether each theme represents breadth across accounts or segments, depth within a small number of accounts, behavioral evidence, commercial pressure, support burden, or an internal hypothesis. Note overlap and likely duplicate signals. ### 5. Evaluate evidence sufficiency Assess directness, segment relevance, independence, recency, behavioral corroboration, severity, strategic fit, commercial relevance, and engineering knowledge. Identify which unknowns could change the decision and which are tolerable for the proposed next action. ### 6. Compare viable roadmap options Consider only relevant options from: ship, improve an existing capability, prototype or experiment, conduct discovery, use documentation or onboarding, defer, decline, and monitor. For each option, show expected customer outcome, strategic fit, supporting and contradicting evidence, engineering or dependency status, opportunity cost, maintenance and UX implications, commercial or support effects, risks, reversibility, validation needed, and confidence. A ship recommendation is eligible only when the problem and target segment are sufficiently supported, strategic fit is explicit, feasibility and dependencies have been reviewed by authorized engineering owners, material security, privacy, legal, compliance, contractual, and commercial concerns have appropriate review paths, and a decision owner is identified. If any gate lacks evidence, mark it unverified and recommend the narrower next action justified by the evidence. A discovery or experiment recommendation must name the decision-changing hypotheses, target participants or cohort, method, evidence to collect, completion signal, and decision rule. A defer, decline, or monitor recommendation must include rationale, affected stakeholders, revisit trigger, and the evidence that could reverse the decision. ### 7. Form the recommendation Choose one primary disposition and, when useful, one contingent alternative. Tie the rationale to evidence identifiers. State confidence, assumptions, unresolved conflicts, opportunity cost, required approvals, owner, timing constraint, and next decision point. Do not imply that the recommendation is approved or committed. ### 8. Verify and reconcile Run the acceptance checks below against the drafted brief. For each check, record the expected condition, actual observation from the draft, evidence inspected, and status as Pass, Fail, or Blocked. Revise correctable failures before presenting the final brief. Preserve failures or blocked checks that require new evidence or human judgment. Required checks: - Every material problem, impact, and recommendation claim traces to supplied evidence or is explicitly labeled as an assumption or hypothesis. - Requested solutions remain distinct from validated problems and desired outcomes. - Counts, frequency claims, quotes, dates, segment labels, and commercial impacts match the supplied material. - Duplicate or dependent signals are not counted as independent corroboration. - Supporting evidence, contradicting evidence, and material source conflicts are visible. - Engineering constraints, dependencies, estimates, and unknown feasibility are represented without invented certainty. - Options are compared against consistent decision dimensions and include opportunity cost. - The primary disposition does not exceed the weakest unmet decision-critical gate. - Discovery or experiment plans contain a completion signal and decision rule; defer, decline, and monitor paths contain revisit triggers. - The named owner, deadline, approvals, and customer-facing commitments are supplied or marked unassigned, unknown, or pending review. - No output wording claims approval, validation, measurement, delivery, or customer commitment without corresponding evidence. ## Required output ### 1. Decision frame Provide the decision question, product area, target segment, owner, deadline, strategic objective, constraints, available dispositions, blocking gaps, and current brief status. ### 2. Evidence inventory | Evidence ID | Source Type | Supplied Observation or Claim | Segment | Date or Window | Independence or Duplication | Limitation | Confidence | | --- | --- | --- | --- | --- | --- | --- | --- | Follow with a short source-coverage note stating which relevant systems or records were not supplied and therefore were not inspected. ### 3. Problem-to-request map | Problem ID | User Job and Context | Observed Pain or Consequence | Requested Solution | Current Workaround | Segment | Supporting Evidence IDs | Contradicting Evidence IDs | Status | | --- | --- | --- | --- | --- | --- | --- | --- | --- | Use status values such as validated, partially supported, hypothesized, conflicted, or unknown, with a brief justification. ### 4. Signal clusters and demand quality | Theme ID | Related Evidence IDs | Breadth and Depth | Source Pattern | Severity | Strategic Relevance | Duplication Risk | Key Unknown | | --- | --- | --- | --- | --- | --- | --- | --- | Do not provide an exact frequency unless the supplied corpus and denominator support it. ### 5. Decision-critical evidence assessment | Dimension | Supporting Evidence | Contradicting or Missing Evidence | Decision Consequence | Confidence | | --- | --- | --- | --- | --- | Include problem validity, segment fit, behavioral support, strategic fit, business impact, support burden, commercial relevance, feasibility, dependencies, and risk review where relevant. ### 6. Roadmap option comparison | Option ID | Disposition | Customer Outcome | Supporting and Contradicting Evidence IDs | Strategic Fit | Feasibility Status | Opportunity Cost | Material Risks | Reversibility | Validation or Approval Needed | Confidence | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | Use not evidenced or unknown instead of filling gaps with assumptions. ### 7. Decision-gate register | Gate | Required Evidence or Review | Actual Evidence Available | Status | Owner Role | Consequence if Unmet | | --- | --- | --- | --- | --- | --- | Include problem validation, segment definition, strategic alignment, engineering feasibility and dependencies, material risk reviews, decision authority, and customer-communication review as applicable. ### 8. Recommendation record State: - primary disposition - contingent alternative - rationale linked to evidence identifiers - confidence and its basis - assumptions and unresolved conflicts - expected benefit stated without unsupported quantification - opportunity cost and rejected alternatives - required human approvals - accountable owner or unassigned status - next decision point and timing constraint - whether the recommendation is decision-ready, conditionally ready, or blocked Explicitly state: Recommendation only; not an approval, roadmap commitment, engineering estimate, or customer promise. ### 9. Validation and handoff plan | Action ID | Hypothesis or Question | Method | Target Segment or Cohort | Evidence Needed | Owner Role | Completion Signal | Decision Rule | Handoff Recipient | | --- | --- | --- | --- | --- | --- | --- | --- | --- | Separate proposed work from work already completed. If completion evidence was not supplied, do not mark an action complete. ### 10. Verification and acceptance ledger | Check | Expected Condition | Actual Observation | Evidence Inspected | Status | Reconciliation or Required Action | | --- | --- | --- | --- | --- | --- | After the table, assign both states independently: - Brief quality state: accepted only if all correctable checks pass and every remaining blocked item is explicit. - Decision authorization state: pending unless an authorized human approval is supplied; never infer authorization from the brief quality state. ### 11. Executive decision memo Provide a concise memo covering the customer problem, affected segment, evidence strength, primary disposition, alternatives considered, opportunity cost, unresolved risks, required validation, owner, and next decision point. Preserve uncertainty and avoid unsupported commitments. ### 12. Open issues and human review List missing inputs, assumptions, conflicts, failed or blocked acceptance checks, unassigned owners, and required product, engineering, commercial, customer-success, security, privacy, legal, compliance, or leadership reviews that are relevant to the supplied decision. Do not add irrelevant review categories. Begin by checking the blocking prerequisites. If they are sufficient, produce the complete brief. If not, provide the intake-gap notice, focused clarification questions, and any bounded evidence organization that can be completed safely.Input for this step
Provide source-linked feedback, usage data, affected customer segments, expected value, known alternatives, technical constraints, and decision deadlines. Separate observed evidence from assumptions.
Carry forward
Pass the selected direction, scoped outcome, acceptance evidence, constraints, unresolved questions, and approval conditions to the implementation-planning step.
Review note
A product and engineering owner should approve the feature direction and scope before repository-level implementation planning proceeds.
-
Step 2 Create the Repository-Aware Feature Build Plan
Inspect the approved scope against the Laravel repository and produce a phased implementation plan covering affected routes, policies, models, queues, interfaces, migrations, compatibility, tests, rollout, and recovery.
Prompt: Codex Evidence-Grounded Long-Horizon Feature Build PlannerDevelop an evidence-grounded plan for the following long-horizon feature change. ## Change inputs Feature goal: [Feature goal] Repository context and architecture: [Repository context and architecture] Current and expected behavior: [Current and expected behavior] Scope and non-goals: [Scope and non-goals] Relevant paths: [Relevant paths] Technical constraints: [Technical constraints] Data and migration requirements: [Data and migration requirements] Interface and integration requirements: [Interface and integration requirements] Access and security requirements: [Access and security requirements] Operational requirements: [Operational requirements] Verification commands and environments: [Verification commands and environments] Release and rollback policy: [Release and rollback policy] Definition of done: [Definition of done] Codex authorization mode: [Codex authorization mode] ## Operating boundaries Use the authorization mode to determine what Codex may do: - Plan-only: analyze supplied material without changing files or running commands. - Inspect-and-plan: inspect accessible repository files and read-only project state, then produce the plan. - Execute approved phases: inspect first and modify or run commands only within the explicitly approved phase and accessible environment. Do not assume repository, shell, network, database, CI, deployment, monitoring, or production access. State which capabilities are available and which are unavailable. Never invent file contents, command results, test outcomes, approvals, deployments, or production observations. Require human authorization before destructive migrations, data mutation, credential or permission changes, external side effects, dependency upgrades with broad impact, deployment, rollback, or production operations. Do not expose secrets, tokens, personal data, or sensitive configuration. Stop and request direction if a proposed action could cause irreversible data loss, security exposure, an uncontrolled outage, or work outside the approved scope. ## Input and uncertainty rules Treat the feature goal, observable current behavior, expected behavior, repository or source snapshot, applicable constraints, definition of done, and authorization mode as blocking inputs for an implementation-ready plan. If one is missing or materially conflicting, ask the smallest set of clarifying questions needed for safe progress. You may still provide a bounded preliminary plan, but mark affected decisions as blocked. Treat architecture diagrams, issue history, traffic profiles, incident records, API specifications, schema documentation, deployment runbooks, and monitoring details as useful optional context. Do not infer them as facts when absent. Classify important statements as one of: - Supplied fact: stated in the inputs but not independently confirmed. - Observed: confirmed from an accessible file, symbol, configuration, schema artifact, or command result; cite the path and symbol, line range, command, or artifact. - Assumption: a bounded premise needed to continue; explain its effect and how to validate it. - Hypothesis: a possible explanation or design implication requiring inspection or testing. - Unknown: information not available. - Conflict: incompatible evidence or requirements requiring reconciliation. Prefer repository evidence over convention. If the repository differs from the supplied description, record the discrepancy rather than silently choosing one account. ## Planning workflow ### 1. Establish the evidence baseline - Record the repository revision, branch, working-tree state, environment, accessible tools, and authorization mode when observable. - List supplied artifacts and inspected artifacts separately. - Identify blocking gaps, conflicting requirements, and any uncommitted changes that must not be overwritten. ### 2. Trace current behavior Inspect relevant entry points and follow the behavior through routes or commands, middleware, validation, authorization, controllers or handlers, services, domain logic, persistence, events, queues, caches, templates or clients, integrations, and observability hooks. Cite concrete files and symbols for observed behavior. For Laravel repositories, inspect applicable routes, middleware, Form Requests, policies and gates, controllers, service or action classes, Eloquent models and relationships, casts and scopes, migrations, jobs and listeners, scheduler entries, cache usage, Blade, Livewire or Inertia surfaces, API resources, service providers, configuration, and PHPUnit or Pest tests. Include only components that exist or are supported by evidence. Map callers, callees, state transitions, data ownership, transaction boundaries, synchronous and asynchronous side effects, public contracts, compatibility assumptions, and existing tests. Flag dead paths, duplicated behavior, hidden coupling, and uncertain runtime behavior without presenting them as confirmed defects. ### 3. Analyze change impact and design choices - Compare current and expected behavior using explicit scenarios, actors, permissions, inputs, state transitions, outputs, side effects, and failure responses. - Identify affected API, event, queue, database, UI, cache, configuration, and observability contracts. - Present viable design options where material trade-offs exist. Compare complexity, compatibility, operability, performance, security, reversibility, and testability, then recommend one with evidence and assumptions. - Prefer localized changes. Justify every broad refactor, dependency addition, public contract change, or abstraction. For schema or data changes, assess nullability, defaults, indexes, uniqueness, foreign keys, lock duration, table size, transaction behavior, replication effects, backfill cost, resumability, idempotency, mixed-version compatibility, and downgrade limitations. Use expand-migrate-contract or another justified compatibility strategy when zero-downtime delivery is required. Do not label a migration reversible merely because a down method exists; explain whether rollback would preserve data. For asynchronous or integrated behavior, assess duplicate delivery, ordering, retries, timeouts, idempotency keys, poison messages, partial failure, rate limits, webhook verification, contract versioning, and reconciliation. For access and security, assess authentication, authorization at every entry point, tenant isolation, input validation, mass assignment, injection, CSRF where applicable, sensitive logging, secret handling, file access, and abuse or privilege-escalation paths. ### 4. Build gated implementation phases Create the smallest coherent phases that preserve deployability and existing behavior. Each phase must specify: - Objective and user-visible effect. - Preconditions and required approval. - Exact files and symbols to inspect, add, or modify, with a justification. - Schema, code, configuration, dependency, interface, and observability changes. - Compatibility strategy for old and new application versions. - Tests and commands to run. - Expected observations and evidence to retain. - Failure signals, stop conditions, and recovery action. - Exit gate before the next phase. Separate preparation, compatibility scaffolding, data migration or backfill, behavior activation, cleanup, and contract removal when those operations carry different risks. Use feature flags or staged rollout only when their lifecycle, default state, ownership, monitoring, and removal plan are defined. ### 5. Design verification and acceptance Build a verification matrix covering applicable unit, feature, integration, contract, authorization, migration, regression, concurrency, queue, cache, UI, performance, and security checks. Include negative and boundary cases, not only the happy path. For every check, provide the requirement or risk covered, setup, command or manual procedure, expected observation, actual observation if executed, evidence location, and status. Valid statuses are proposed, unavailable, blocked, failed, passed, and not applicable. Use passed only when the check actually ran successfully and supporting evidence exists. If execution did not occur, actual observation must say not observed. Reconcile verification results against the definition of done. A failing, blocked, unavailable, or contradictory check remains unresolved and must have an owner or decision before acceptance. ### 6. Plan release, monitoring, and recovery Define deployment order, migration timing, worker or scheduler coordination, cache and configuration handling, health checks, canary or staged rollout where justified, relevant metrics and logs, alert thresholds, observation period, and rollback decision authority. Distinguish code rollback, feature disablement, forward fix, schema rollback, and data restoration. Document recovery point limitations, irreversible transformations, backup or restore prerequisites, backfill cancellation behavior, and how partially processed records will be reconciled. ### 7. Execute only when authorized If execution is authorized, work one approved phase at a time. Before each phase, show its scope, commands, side effects, and stop conditions. Preserve unrelated changes. After the phase, report changed files, command results, evidence, deviations, and unresolved issues, then wait for approval when the next phase is consequential. Do not say fixed, tested, verified, approved, deployed, rolled back, or complete unless that action occurred in the accessible environment and evidence is recorded. Keep planned work, inspected findings, executed changes, unavailable checks, and human approvals visibly separate. ## Required deliverable ### A. Capability and Evidence Ledger Provide repository state, authorization mode, available and unavailable capabilities, supplied artifacts, inspected artifacts with citations, assumptions, unknowns, conflicts, and blocking questions. ### B. Current-to-Target Behavior Matrix Use columns for scenario, actor or permission, current behavior and evidence, target behavior, affected contracts, side effects, edge cases, and unresolved questions. ### C. Architecture and Dependency Trace Describe entry points, call paths, state transitions, transaction boundaries, data stores, queues, caches, integrations, user interfaces, and observability. Cite files and symbols for observations. ### D. Design Decision Record For each material decision, provide options considered, evidence, assumptions, trade-offs, recommendation, rejected alternatives, compatibility impact, and approval required. ### E. File and Contract Change Manifest Use columns for phase, path and symbol, change type, intended modification, justification, dependent contracts, compatibility concern, and test coverage. Do not list speculative paths as confirmed files. ### F. Phased Implementation Plan Provide phase objectives, prerequisites, approvals, ordered implementation steps, migration or rollout strategy, verification gate, failure signals, stop conditions, recovery procedure, and handoff state. ### G. Risk and Control Register Use columns for failure mode, trigger or cause, affected users or systems, likelihood, impact, detectability, preventive control, detection signal, mitigation or recovery, owner, phase, and residual risk. Include applicable data-loss, authorization, compatibility, race-condition, migration-lock, queue-duplication, cache-staleness, integration, performance, and deployment risks. ### H. Verification and Acceptance Matrix Use columns for requirement or risk, test level, setup, command or procedure, expected observation, actual observation, evidence, status, and follow-up owner. Clearly separate proposed checks from executed checks. ### I. Release, Monitoring, and Rollback Runbook Specify release sequence, approval points, feature-flag state, migration and backfill coordination, worker handling, health checks, metrics, logs, thresholds, observation window, rollback triggers, recovery path, and irreversible limitations. ### J. Definition-of-Done Reconciliation For each supplied completion criterion, report its evidence, status, unresolved gap, and acceptance authority. End with one handoff state: ready for human review, blocked pending information, ready for an approved implementation phase, or executed with unresolved verification. Do not imply approval or completion from the handoff state alone.Input for this step
Supply the approved roadmap brief, repository access, relevant architecture documentation, coding conventions, current deployment topology, and any protected paths or prohibited actions.
Carry forward
Pass the phased change manifest, applicable migration requirements, compatibility constraints, verification matrix, rollout stages, and rollback paths to any required migration review. Implementation is a separately authorized phase; resume pull-request review only after a real change set and test evidence exist.
Review note
Engineering should approve any consequential architecture, data-model, or rollout decisions before changes are authorized.
-
Step 3 If Applicable, Review Laravel Migration and Backfill Safety
When the feature includes schema or data changes, review proposed migrations and backfills for locking risk, rolling-version compatibility, sequencing, pause criteria, reconciliation, and recovery. If no schema or data migration exists, record Not applicable with the reason and continue without inventing migration work.
Prompt: Zero-Downtime Laravel Migration ReviewReview the proposed Laravel schema and data migration change set for zero-downtime feasibility and production safety using Codex and the actual repository. Use only repository content, database evidence, command output, and operational facts that are supplied or genuinely accessible in the current Codex workspace. ## Required inputs - Repository and change set: [Repository and change set] - Framework and database versions: [Framework and database versions] - Production schema evidence: [Production schema evidence] - Workload and table evidence: [Workload and table evidence] - Deployment topology and compatibility window: [Deployment topology and compatibility window] - Backfill and recovery constraints: [Backfill and recovery constraints] - Operational limits and approvals: [Operational limits and approvals] - Acceptance evidence: [Acceptance evidence] The repository and change-set input should identify, where relevant: - the exact release, commit, branch, or diff under review; - migration files; - raw SQL; - related models and casts; - accessors and mutators; - validation rules; - services and query builders; - controllers and API resources; - jobs and queue payloads; - events and listeners; - scheduled commands; - factories and seeders; - tests; - feature flags; - application deployment order. Production schema evidence should include, where available: - current columns and data types; - defaults; - nullability; - indexes; - constraints; - foreign keys; - generated columns; - approximate row counts; - duplicate, null, orphan, or invalid-data counts; - relevant database metadata; - observed schema drift. Workload and table evidence should describe, where available: - read and write rates; - transaction duration; - long-running transactions; - high-traffic periods; - table growth; - replica use and acceptable lag; - connection pooling; - lock or statement timeouts; - queue throughput; - scheduled workloads; - disk, transaction-log, or WAL constraints. Deployment topology should identify: - environments; - promotion order; - application instances; - queue workers; - scheduled processes; - deployment strategy; - mixed-version window; - maintenance constraints; - maximum acceptable interruption or degradation. Backfill and recovery constraints should identify: - whether data transformation is required; - acceptable batch and runtime limits; - retry and resume requirements; - backup scope and freshness; - restore evidence; - rollback and roll-forward expectations; - data-loss tolerance. Operational limits and approvals should state: - permitted read-only inspection; - permitted local commands; - whether file edits are permitted; - prohibited actions; - production-access restrictions; - database-owner and release-owner responsibilities; - required human approval gates. Acceptance evidence should define the observable conditions required before: - rehearsal; - schema expansion; - backfill; - read switching; - constraint validation; - contract work; - cleanup; - production completion. ## Zero-downtime standard Do not interpret “zero downtime” as a literal guarantee of zero locks, zero latency change, or zero operational impact. Evaluate zero-downtime feasibility against the supplied service objectives and acceptance constraints, including: - permitted service interruption; - acceptable latency or error-rate change; - write availability; - queue delay; - replica lag; - maintenance allowance; - user-visible degradation; - compatibility requirements. If those thresholds are not supplied, mark zero-downtime feasibility as unverified. Do not invent an acceptable outage or degradation threshold. ## Input and evidence rules 1. Begin with an input-status table. Classify every required input as: - supplied; - observed in the accessible workspace; - missing; - ambiguous; - conflicting; - not applicable. 2. Bind all material evidence to the exact release under review where possible. Record: - commit, revision, or diff; - migration filename and identifier; - database engine and version; - target environment; - schema snapshot date; - workload measurement window; - command or rehearsal timestamp; - artifact or output identity. Evidence from another commit, migration set, database version, schema state, environment, or execution window is not automatically evidence for this release. 3. Cite repository findings using available file paths, line ranges, classes, methods, migration names, or symbols. 4. Cite operational findings by naming the supplied: - schema snapshot; - command output; - metric; - query result; - runbook; - deployment record; - backup record; - rehearsal artifact; - user statement. 5. Label every material statement as one of: - confirmed; - inferred; - assumed; - unknown; - conflicting. Never convert an assumption or generic database practice into a confirmed finding. 6. If migration files are unavailable, stop after listing the exact migrations and related code required. Do not issue a deployment or zero-downtime decision. 7. If the database engine or exact version is missing or conflicting, do not make engine-specific claims about: - locking; - online DDL; - table rewrites; - transactional behavior; - concurrent index creation; - instant or in-place alterations. Request authoritative version output. 8. If table size, write load, production schema, long-running transactions, or deployment topology is unknown, mark lock duration and zero-downtime feasibility unknown. Do not automatically classify the operation as safe or unsafe. 9. Reconcile repository migrations with the actual production schema. Production schema evidence governs operational risk. Repository history remains evidence of intended state. Unexplained schema drift is a release blocker. 10. Distinguish clearly: - requested work; - proposed edits or commands; - executed checks; - supplied execution evidence; - unavailable checks; - unverified results. A command is executed only when Codex actually runs it in an authorized environment and captures its result. Command output supplied by the user is supplied evidence, not independently reproduced evidence. 11. Do not invent: - row counts; - batch sizes; - operation duration; - lock duration; - throughput; - replica lag; - backup validity; - restore success; - database behavior; - test output; - deployment success. 12. When a numerical recommendation cannot be supported, provide a calibration method or bounded range instead of false precision. ## Codex authority boundaries Unless [Operational limits and approvals] explicitly restricts it, permit: - read-only repository inspection; - inspection of supplied schema metadata; - non-mutating local diagnostics; - review of existing test and deployment configuration. Treat the following as unauthorized unless expressly approved: - file edits; - mutating commands; - dependency changes; - database writes; - migrations; - backfills; - destructive SQL; - production queries; - load tests; - cache or queue changes; - deployments; - rollbacks; - external-service changes. Even where local edits are authorized, do not execute: - production migrations; - production backfills; - destructive SQL; - production rollback commands; - deployment; - DNS or infrastructure changes. Production execution, restore decisions, destructive changes, and release approval remain human-controlled actions. Do not expose credentials, connection strings, customer records, personal data, payment data, or confidential production rows. Request redacted schema metadata, aggregate counts, and sanitized samples. If repository edits are separately authorized, make only the smallest reviewable changes required to reduce migration risk. Keep applied changes separate from proposed but unapplied work. ## Focused review workflow ### 1. Establish the release identity and review scope Record: - release or commit identity; - migration files; - related application components; - target database engine and version; - target environment; - deployment strategy; - compatibility window; - maintenance limits; - supplied acceptance criteria. State explicitly what Codex inspected and what remained unavailable. ### 2. Reconcile the migration surface Inventory every `up` and `down` operation and every raw SQL statement. For each operation, identify: - migration file and location; - table or relation; - columns; - data types; - defaults; - nullability; - generated values; - indexes; - uniqueness rules; - foreign keys; - check constraints; - data transformations; - application dependencies. Trace old and new schema names through: - models; - casts; - accessors and mutators; - validation; - services; - queries; - API resources; - events and listeners; - queue payloads; - scheduled work; - reports; - imports and exports; - factories and seeders; - tests. Flag behavior dependent on: - Laravel version; - database driver; - doctrine/dbal; - database-server version; - migration configuration; - transactional DDL support. Do not infer the current production schema solely from migration history. ### 3. Analyze database-engine behavior For MySQL or MariaDB, assess the supplied version and operation against applicable: - instant, in-place, or table-copy behavior; - metadata-lock acquisition; - index-build concurrency; - implicit commits; - foreign-key checks; - generated-column behavior; - default-expression support; - row format; - online-DDL options; - replica effects. Treat `ALGORITHM`, `LOCK`, online DDL, or similar clauses as proposals until their support is validated against the exact engine and version. Identify long transactions that could delay metadata locks. For PostgreSQL, assess: - catalog-only versus table-rewrite behavior; - required lock level and likely duration; - transaction boundaries; - `CREATE INDEX CONCURRENTLY`; - `DROP INDEX CONCURRENTLY`; - invalid indexes after failure; - `NOT VALID` constraints; - later constraint validation; - default-value behavior; - type-change rewrites; - long-running transactions; - dead tuples; - WAL growth; - replica lag. Identify where Laravel migration transaction behavior conflicts with concurrent operations. For another engine, limit conclusions to documented behavior supported by supplied evidence. SQLite development success is not evidence that a MySQL, MariaDB, or PostgreSQL production migration is safe. Do not recommend an external online-schema-change tool unless its suitability, operational ownership, constraints, and approval requirements have been evaluated separately. ### 4. Analyze operation-specific failure modes If this is a prospective review, analyze credible migration failure modes without pretending a failure has already occurred. If an actual migration has failed, reconstruct the failure using supplied evidence and establish root cause only where the causal chain is supported. Check for: - non-null additions before compatible writes and backfill completion; - expensive defaults or table rewrites; - in-place type changes; - truncation; - collation or encoding changes; - lossy casts; - renames or drops while old code still uses the schema; - unique indexes before duplicate and null-semantics checks; - foreign keys before orphan and supporting-index review; - cascade effects; - indexes that do not match observed query predicates or ordering; - blocked writes; - metadata-lock queues; - statement or lock timeouts; - disk or temporary-space pressure; - transaction-log or WAL growth; - replica lag; - failover exposure; - schema and data changes combined into one irreversible unit; - unbounded updates; - offset-based backfills; - mutable pagination keys; - hot-row contention; - retries that duplicate effects; - queue flooding; - `down` methods that destroy data or restore structure without restoring meaning; - migration ordering and timestamp collisions; - environment-dependent migrations; - non-idempotent raw SQL; - mixed-version incompatibility. A migration `down` method is not, by itself, a complete rollback or recovery plan. ### 5. Evaluate mixed-version compatibility Determine whether old and new application versions can coexist with the intermediate schema. Include: - web processes; - API processes; - queue workers; - delayed jobs; - scheduled commands; - reports; - exports; - integrations; - external consumers. Check: - reads from old and new columns; - writes to old and new columns; - dual-write behavior; - default and null handling; - serialized queue payloads; - cache-key or serialization changes; - deployment and worker restart order; - feature-flag ownership and defaults. Do not allow contract work while old application or worker versions may still depend on the old schema. ### 6. Determine the compatible release sequence For every risky change, decide whether it requires: 1. expand; 2. compatibility code; 3. dual write; 4. backfill; 5. reconciliation; 6. read switch; 7. constraint validation; 8. contract; 9. cleanup. For every phase, define: - compatible application versions; - compatible worker versions; - required entry evidence; - proposed action; - monitoring signals; - pause conditions; - acceptance criteria; - recovery path; - approval gate. Use feature flags only where ownership, default state, rollback behavior, and removal criteria are supplied or explicitly proposed. ### 7. Design a controlled backfill Do not place a large backfill inside a schema migration. When a backfill is required, specify: - a versioned Artisan command, controlled job, or reviewed script; - stable keyset batching; - candidate batch-size range; - staging calibration method; - transaction scope; - idempotency predicate or key; - throttling signal; - checkpointing; - progress metrics; - retry behavior; - pause and resume behavior; - failed-record quarantine; - observability; - termination criteria. Base numerical recommendations on supplied measurements. Otherwise mark them for calibration. Define reconciliation using: - candidate count; - processed count; - success count; - skipped count; - failure count; - remaining count; - invariant checks. Unexplained differences must block progression. ### 8. Design rollback and forward recovery Separate: - application rollback; - schema rollback; - backfill pause; - backfill reversal; - data restoration; - forward-compatible recovery. Prefer forward recovery when: - a destructive `down` method would lose data; - old code cannot operate against the new schema; - a partial backfill has changed business meaning; - contract work has already removed compatibility. Identify: - the last reversible phase; - failure indicators; - immediate safe response; - data-loss exposure; - backup dependencies; - restore dependencies; - partial-failure handling; - approval gates; - evidence required before resuming. A backup claim is insufficient without evidence of: - scope; - freshness; - retention; - encryption handling; - access; - restore testing appropriate to the change. ### 9. Define verification and acceptance evidence Propose repository-appropriate checks. Do not imply that SQL generation or `migrate --pretend` proves online execution safety. Where applicable, include: - migration-operation reconciliation; - production-schema reconciliation; - generated-SQL review; - engine-supported DDL validation; - duplicate checks; - orphan checks; - null and range checks; - truncation and cast-failure checks; - representative query plans; - old-version application tests; - mixed-version tests; - new-version tests; - queue-worker compatibility tests; - production-like rehearsal; - lock-wait observations; - blocked-session observations; - disk and temporary-space observations; - transaction-log or WAL growth; - replica-lag observations; - backfill reconciliation; - post-phase schema and data checks; - rollback or forward-recovery rehearsal. For every proposed command or query, state: - purpose; - target environment; - expected observation; - failure meaning; - safety caveat; - work state: proposed, executed, supplied, unavailable, or unverified. Avoid production-wide scans unless an authorized operator confirms: - acceptable execution plan; - timeout; - replica or primary target; - impact window; - cancellation method. ## Risk classification Use only these qualitative states: - Critical — credible risk of data loss, corruption, prolonged outage, irreversible change, uncontrolled production impact, or a release state from which neither old nor new code can recover safely. - High — material lock, availability, compatibility, integrity, backfill, rollback, or recovery risk requiring correction or explicit evidence before progression. - Medium — a meaningful but controllable risk requiring defined safeguards, monitoring, ownership, or a phased release condition. - Low — evidence supports limited blast radius and acceptable behavior within the supplied operational constraints. - Unknown — available evidence is insufficient to classify the risk defensibly. Do not rate a risk Low solely because the migration is small, passes locally, or uses a familiar Laravel schema method. ## Output contract: zero-downtime migration review deliverable Keep the report concise and proportional to the migration scope, risk, and available evidence. Do not repeat the same evidence or limitation across multiple sections. Use operation IDs, finding IDs, and evidence IDs for cross-reference. Where a subsection is genuinely not applicable, retain the heading, state `Not applicable`, and explain briefly why. Never omit: - evidence and coverage; - schema-operation register; - blockers; - compatibility analysis; - recovery; - verification; - release decision. ### A. Review basis and evidence coverage Report: - exact release identity; - target environment; - database engine and version; - migration files and related code inspected; - unavailable materials; - supplied, observed, missing, ambiguous, and conflicting inputs; - zero-downtime acceptance definition; - review limitations. ### B. Schema-operation register For every operation provide: - operation ID; - migration and location; - generated or intended DDL; - affected object; - data touch; - engine and version dependency; - expected lock or rewrite behavior; - rolling-code compatibility; - reversibility; - supporting evidence; - risk state. ### C. Blocking findings and risk register For every material finding provide: - finding ID; - operation or release phase; - failure scenario; - triggering condition; - impact; - risk state; - supporting evidence; - uncertainty; - minimum risk-reducing change; - required owner; - closure evidence. Treat these as blockers until resolved: - unknown engine-specific lock or rewrite behavior for a material operation; - unreconciled production-schema drift; - unbounded backfills; - destructive changes without recovery; - incompatible mixed-version operation; - missing required acceptance evidence. ### D. Compatible phased migration design Provide the ordered release plan. For each phase state: - migration or code change; - compatible application and worker versions; - entry evidence; - proposed action; - monitoring signals; - pause thresholds; - acceptance criteria; - rollback or forward-recovery path; - approval gate. If a single-phase release is sufficient, justify that conclusion using engine-specific, workload, compatibility, and recovery evidence. ### E. Backfill control sheet State: - selection predicate; - stable cursor; - batching method; - calibration method; - idempotency behavior; - transaction boundary; - throttle and pause signals; - retry handling; - checkpoint storage; - progress metrics; - reconciliation equations; - anomaly handling; - completion criteria; - read-switch and contract prerequisites. If no backfill is required, state `Not applicable` and explain why. ### F. Mixed-version compatibility record Report compatibility for: - old application with expanded schema; - new application with intermediate schema; - queue workers and delayed jobs; - scheduled commands; - APIs and integrations; - caches and serialized data; - feature flags; - contract and cleanup timing. Identify the last point at which old code remains safe. ### G. Recovery matrix Cover failure: - before DDL; - during DDL; - after schema expansion; - during backfill; - after read switch; - during contract; - after application rollback. For each case state: - observable symptoms; - immediate safe response; - approval-required action; - data-loss exposure; - recovery evidence; - whether old and new code remain operable. ### H. Verification runbook List commands, SQL, tests, and observations in release order. For each item provide: - check ID; - purpose; - target environment; - command or method; - expected result; - actual supplied or observed result; - evidence; - safety limit; - status: proposed, executed, supplied, unavailable, or unverified; - acceptance result: pass, fail, investigate, or not assessed. Never fabricate command output. ### I. Release decision record Choose exactly one status: - Ready for authorized rehearsal - Ready for authorized phased production rollout - Changes required - Blocked by missing evidence - Unsafe as proposed State: - zero-downtime feasibility; - highest residual risks; - required changes; - unresolved assumptions; - required human approvals; - next evidence-producing action. Do not use “safe to deploy” unless every mandatory acceptance criterion is supported by current, release-bound evidence. ## Final quality gate Before returning the report, verify that: 1. Every migration operation is accounted for. 2. The reviewed evidence is bound to the exact release where possible. 3. Production schema drift is reconciled or explicitly blocking. 4. Database-engine and version dependencies are addressed. 5. Lock, rewrite, index, constraint, and transaction behavior are assessed. 6. Mixed-version application and worker compatibility is evaluated. 7. Backfills are bounded, resumable, idempotent, observable, and reconciled where required. 8. Rollback and forward-recovery paths are distinguished. 9. Proposed commands include expected observations and safety limits. 10. Acceptance criteria reconcile schema, data, application behavior, workers, and operations. 11. Zero-downtime feasibility is tied to supplied service constraints. 12. No execution, verification, approval, deployment, recovery, or completion is claimed without evidence.Input for this step
When applicable, provide migration files or specifications, database engine and version, table sizes and write patterns, deployment sequence, worker behavior, backfill design, and recovery constraints. Otherwise provide confirmation that the change has no schema or data migration.
Carry forward
When applicable, pass required migration revisions, deployment ordering, rehearsal checks, reconciliation queries, stop conditions, and residual risks to implementation and pull-request review. Otherwise pass the recorded Not-applicable decision and continue only when the real change set and test evidence exist.
Review note
When an applicable migration can lock, rewrite, delete, or irreversibly transform production data, a database or production owner should approve it. No migration approval is required when schema and data migration were confirmed Not applicable.
-
Step 4 Conduct an Evidence-Grounded Laravel Pull Request Review
Begin only after separately authorized implementation has produced a real pull request or change set and test evidence. Review that change against the approved feature scope and applicable migration controls, covering behavior, authorization, tenant isolation, transactions, queues, caches, compatibility, deployment risk, and test coverage.
Prompt: Evidence-Grounded Laravel Pull Request Review with CodexReview the supplied Laravel pull request as a bounded, evidence-grounded assessment. Identify defects, security risks, regressions, migration hazards, compatibility problems, and verification gaps without changing the repository or making the merge decision. ## Review inputs - Pull request objective and acceptance criteria: [Pull request objective and acceptance criteria] - Pull request diff or commit range: [Pull request diff or commit range] - Repository context and relevant files: [Repository context and relevant files] - Laravel stack and target environments: [Laravel stack and target environments] - Project conventions and risk constraints: [Project conventions and risk constraints] - Authorized Codex access and execution scope: [Authorized Codex access and execution scope] - Verification commands and supplied evidence: [Verification commands and supplied evidence] - Deployment, migration, and rollback context: [Deployment migration and rollback context] ## Input gate The minimum prerequisites are the pull request objective, acceptance criteria, diff or commit range, Laravel and PHP versions, relevant repository access, and the authorized inspection scope. If the diff, objective, or access boundary is missing or unusable, stop and request it rather than producing a merge assessment. Treat tests, logs, deployment details, schema snapshots, production topology, traffic assumptions, and rollback procedures as optional unless the change affects those areas. When optional context is absent, continue only with a bounded static review, identify the resulting blind spots, and mark affected conclusions as unverified. If inputs conflict, record the conflict and do not silently choose one version. Never infer omitted code, configuration, database state, runtime behavior, or organizational policy. ## Codex access and authority boundaries 1. Inspect only the supplied diff, files, repository content, and artifacts that Codex can actually access. State what was and was not inspected. 2. Default to read-only review. Do not edit files, create commits, push branches, merge or approve the pull request, deploy code, run production migrations, alter data, rotate credentials, contact people, or change external systems. 3. Run commands only when the authorized scope explicitly permits execution and the environment is confirmed non-production. Do not run destructive commands, commands requiring secrets, dependency updates, irreversible migrations, or commands that may affect shared services. Stop and request human authorization if a command could mutate persistent or shared state. 4. Redact secrets, tokens, credentials, personal data, and sensitive tenant data from quotations and command output. Flag exposed secrets without reproducing their values. 5. Recommendations are advisory. A human maintainer retains responsibility for remediation, risk acceptance, merge approval, rollout, and rollback decisions. ## Evidence and claim rules - Separate supplied facts, direct code observations, command execution evidence, assumptions, hypotheses, unknowns, and conflicts. - Support every finding with a file and line, diff hunk, configuration location, schema artifact, log excerpt, or command result. If exact lines are unavailable, cite the nearest symbol or file and say why precision is limited. - Explain the failure mechanism and affected request, job, migration, data path, or deployment phase. Do not report a theoretical pattern as a confirmed defect without showing that the relevant code path is reachable. - Assign confidence as high, medium, or low and explain material uncertainty. Downgrade or omit findings that cannot be connected to the supplied change. - Code inspection is not execution evidence. Supplied historical test output is not evidence that the reviewed commit currently passes unless its commit and environment match. - Use the terms passed, failed, fixed, tested, verified, deployed, approved, or completed only when corresponding actions actually occurred and evidence is available. Otherwise use proposed, not run, unavailable, blocked, or unverified. ## Review workflow ### 1. Establish scope and coverage Summarize the intended behavior, affected entry points, trust boundaries, persistence changes, asynchronous paths, public contracts, and deployment implications. Map changed files to related Laravel components that may need inspection, including routes, middleware, controllers, Form Requests, policies and gates, models, casts, scopes, services, events, listeners, jobs, notifications, API resources, views, configuration, migrations, factories, seeders, and tests. Identify related files that were expected but unavailable. Keep unrelated legacy issues out of scope unless the pull request activates or materially worsens them. ### 2. Trace behavior and framework interactions Trace representative success, validation-failure, authorization-failure, not-found, retry, and exception paths from entry point to side effects. Check Laravel-specific behavior such as route-model binding, middleware order, container bindings, service-provider registration, Eloquent scopes and events, transaction boundaries, exception rendering, configuration caching, and environment-dependent behavior. Compare actual behavior with the stated acceptance criteria. Note backward-compatibility effects on HTTP APIs, console commands, scheduled tasks, events, queue payloads, serialized models, webhooks, and package or PHP requirements. ### 3. Review security and tenant isolation Check authentication and authorization at every protected operation, including policy coverage, ownership checks, tenant scoping, elevated roles, indirect object references, and administrative bypasses. Review validation and normalization, mass assignment, unsafe query construction, output escaping, CSRF exposure, SSRF paths, file uploads, signed URLs, rate limits, secret handling, and sensitive logging where relevant. Treat a plausible cross-tenant access path, authorization bypass, credential disclosure, injection path, or destructive unauthenticated action as blocking unless evidence disproves reachability or impact. ### 4. Review database and rollout safety For schema or data changes, evaluate table locks or rewrites, index creation, foreign keys, defaults, nullability, type narrowing, backfill cost, duplicate or invalid existing data, transaction behavior, and database-engine differences. Determine whether old and new application versions can safely coexist during rolling deployment. Assess expand-and-contract sequencing, read/write compatibility, backfill observability, retry and resume behavior, rollback feasibility, and irreversible data loss. Do not assume a migration down method restores transformed or deleted data. Flag migrations that require production data profiling, maintenance windows, database-specific online DDL, or operator approval. ### 5. Review queues, transactions, caches, and concurrency Where applicable, inspect job serialization, retry policy, idempotency, uniqueness, timeout handling, after-commit dispatch, stale model state, duplicate delivery, dead-letter handling, and side effects. Check race conditions, lost updates, locking, transaction isolation, cache-key scope, invalidation, and tenant leakage. Identify failures that could appear only under retries, concurrent requests, rolling deployment, or partial outages. ### 6. Evaluate tests and verification Map each acceptance criterion and material risk to existing or missing tests. Consider feature, unit, authorization, validation, database, migration, queue, concurrency, contract, and regression coverage as applicable. Check whether assertions prove externally meaningful behavior rather than only status codes or implementation details. If command execution is explicitly authorized, run only the smallest relevant safe commands first. Record the exact command, environment, expected observation, actual observation, exit status, and evidence location. Reconcile failures with the reviewed commit; do not dismiss them as unrelated without evidence. If execution is unavailable or unsafe, provide commands as proposed verification and mark them not run. ### 7. Determine disposition Classify each issue as: - Blocking: credible risk of security breach, cross-tenant exposure, data loss or corruption, production outage, irreversible migration failure, broken acceptance criterion, or incompatible public contract. - Conditional: disposition depends on missing environment, data, traffic, deployment, or policy evidence that must be resolved before merging. - Non-blocking: maintainability, clarity, resilience, or test improvement with no demonstrated merge-stopping impact. Do not inflate severity. State when no blocking issue was found, but never translate that into approval. Base the recommendation on evidence coverage and unresolved blind spots. ## Required deliverable Return Markdown with these sections: # Laravel Pull Request Review ## Scope and Evidence Coverage Include the reviewed objective, diff or commit range, files and components inspected, artifacts unavailable, execution access used, and material assumptions or conflicts. ## Change and Risk Map Provide a table with columns: Area, Changed behavior, Related Laravel components, Trust or data boundary, Deployment concern, Coverage status. ## Findings Register Provide a table with columns: ID, Disposition, Severity, Confidence, Location, Evidence type, Observation, Failure mechanism, Impact, Required remediation, Verification needed. For each blocking or conditional finding, add a short evidence note quoting only the minimum safe excerpt and explain why the issue is reachable. If there are no supported findings in a disposition, write that none were found within inspected scope. ## Migration and Rollout Assessment When relevant, report database engine assumptions, lock or rewrite risk, existing-data prerequisites, old/new version compatibility, expand-and-contract needs, backfill controls, observability, rollback limits, and required operator approval. If not relevant, state why. ## Acceptance and Test Coverage Matrix Provide a table with columns: Acceptance criterion or risk, Existing evidence, Test level, Expected observation, Actual observation, Status, Gap or follow-up. Status must be Passed, Failed, Not run, Blocked, or Unverified and must match the evidence. ## Verification Ledger List each executed or proposed command or manual check with its purpose, target environment, safety prerequisites, expected result, actual result, execution state, and evidence location. Never present proposed commands as executed. ## Merge Guidance and Human Handoff Choose one advisory state: Block pending remediation, Hold pending evidence, or No blocking issue found within reviewed scope. Explain the evidence basis, unresolved unknowns, required owners or approvals, safest next actions, and any rollout or rollback checkpoints. Explicitly state that Codex did not merge, approve, deploy, or modify the pull request.Input for this step
Provide the actual pull-request diff or change set, linked requirements, implementation plan, applicable migration review or Not-applicable record, real test and CI evidence, and known deviations. Keep merge authority with the designated engineering reviewer.
Carry forward
Pass code-location-specific findings, blocking defects, verification gaps, residual risks, and the evidence-qualified merge recommendation to the production verification step.
Review note
A qualified engineering reviewer should resolve blocking findings and make the merge decision.
-
Step 5 Build the Production Verification and Release Gate
Convert the approved change package and review findings into a risk-based verification plan covering automated tests, manual checks, CI gates, deployment smoke tests, observability, rollback readiness, and release confidence.
Prompt: Production Test and Verification Plan PromptBuild a risk-based test and verification plan for the following software change or release. Inputs - Change or release under test: [Change or release under test] - Repository and relevant files: [Repository and relevant files] - System and runtime context: [System and runtime context] - Acceptance criteria: [Acceptance criteria] - Test and deployment constraints: [Test and deployment constraints] - Available evidence: [Available evidence] - Authorized actions and environment: [Authorized actions and environment] - CI/CD and rollback context: [CI/CD and rollback context] Codex operating boundaries - Use Codex to inspect supplied repository content, diffs, configuration, test suites, CI definitions, logs, and command output that are actually available in the session. - Run tests or read additional files only when the environment provides that capability and the authorized-actions input permits it. Prefer targeted, read-only inspection before expensive or state-changing commands. - Do not deploy, merge, approve a release, alter production, access undeclared systems, expose secrets, create real customer data, disable safeguards, or run destructive commands. Treat migrations, load tests, security probes, external API calls, and commands that write or delete data as approval-gated. - Stop before an action if its target, blast radius, data handling, cost, reversibility, or authorization is unclear. Record the blocked action, required approval, and a safe alternative. - Never imply that a command ran merely because it was proposed. Never claim that code is fixed, tests passed, coverage improved, a release was approved, a rollback works, or a deployment completed without corresponding execution evidence. Input and evidence rules 1. Treat the change target, acceptance criteria, repository or equivalent technical artifacts, runtime context, and authority scope as prerequisites for an execution-backed assessment. If one is missing, ask only the questions necessary to unblock it. 2. If execution is blocked but supplied artifacts are sufficient, produce a bounded plan and mark execution-dependent conclusions unverified. If the change boundary or acceptance criteria cannot be established, do not issue a release-confidence recommendation. 3. Maintain an evidence ledger that distinguishes supplied facts, direct Codex observations, command execution evidence, assumptions, hypotheses, conflicts, and unknowns. Cite file paths, symbols, diff locations, log excerpts, CI job names, test identifiers, commands, exit codes, or artifact locations where available. 4. Do not resolve conflicting documentation, code behavior, logs, or requirements by guessing. Describe the conflict, its verification impact, and who must resolve it. 5. Do not infer test success from the existence of test files, infer production behavior solely from mocks, or equate code coverage with behavioral correctness. Assessment workflow 1. Establish scope and baseline - Identify changed components, interfaces, dependencies, data stores, feature flags, configuration, infrastructure, schemas, jobs, and user journeys. - Determine the comparison baseline and whether generated files, lockfiles, migrations, API contracts, or deployment manifests changed. - Record exclusions and distinguish intentional scope limits from unavailable evidence. 2. Perform change-impact and risk analysis - Trace affected call paths, consumers, upstream and downstream integrations, shared libraries, background work, cache behavior, concurrency boundaries, and compatibility requirements. - Rate each material risk by likelihood and impact. Include regression, data integrity, authorization, privacy, availability, performance, observability, backward compatibility, migration, retry or idempotency, and rollback risks when relevant. - Prioritize tests by risk reduction rather than test count. 3. Build acceptance traceability - Decompose each acceptance criterion into observable behavior. - Map it to one or more unit, component, integration, contract, end-to-end, migration, security, performance, resilience, or manual checks as appropriate. - Define setup, fixtures or test data, action, expected result, required evidence, cleanup, and ownership for every check. - Include negative paths and boundaries such as empty, null, malformed, duplicate, maximum-size, timeout, partial-failure, retry, race, permission-denied, stale-cache, and dependency-unavailable conditions where applicable. 4. Evaluate existing verification assets - Identify relevant tests and assess whether their assertions prove the required behavior rather than merely execute code. - Detect missing assertions, over-mocking, nondeterministic time or randomness, shared-state leakage, order dependence, brittle snapshots, unsafe fixtures, hidden network access, and flaky retries. - Review CI triggers, path filters, matrices, service dependencies, caches, artifacts, timeouts, required checks, branch protections, and failure propagation for gaps that could produce false confidence. 5. Specify the verification sequence - Order checks from fast and isolated to broad and operational: static checks, targeted unit tests, component or integration tests, contracts, migrations, end-to-end paths, non-functional checks, and manual exploration. - Provide exact commands only when supported by repository evidence. Otherwise label commands as proposed and identify what must be confirmed. - Separate blocking release gates from advisory checks. Define retry policy, flaky-test handling, artifact retention, test-data cleanup, and ownership of failures. 6. Execute only authorized checks - Before each command, state its purpose, environment, expected side effects, and why it is within authority. - Capture the exact command, working directory, relevant environment details with secrets redacted, start and finish state, exit code, actual observation, and artifact reference. - Do not silently rewrite code or tests to make checks pass. If modification is expressly authorized, present the proposed patch and its rationale separately, then verify it with fresh evidence. - Classify each check as passed, failed, blocked, not run, or inconclusive. A zero exit code is not sufficient when assertions, logs, skipped-test counts, or produced artifacts contradict success. 7. Assess deployment and recovery readiness - Verify pre-deployment prerequisites, configuration compatibility, secret references without revealing values, migration ordering, backward and forward compatibility, feature-flag behavior, health checks, and capacity assumptions where relevant. - Define post-deployment smoke tests and observability signals with query or dashboard source, baseline, threshold, observation window, and owner. Cover errors, latency, saturation, queue lag, data reconciliation, and key business behavior as applicable. - Specify rollback or roll-forward triggers, decision owner, procedure reference, data consequences, compatibility limits, recovery verification, and cases where rollback is unsafe, such as irreversible schema or data transformations. 8. Reconcile evidence and determine confidence - Reconcile every acceptance criterion, risk, test result, defect, skipped check, and conflicting observation. - Recommend exactly one state: Ready, Conditionally ready, Not ready, or Unassessed. This is a technical recommendation, not release approval. - Ready requires all blocking criteria to have passing evidence and no unresolved release-blocking defect or unknown. Conditionally ready requires explicit conditions, owners, and deadlines. Not ready requires named blockers. Unassessed applies when evidence is insufficient to support a conclusion. Required deliverable A. Scope and evidence ledger - Change boundary, baseline, affected systems, exclusions, authority scope, and environment. - Evidence table with ID, classification, source or artifact, observation, reliability limitation, and related conclusion. - Assumptions, unknowns, and conflicts, each with impact and resolution owner. B. Change-impact and risk register - Component or behavior, change mechanism, dependent systems, failure mode, likelihood, impact, detectability, risk priority, proposed control, and residual risk. C. Acceptance-to-test matrix - Criterion ID, observable behavior, risk covered, test level, setup and data, procedure or command, expected observation, required evidence, cleanup, owner, priority, and status. D. Existing test and CI assessment - Relevant test or job, what it proves, identified gap, flakiness or isolation concern, CI gate status, and recommended correction. E. Execution record - Check ID, proposed or executed state, exact command or manual procedure, environment, expected observation, actual observation, exit code when applicable, duration when known, evidence reference, and result classification. F. Defect and unresolved-work register - Defect or gap ID, reproduction evidence, affected criterion, severity, release impact, workaround, owner, and retest requirement. Keep proposed fixes separate from applied changes. G. Deployment, observability, and recovery checks - Pre-deployment gates, smoke tests, monitored signals, baselines and thresholds, observation windows, rollback or roll-forward triggers, recovery procedure references, data reconciliation, and responsible approvers. H. Verification verdict - Recommended state, evidence-backed rationale, passed blocking gates, failed or missing gates, residual risks, approval still required, and the smallest safe next action. Use concise technical language. Preserve unresolved states and make every consequential conclusion traceable to evidence.Input for this step
Supply the accepted requirements, final change set, migration controls, pull-request findings, available test evidence, deployment process, monitoring signals, and rollback procedures.
Carry forward
Produce the final release checklist, evidence register, monitoring and rollback triggers, unresolved conditions, and a conditional go, no-go, or defer recommendation for release owners.
Review note
The authorized release owner should make the final deployment decision after reviewing all blockers, unverified checks, and rollback readiness.
Completion criteria
The package traces the approved product outcome through implementation scope, any applicable migration safety review, an actual change set, pull-request findings, tests, deployment checks, monitoring, and rollback readiness. Separately authorized implementation, unexecuted work, Not-applicable migration review, unresolved blockers, and unverified checks remain explicit.
Related Workflows
Browse WorkflowsProduction Incident to Safe Patch and Prevention Plan
Turn production logs and repository evidence into a minimal patch proposal, verification plan, independent review, deployment controls, and a blameless prevention backlog.
Laravel Incident Investigation and Controlled Correction
Use a compact three-step path to diagnose a Laravel production incident, make only an authorized minimal correction, independently review the change, and prepare a controlled release.
Safe AI Agent Workflow Selection and Deployment Readiness
Move from a broad list of AI opportunities to one prioritized, mapped, governed, and measurable agent workflow that is ready for an informed pilot decision.
Was this useful?