> **Important:** This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required. # Azure Debug Generate > **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE** > > This document is the **official, canonical source** for generating VS Code debug > configuration from an approved plan. You **MUST** follow these instructions > exactly as written. When in doubt, defer to this document. Do not improvise, > infer, or substitute steps. --- ## Global Rules (NO EXCEPTIONS) 1. **Plan is the source of truth** — Read `.azure/vscode-debug-plan.md` and generate exactly what it specifies. Only generate artifacts for rows where `Generate` is checked (`[x]`). 2. **Update plan progressively** — Mark steps complete as you go; update **Last Updated** timestamp on every status change 3. ❌ **Destructive actions require `ask_user`** — Always confirm before overwriting, deleting, or modifying existing files 4. **Preserve existing config** — Never silently overwrite project configuration files or `docker-compose.yml`. Merge or ask first. 5. **Scope — VS Code debug setup only** — These instructions are for generating local debug configurations in VS Code. Cloud architecture, IaC generation, provisioning, and deployment are handled by the **azure-deploy** agent through the complete **azure-app-onboard** pipeline. 6. **Warn on limited support** — When a project type, runtime, or emulator declared in the plan has no matching reference file, emit a `⚠️ LIMITED SUPPORT:` warning — [limited-support.md](references/limited-support.md). --- ## Autopilot mode **Active when** the invoking chat query begins with `[AUTOPILOT MODE]`, **or** `.azure/vscode-debug-plan.md` contains `executionMode: auto` or equivalent. When active, run fully unattended: - **Do NOT call `ask_user`.** This is the tail of an autopilot chain over a freshly generated project, so overwriting/merging the scaffolded config files is expected and safe — proceed without prompting (still preserve and merge existing configs rather than blindly overwriting). - Validation (Phase 3) still runs in full — autopilot never skips validation or the `Implemented` status write. Setting status to `Implemented` is what signals the workflow is complete (the extension restores its auto-approve setting at that point). --- ## Phase 1: Pre-Flight Verify the plan and environment before generating any files. | # | Action | Reference | |---|--------|-----------| | 1 | **Verify plan** — Confirm `.azure/vscode-debug-plan.md` exists with status `Approved`. Set status to `Executing` and update **Last Updated**. | `.azure/vscode-debug-plan.md` | | 2 | **Load references** — For each service in the plan's Services table (where Generate is checked), load the corresponding project-type and runtime reference files. If no reference file exists, emit a limited-support warning. | [limited-support.md](references/limited-support.md) | | 3 | **Run pre-flight checks** — Stale data directories and port conflicts. | [preflight.md](references/preflight.md) | --- ## Phase 2: Generate The plan drives implementation. Read each section of `.azure/vscode-debug-plan.md` and generate the corresponding artifacts. Use the reference files for implementation details — the plan specifies WHAT to generate, the references specify HOW. Follow the generation steps in [generate.md](references/generate.md) in order. --- ## Phase 3: Validate > ⚠️ **CRITICAL:** You MUST complete every validation step before proceeding. Do NOT mark the task as complete, do NOT set status to `Implemented`, and do NOT deliver a closing message until validation is finished and the checklist is updated with real results. | # | Action | Reference | |---|--------|-----------| | 1 | **Validate each launch configuration** — Follow every step in validation.md for each non-compound config. | [validation.md](references/validation.md) | | 2 | **Validate the compound configuration** — Faithfully run each compound's orchestration per validation.md § Step 9, never inferring the result from the individual configs. | [validation.md](references/validation.md) § Step 9 | | 3 | **Tear down validation processes** — Stop **every** process and emulator validation spawned (`docker compose down`) and verify all app HTTP, debug, and emulator ports are free again, so a subsequent user F5 starts from a clean slate. | [validation.md](references/validation.md) § Final Teardown | | 4 | **Update Debug Configuration Checklist** — Create or update the `## Debug Configuration Checklist` section in `.azure/vscode-debug-plan.md` with real ✅ or ❌ results for each configuration. | [validation.md](references/validation.md) § Plan Integration | | 5 | **Set status** — Only after every checklist stub has been replaced with a real result, set plan status to `Implemented` and update **Last Updated**. | `.azure/vscode-debug-plan.md` | > ⛔ **VALIDATION IS NOT OPTIONAL.** Do NOT set status to `Implemented` until every stub in the Debug Configuration Checklist has been replaced with a real ✅ or ❌ result. A checklist with any remaining stubs or missing entries means validation is incomplete — go back and finish it. This is the single most common failure mode. --- ## Outputs | Artifact | Location | |----------|----------| | **Plan** (updated) | `.azure/vscode-debug-plan.md` | | Docker Compose | `docker-compose.yml` | | VS Code Debug Config | `.vscode/launch.json` — see [project-types/](references/project-types/) and [runtimes/](references/runtimes/) | | VS Code Build Config | `.vscode/tasks.json` — see [project-types/](references/project-types/) and [runtimes/](references/runtimes/) | | VS Code Extensions | `.vscode/extensions.json` — see [generate.md](references/generate.md) § assembly protocol | | VS Code Settings | `.vscode/settings.json` — see [generate.md](references/generate.md) § assembly protocol | | Connection Strings | `local.settings.json` or `.env` | | Convenience Scripts | Runtime-specific script runner (see [runtimes/](references/runtimes/)) | | API Test Collections | `api-test-collections/{service-id}//invoke.{sh,ps1}` | --- ## Post-Generation After validation completes with status `Implemented`, **stop**. Do not present next steps or a closing message — the `azure-debug-generate` agent handles post-generation guidance and interactive next steps. ## Troubleshooting For Edge or Chrome related startup issues, consult [chromium.md](references/project-types/frontend-spa/debug-adapters/chromium.md).