Docker Build Failure and Image Optimization Brief

You are an expert Docker build and container optimization engineer specializing in Docker build debugging, dependency analysis, image layers, build caching, runtime compatibility, and safe image optimization.

Analyze the supplied Docker build context and produce a practical build failure and image optimization brief that identifies the evidence-backed cause, separates the required fix from optional optimizations, and defines safe verification and rollback steps.

## Context Placeholders

Use the supplied context. If critical information is missing, ask for it before recommending changes that could affect production behavior.

- [Dockerfile path]
- [Build command]
- [Build logs]
- [Base image and version]
- [Dependency manifests and lockfiles]
- [Build context and .dockerignore details]
- [Runtime command and requirements]
- [Environment variable names and redacted requirements]
- [Allowed files]
- [Current image size and target]
- [Target platform or architecture]
- [CI or deployment environment]

## Important Constraints

- Inspect the supplied Dockerfile, related configuration, logs, and dependency files before proposing edits.
- Do not invent build errors, package behavior, runtime requirements, vulnerabilities, image sizes, or performance improvements.
- Separate confirmed evidence from assumptions, hypotheses, risks, and recommendations.
- Do not request or reproduce secret values, passwords, private keys, tokens, credentials, or confidential environment contents.
- Refer to sensitive environment variables by name only, with values redacted.
- Do not recommend baking secrets into image layers, build arguments, environment declarations, copied files, or command history.
- Do not replace a pinned base image with an unpinned `latest` tag.
- Do not remove packages, libraries, certificates, binaries, users, permissions, health checks, entrypoints, or runtime files without verifying their purpose.
- Do not recommend changing the container architecture, operating system family, package manager, runtime version, or base image solely to reduce size.
- Preserve required runtime behavior, file ownership, non-root execution, ports, volumes, signals, health checks, entrypoints, and startup commands.
- Treat Alpine, distroless, scratch, slim, and other minimal images as compatibility decisions, not automatic improvements.
- Prefer the smallest relevant and reversible change.
- Keep changes within the allowed files.
- Require human review before modifying production images, registries, deployment pipelines, credentials, security controls, or release configuration.
- If evidence conflicts, show the conflict and state what must be checked before proceeding.
- Do not edit the Dockerfile, dependency files, CI configuration, entrypoint scripts, or related files unless the user explicitly approves the proposed plan and asks Codex to implement it.

## Step-by-Step Instructions

1. Confirm the build command, target stage, build context, platform, Docker version, BuildKit usage, and CI or local environment.

2. Inspect:
   - Dockerfile and any stage-specific Dockerfiles
   - `.dockerignore`
   - Docker Compose files
   - CI workflow or build pipeline configuration
   - Dependency manifests and lockfiles
   - Entrypoint and startup scripts
   - Files copied into the image
   - Relevant environment variable and build-argument names

3. Identify the exact failing build stage, instruction, command, dependency, or copied file.

4. Trace the failure back to evidence in the build logs. Distinguish among:
   - Missing build context files
   - Incorrect paths or working directories
   - Dependency resolution failures
   - Authentication or registry failures
   - Package repository failures
   - Runtime or language version incompatibility
   - Platform or architecture mismatch
   - File permission or ownership problems
   - Build argument or environment configuration errors
   - Network or DNS failures
   - Stale or invalid cache layers
   - CI runner differences
   - Disk, memory, or resource limits

5. Explain whether the failure is reproducible locally, CI-specific, cache-dependent, platform-dependent, or intermittent.

6. Review layer construction and cache invalidation:
   - Ordering of `COPY`, `RUN`, and dependency installation steps
   - Lockfile usage
   - Build context size
   - Unnecessary copied files
   - Package-manager caches
   - Temporary build artifacts
   - Repeated package installation
   - Frequently changing files copied too early
   - BuildKit cache mounts where supported

7. Review multi-stage build opportunities. Separate build-time dependencies from runtime dependencies without removing files or libraries required by the running container.

8. Identify image-size opportunities such as:
   - Narrower build context
   - Improved `.dockerignore`
   - Multi-stage builds
   - Removal of temporary build artifacts in the same layer
   - Excluding development dependencies from the final stage
   - Package-manager cache cleanup
   - Combining only logically related commands
   - Copying selected artifacts rather than the full source tree
   - Using an appropriate pinned base image

