Issue Investigation

Step 4: Prepare a faithful reproduction environment

Start from a clean workspace unless the issue is explicitly about dirty state, upgrade state, or cached files.

Default to the agent's current OS and local tooling for the first repro attempt. Do not create a Windows VM, Linux container, macOS host, cloud resource, or other remote environment just because the issue mentions one in passing. Escalate to a different environment only when the issue states the behavior is OS-specific, the dependency is unavailable locally, or the current-OS attempt cannot reproduce behavior that plausibly depends on OS, shell, filesystem, networking, browser, or cloud semantics.

Before installing anything, analyze the repro steps and create a dependency readiness summary:

1. List the required tools, runtimes, package managers, services, and credentials from the issue body, comments, linked repros, and logs.
2. Check what is already available in the current environment with lightweight version probes such as dotnet --info, aspire --version, node --version, npm --version, docker --version, java --version, az --version, or gh --version.
3. Classify each missing dependency as lightweight, heavyweight/invasive, OS-specific, cloud-only, or credential-required.
4. Present the missing dependency summary to the user before changing the host environment when the setup is heavyweight, invasive, or ambiguous.

If a repro requires installing a large or invasive toolchain, prefer a disposable container over installing it on the host. Examples include Java/Play Framework/SBT, full browser stacks, Kubernetes tooling, database servers, language runtimes not already installed, or package managers that may rewrite workspace state. For example, an issue like #6715 that requires Java and the Play Framework should default to a containerized repro unless the user chooses local installation. Ask the user before installing heavyweight dependencies locally and offer choices like:

• Use a container (Recommended) — create an isolated repro environment with the required tools.
• Install locally — install the required software on the current machine.
• Do not install yet — stop and report the repro as blocked on dependency setup.

Always include the latest stable Aspire version in the repro plan. If the issue reports an old Aspire version, first try the same repro against latest stable in the smallest faithful environment. Only install or acquire the old version when you need to confirm a historical regression, validate an upgrade path, or explain a version-specific failure. If the issue does not reproduce on latest stable and the reported version is old, offer the user an issue reply that says the current stable version was checked, the issue could not be reproduced there, and asks the reporter to upgrade or provide a latest-stable repro if it still happens.

workdir="$(mktemp -d -t aspire-issue-XXXXXX)"
cd "$workdir"

For repo-local investigations, restore before building from the repository root:

cd <repo-root>
./restore.sh
./build.sh --build /p:SkipNativeBuild=true

For CLI behavior, prefer the exact reported CLI when possible:

For AppHost behavior, prefer an issue-provided AppHost snippet. If none exists, create the smallest AppHost that exercises the same resource graph, endpoints, package versions, and wait relationships. Keep platform details intact: Windows shell behavior, Bun/npm workspaces, Docker Desktop architecture, static ports, or launch profiles can be the bug.

When running an AppHost and you need follow-up commands, prefer start/wait/stop so the app stays available while you inspect it:

aspire start --project <path-to-apphost> --non-interactive
aspire wait
aspire ps
aspire describe
aspire logs <resource> --tail 100
aspire stop

If the issue involves the dashboard, use the runtime/plugin-provided playwright-cli skill when it is available to capture the dashboard state and reproduce the issue, including the page, telemetry export, relevant trace/log IDs, and browser console errors. If playwright-cli is unavailable, capture the same evidence with dashboard exports, Aspire CLI logs/traces or runtime aspire-monitoring when available, screenshots, and dashboard-testing for test-focused dashboard issues.

If it involves cloud deployment, record generated artifacts, resource group names, az/azd versions, and cleanup status.

Step 5: Reproduce and narrow the cause

Run the issue's repro steps against latest stable first unless the issue is explicitly about a specific version, install/update route, or PR build. Then vary one factor at a time:

1. Latest stable versus reported version/channel versus current main.
2. Current OS/shell versus reported OS/shell, escalating only when the mismatch plausibly explains the result.
3. Clean cache versus existing .aspire, package cache, template hive, node_modules, or container state.
4. Minimal AppHost versus the reported real project shape.
5. Interactive versus --non-interactive.
6. Installed CLI versus repo-local CLI.

Capture the command, exit code, and relevant output for each attempt. Prefer structured evidence over screenshots when possible: logs, aspire describe, distributed traces, test results, workflow artifacts, generated files, or package versions.

Do not stop after the first "could not reproduce" if the environment differs from the report in a meaningful way. Call out the mismatch and either try a closer environment or ask for the missing detail.

After a repro attempt reaches a clear result, present the evidence to the user and ask what they want to do next instead of taking action automatically. Offer choices that match the outcome:

• Investigate root cause — inspect the relevant code paths, tests, logs, and telemetry to explain why the reproduced behavior happens without making a fix yet.
• Make a fix — do not post an issue update; implement the targeted code/test change and open a PR once the issue is reproduced or the likely cause is strong enough.
• Update the issue — draft a GitHub issue comment with the investigation evidence.

Before offering to update the issue, prepare a comment draft and scrub it for PII and sensitive details. Do not include local usernames or home directory paths, machine names, tokens, private URLs, subscription IDs, resource group names that identify a customer or user, secrets, credentials, exact private repository paths, or raw logs that may contain any of those values. Replace sensitive paths with placeholders such as <scratch>, <repo>, or <redacted>, and summarize long logs instead of pasting them verbatim. Show the sanitized draft to the user first and ask for approval before posting.

Step 6: Investigation result format

End every investigation with a concise status and evidence:

Status: reproduced | not reproduced | blocked | design-only | duplicate/known
Issue: #<number> <title>
Area: <labels and likely code area>
Environment: <OS, CLI/SDK version, install route, runtime/cloud/browser details>
Repro: <exact commands or steps that matter>
Observed: <actual behavior with evidence>
Expected: <expected behavior from issue or docs>
Likely cause: <confirmed root cause or best hypothesis; say if unconfirmed>
Artifacts: <paths/links to logs, traces, screenshots, recordings, generated files>
Proposed issue comment: <sanitized draft shown to user, posted with approval, declined, or not needed>
Next action: <ask user to choose root-cause investigation, fix/PR, issue update, missing info, owner question, or validation path>

Be explicit about confidence. Use "confirmed" only when the evidence directly proves the cause. Use "hypothesis" when the behavior is reproduced but the code-level cause is not yet verified.

Step 7: If the user also asked for a fix

Only start implementation after reproduction or a strong evidence-backed root cause. Follow the repository instructions for the touched area, add or update targeted tests, and validate with the smallest command that exercises the bug. For flaky tests, quarantined tests, CI failures, deployment E2E, dashboard tests, CLI E2E, or PR-build testing, hand off to the specialized skill instead of duplicating its workflow.