> **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.
# Plan Template
> Generate `.azure/vscode-debug-plan.md` using this template. This file is the
> **single source of truth** for the generation phase. The generation phase reads this plan and
> generates all artifacts from it — no re-scanning of the workspace is needed.
>
> The plan is generated directly from the workspace scan. The user reviews the plan,
> edits it as needed, then approves it before generation proceeds.
## ⛔ BLOCKING REQUIREMENT
You **MUST** create this plan file and get user approval BEFORE generating any configuration files.
---
## Markdown Table Integrity
When editing markdown tables with `replace_string_in_file` or `multi_replace_string_in_file`, always **read the file back** after the edit and verify that each table row is on its own line. Markdown tables require exactly one row per line — a missing newline between `|---|` and `| data |` breaks parsing completely.
**Post-edit verification rule:** After any edit to `.azure/vscode-debug-plan.md` that modifies a table, immediately read the affected lines back to confirm the table renders correctly (header, separator, and each data row on separate lines). If rows are concatenated, fix before proceeding.
---
## ⚠️ Mermaid Label Quoting — ALWAYS Quote Every Label
In the `## Architecture Diagram` mermaid block, **every node label and every edge label MUST be wrapped in double quotes.** This rule is unconditional — quote every label, every time, even when it looks harmless.
```mermaid
graph LR
%% ✅ CORRECT — every label quoted
API["Commerce API
Azure Functions :7071"] -->|"@azure/storage-blob"| AZ["Azurite
:10000"]
API -->|"pg"| PG[("PostgreSQL
:5432")]
%% ❌ WRONG — unquoted labels; the leading @ is a parse error
%% API[Commerce API
Azure Functions :7071] -->|@azure/storage-blob| AZ[Azurite]
```
**Why:** mermaid v11 uses `@` for edge-ID (`e1@-->`) and node-metadata (`id@{ shape: ... }`) syntax, so an `@` at the **start** of an unquoted label is lexed as a link ID and the whole diagram fails to parse with `Expecting 'AMP', 'COLON', ... got 'LINK_ID'`. Scoped npm package names (`@azure/storage-blob`, `@azure/identity`, `@prisma/client`) are the most common trigger, and they are exactly what shows up in Azure dependency edge labels. The debug-plan webview renders this block with mermaid — a parse error replaces the diagram with a raw `mermaid (error)` code block.
Quoting is always valid in mermaid and also protects labels containing `(`, `)`, `:`, `-`, `/`, `#`, or `·`. Do **not** try to detect which labels are "risky" — just quote all of them.
---
## Template
````markdown
# Azure Debug Plan
> This plan is the source of truth for generating the
> VS Code debug setup in this workspace.
>
> **Status:** {Planning | Approved | Executing | Implemented}
> **Execution Mode:** {Auto | Guided}
> **Created:** {ISO-8601 datetime}
> **Last Updated:** {ISO-8601 datetime}
>
>
>
---
## Prerequisites
| Tool / Extension | Category | Service(s) | Installed | Version |
|------------------|----------|------------|-----------|---------|
| {name} | {Runtime / Package manager / …} | {service(s) or *} | {✅/❓} | {version or —} |
> ⚠️ **Action required:** Confirm any tool or extension marked ❓ is installed and ready before approving this plan — rerun the recheck to confirm CLI tools provided by a version manager.
---
## Debug Configurations
Each checked row below produces a VS Code debug configuration in the `.vscode/launch.json`.
| Generate | Debug Config Name | Service Label | Service Root | Project Type | Runtime | Version | Azure Dependencies |
|----------|--------------------|---------------|--------------|--------------|---------|---------|-----|
| {[x] / [ ]} | {e.g. Payments API (debug)} | {label} | {path} | {type} | {runtime} | {version} | {comma-separated azure service labels} |
ℹ️ Project Type Descriptions
| Project Type | Description |
|-------------|-------------|
| {type} | {brief description of what this project type means} |
---
## Orchestrator
| Orchestrator | Container Runtime | Compose Command | Description |
|-------------|-------------------|-----------------|-------------|
| {Docker Compose / Podman Compose} | {Docker / Podman / Podman (Docker-compatible)} | {`docker compose` / `podman compose`} | {description} |
---
## Emulators
| Dependent Service | Emulator | Purpose |
|-------------------|----------|---------|
| {azure service label} | {emulator name} | {description of what this emulator provides} |
---
## Architecture Diagram
{One sentence describing how the app connects to its dependencies during debugging.}
```mermaid
graph LR
%% Generated from Debug Configurations + Emulators tables above.
%% Show each service as a node, each emulator as a node,
%% and edges for the Azure Dependencies that connect them.
%% MANDATORY: wrap EVERY node label and EVERY edge label in double quotes —
%% e.g. API["Commerce API
Azure Functions :7071"] -->|"@azure/storage-blob"| AZ["Azurite"]
%% An unquoted leading @ (scoped npm packages) is parsed as mermaid edge-ID
%% syntax and breaks the whole diagram. See "Mermaid Label Quoting" above.
```
---
## Migrations
When selected, the generation phase creates automated VS Code tasks that run migration scripts on launch — so emulator databases are automatically provisioned with the correct schema and seed data before the app starts debugging. No manual migration steps needed.
| Generate | Service | Migration Tool |
|----------|---------|---------------|
| {[x] / [ ]} | {service label} | {tool name, e.g. Prisma / Knex / Drizzle / EF Core} |
---
## API Test Collections
When selected, the generation phase produces lightweight, runnable API test scripts in the project so you can quickly smoke-test endpoints and triggers once everything is launched and connected locally.
| Generate | Service | Description |
|----------|---------|-------------|
| {[x] / [ ]} | {service label} | {collapsible lists of HTTP endpoints and/or triggers — see format below} |
---
## Convenience Scripts
| Generate | Script | Registered In | Description |
|----------|--------|---------------|-------------|
| {[x] / [ ]} | {script name} | {path to file where script is registered, e.g. ./package.json} | {what the script does} |