Define the failure before changing the environment
This guide is for a developer inheriting an agent demo that must become supportable. The original teaching example is an exhibition-preview assistant: it receives a fictional exhibit list, generates a browser preview and returns a result to a web page. Suppose a report says, “the task log says complete, but the page has no preview.” Establish whether complete means a process exited, a file was generated or a user could actually access the result. These are different claims. No system was run or diagnosed for this article.
Create an incident card with expected and observed behavior, first occurrence, source and image versions, triggering input, task identifier, environment and recent changes. Reproduce with a small list containing no sensitive data. Map five boundaries: entry point, agent, browser process, result artifact and page reader. Write the input and output of each boundary. Preserve the failure evidence instead of restarting every service and overwriting the only record of the problem.
Scenario one: find the container, network or storage break
Establish service state and a relevant time window, then inspect logs for the failing task. Docker Compose provides service log output, with filtering options to choose for the installed version. Do not upload every log from the host. Compare application startup, browser exit and artifact handoff times, accounting for time zones and possible clock differences. A zero exit code describes one process outcome, not whether another service received its file.
For the exhibition case, ask where the artifact is written and who reads it. An agent's /app/out and a web container's /srv/previews do not share data merely because they have similar purposes. Inspect actual mounts, resolved paths, runtime users and access. Determine whether the result landed in a temporary container layer instead of intended storage. A harmless marker read and write in an authorized test directory can verify one specific shared path; it does not justify opening the host disk or running everything with administrator privileges.
Map network calls separately. Localhost inside a browser container is not the host's localhost or the web service's localhost. Record resolution, connection, HTTP response, authentication and business outcome as separate stages. Check actual service names and internal ports rather than copying a host-facing address into every container. Follow the supported host-access method for the real Docker platform when the destination is on the host. Establish listener scope and authorized callers before considering any bridge or published port.
The result of this stage should be a small reproduction and an evidence-to-cause explanation. “The browser wrote the preview into its temporary filesystem while the web reader used a separate volume” is a checkable diagnosis. “Docker is unreliable” is not. Describe the affected configuration, services needing replacement, data-preservation conditions and recovery route. Change one layer at a time and use the same input again, so a coincidental success does not become an unsupported root-cause claim.
Scenario two: validate browser execution and visible results
The absence of a desktop window is not automatically failure. Establish whether the task requires headless execution, a headed session or a remote viewing interface. A headed Linux run may require an appropriate display environment. A headless task should instead have page-state and artifact evidence. Process existence, a reachable debugging endpoint and a readable target page are distinct checks. Launch logs alone do not show what a user saw.
Begin with a minimal local static preview. Read a known title and save a screenshot to the agreed artifact location. Only then add application scripts, data requests and any permitted authentication. Retain console errors, failed requests, actual page address and relevant DOM state. Playwright's documented Trace Viewer can help examine recorded traces; confirm that tracing was actually collected rather than renaming an ordinary application log as a trace. Use the project's supported tools and version.
For the exhibition fixture, cover three paths. A valid list should display the expected cards. A missing image should show the intended fallback. A generation timeout should produce a recoverable error. Use meaningful, stable interface locators and wait for a state that demonstrates completion rather than simply increasing a fixed sleep. Verify that the generated artifact is read by the next service and that a download link belongs to the current task. A stale file from yesterday's successful task is not evidence that today's task completed.
Screenshots and traces can contain page text, requests or session information. Retain and share only what the task permits, after reviewing content and destination. The fictional exhibit fixture does not require private browsing history or real accounts. If the available tool cannot observe the page, report the observation gap. A command returning does not justify a claim that the user journey passed. The minimal-page check separates a browser-environment failure from an application failure before the full route is reconnected.
Scenario three: make the repair maintainable
Establish reproducible versions and builds before optimizing image size. Inspect dependency constraints, build context, included assets and runtime configuration. Then assess multi-stage builds or caching where useful. Do not remove browser libraries or fonts whose purpose has not been established merely to obtain a smaller image. Preserve necessary diagnostics with appropriate access; a debugging interface should not silently become a public service.
Keep secrets out of source, image layers and frontend assets. Runtime variables can still appear in logs or diagnostic output, so choose a supported secret-management route and review consumption and reporting. Distinguish browser session data from ordinary temporary output and define retention and cleanup conditions. Connect service logs, page outcome and delivered artifacts through a non-sensitive task identifier. Assign responsibility for rotation, retention and storage pressure rather than assuming logs can grow forever.
Turn the failing input into a regression case that exposes the issue before the repair and checks the correct result afterward. Also test the previously working list. Link the release record to source, image, configuration, actual results and limitations. A restoration plan must consider shared storage and data-format compatibility as well as the previous image. Rehearse on a suitable test copy. After release, perform the minimal checks within the authorized scope; debugging convenience is not a reason to delete production state.
Verified skill roles and prerequisites
The catalog inspection did not establish verifiable SkillPI entries corresponding to the original Docker and remote-browser names. No guessed installation links are supplied. Use Microsoft's maintained Playwright documentation and Docker's official diagnostic guidance as references for the existing supported tools. Their visible source and documented interfaces help assessment, but do not establish that this environment has been tested. Review the actual versions, dependencies, licenses and integration effort before implementation.
Webapp Testing fits local page observation and interaction checks in scenario two. It needs a running test service, its address or startup command, permitted data and the required Python/Playwright dependencies. It can help retain page evidence and diagnostic clues. It does not automatically repair shared volumes, supply a remote desktop or establish deployment permissions. Page-level success also does not prove backend persistence.
Writing Guidelines fits the incident card, reproduction instructions and maintenance handoff. Supply the draft files and access to the relevant writing guidance. Its job is clarity and structure; it does not execute a container check, browser path or security scan. Keep source review, scanning and observed execution separate rather than treating an installed instruction package as a repaired system.
A concrete diagnostic request
A suitable request is: “Reproduce the exhibition preview that reports completion without a visible result in the test environment. First map the five boundaries and inspect artifact location and reader identity for the failed task. Then establish a minimal browser page. Use a fictional list, retain only the relevant log window and do not print secrets. Return causal evidence, a minimal repair and regression results. Mark anything unobservable as unknown. Do not change production networking.” The request begins with a symptom and an inspectable output instead of an indiscriminate bundle installation.
For each proposed change, record the hypothesis, expected evidence, actual observation and whether the original symptom remains. If a mounted directory fixes one fixture but breaks another, retain both inputs and investigate the difference. Do not keep broadening access until the error disappears. This comparison makes the final explanation more useful than a transcript of many unrelated commands.
Troubleshooting and FAQ
If a browser launches without a visible interface, distinguish execution mode, display setup and target-page loading before changing ports. If the image needs optimization, reproduce a known working build first, then change and verify one dependency or layer. If execution works but results vanish, follow the actual write path, reader, task identity and storage boundary. If logs contain a secret, stop further distribution and use the team's established incident process for exposure and credential handling rather than pasting it into a public issue.
Are these methods tied to one model? No, but actual tools and environments differ, so universal agent compatibility is not promised. Can a finder replace diagnosis? It can assist discovery; causal evidence still decides the fault. When is the task complete? The fault is reproducible, the repair explains it, relevant regression checks pass, and release and recovery conditions are recorded with uncovered scope stated. Both original-language sources and references remain in the editorial record. The exhibition scenario is original and illustrative, with no invented user testimonial or production test result.