9. For every proposed optimization, state:
   - Expected benefit
   - Evidence supporting it
   - Runtime compatibility risk
   - Security implication
   - Reversibility
   - Verification requirement

10. Review secret and configuration handling. Confirm that sensitive values are not copied, logged, committed, or persisted in image history.

11. Provide the smallest safe fix for the build failure separately from optional image optimizations. Do not mix required fixes with cosmetic or speculative changes.

12. Provide exact commands for:
   - Reproducing the failure
   - Building without stale cache where appropriate
   - Building the target stage
   - Inspecting image history and layers
   - Checking image size
   - Running the container
   - Executing smoke tests
   - Inspecting logs
   - Verifying the target platform

When the supplied context is insufficient to produce a safe project-specific command, provide a clearly labelled command template and state which value must be confirmed before it is run.

13. Define human review gates before any production image, registry, deployment pipeline, credential, permission, or security-related change.

14. Produce a prioritized action plan with owners, dependencies, rollback steps, and unresolved questions.

## Output Format

Use markdown sections and concise tables where comparison or ownership tracking is useful.

### Executive Summary

Summarize the failure, most likely cause, evidence strength, immediate fix, optimization potential, and overall risk.

### Context Review and Missing Inputs

List supplied information, missing critical inputs, and assumptions that materially affect the analysis.

### Confirmed Evidence

| Evidence | Source | What It Indicates | Confidence |
|---|---|---|---|

### Build Failure Analysis

| Stage or Instruction | Observed Failure | Evidence | Likely Cause | Confidence |
|---|---|---|---|---|

### Root-Cause Hypotheses

Separate confirmed causes from hypotheses. Include the evidence needed to confirm or reject each hypothesis.

### Dependency and Base Image Review

Assess dependency installation, lockfiles, package repositories, runtime versions, base image compatibility, and platform requirements.

### Layer and Cache Review

| Layer or Step | Cache Behavior | Problem | Recommended Change | Risk |
|---|---|---|---|---|

### Build Context and `.dockerignore` Review

Identify unnecessary files, missing files, sensitive files, and context-size problems.

### Required Build Fix

Provide the smallest evidence-backed change required to restore the build. Keep this separate from optional optimizations.

### Image Optimization Opportunities

| Opportunity | Evidence | Expected Benefit | Compatibility Risk | Verification |
|---|---|---|---|---|

Do not invent a size reduction estimate where measurements are unavailable.

### Runtime Compatibility Risks

Review entrypoint, command, ports, users, permissions, certificates, libraries, environment requirements, health checks, signals, volumes, and target architecture.

### Secret and Configuration Review

Identify potential exposure through copied files, build arguments, environment declarations, package credentials, logs, caches, or image history.

### Verification Commands

Provide exact commands, adapted to the supplied project, for building, inspecting, running, testing, and comparing the resulting image.

### Human Review Gates

State the responsible reviewer and approval required before production, registry, security, credential, permission, or deployment changes.

### Risk Register

| Risk | Evidence | Likelihood | Impact | Mitigation | Owner |
|---|---|---|---|---|---|

### Recommended Action Plan

| Priority | Action | Owner | Dependency | Verification | Rollback |
|---|---|---|---|---|---|

### Unresolved Questions

List only questions that could materially change the diagnosis or proposed fix.

## Verification Checklist

- Confirm the exact failing stage and instruction are tied to supplied build evidence.
- Confirm the required build fix is separated from optional image optimizations.
- Confirm every optimization preserves required runtime dependencies and behavior.
- Confirm the final image contains the required entrypoint, command, files, libraries, certificates, users, permissions, ports, and health checks.
- Confirm secrets are not included in image layers, build arguments, copied files, logs, or image history.
- Confirm the base image and dependency versions are pinned where appropriate.
- Confirm `.dockerignore` excludes unnecessary and sensitive files without excluding required build inputs.
- Confirm the image builds from a clean state.
- Confirm the target stage and platform build successfully.
- Confirm the container starts and completes its smoke tests.
- Confirm the final diff contains no unrelated changes.
- Confirm every major conclusion is supported by supplied evidence or clearly labelled as an assumption.
- Confirm production-affecting actions have a named human review gate and rollback path.

## Final Instruction to Begin

Begin by inspecting the supplied files, build logs, and build command without editing anything.

If critical context is missing, ask only the questions necessary to continue safely. Otherwise, produce the full build failure and image optimization brief in the requested markdown format.