Phase1 Advisor

The current architecture diagram (00_arch_current.html) scanned in Phase 0 already exists. In this case, skip the project name/service list confirmation in 1-1 and enter the modification conversation directly:

1. “What would you like to change here?” — User’s natural language request
2. Apply Delta Confirmation Rule — Confirm undecided required fields for the changes
3. Fact check — Cross-verify with MS Docs
4. Generate updated diagram (01_arch_diagram_draft.html)
5. Proceed to Phase 2 after confirmation

Goal of this Phase: Accurately identify what the user wants and finalize the architecture together.

1-1. Diagram Preparation — Gathering Required Information

Before drawing the diagram, ask the user questions until all items below are confirmed. Generate the diagram only after all items are confirmed.

First, confirm the project name:

Provide a default value as a choice via ask_user. If the user just presses Enter, the default is applied; they can also type a custom name. The default is inferred from the user’s request (e.g., RAG chatbot → rag-chatbot, data platform → data-platform).

The project name is used for the Bicep output folder name, diagram save path, deployment name, etc.

🔹 Parallel Preload Along with Project Name Question (Required):

When asking the project name via ask_user, there is idle time while waiting for the user to respond. Utilize this time to preload information needed for subsequent questions and Bicep generation in parallel.

Tools to call simultaneously with ask_user:

Benefits: While the user types the project name, all information is loaded, so SKU/region questions can be presented with accurate choices immediately after the project name is confirmed. Wait time is significantly reduced compared to sequential execution.

Notes:

• Preload targets are only information independent of the project name (nothing depends on the name)
• web_fetch is performed only for services mentioned in the user’s initial request (no guessing)
• Azure CLI check (az account show) is NOT done at this point — preload at architecture finalization

🔹 Utilizing Architecture Guidance (Adjusting Question Depth):

Extract design decision points from the architecture guidance documents fetched during preload, and naturally incorporate them into subsequent user questions.

Purpose: Not just spec questions like SKU/region, but reflecting design decision points recommended by official architecture guidance into the questions.

Example — When “RAG chatbot” is requested:

• Fetch Baseline Foundry Chat Architecture (A6)
• Extract recommended design decision points from the document: → Network isolation level (full private vs hybrid?) → Authentication method (managed identity vs API key?) → Data ingestion strategy (push vs pull indexing?) → Monitoring scope (Application Insights needed?)
• Naturally include these points in user questions

Notes:

• What is extracted from architecture guidance is “points to ask about”, not “answers”
• Deployment specs like SKU/API version/region are still determined only via azure-dynamic-sources.md
• Fetch budget: maximum 2 documents. No full traversal

Required confirmation items:

• Not done: Project name (default: azure-project)
• Not done: Service list (which Azure services to use)
• Not done: SKU/tier for each service
• Not done: Networking method (Private Endpoint usage)
• Not done: Deployment location (region)

Questioning principles:

• Do not ask again for information the user has already mentioned
• Do not ask about detailed implementation specifics not directly represented in the diagram (indexing method, query volume, etc.)
• Do not ask too many questions at once; ask only key undecided items concisely
• For items with obvious defaults (e.g., PE enabled), assume and just confirm. However, location MUST always be confirmed with the user
• When asking about SKUs, models, or service options, show ALL available choices verified from MS Docs, and provide the MS Docs URL as well. This allows the user to reference and make their own judgment. Do not show only partial options or arbitrarily filter them out

🔹 VM/Resource SKU Selection — Region Availability Pre-check Required:

Before asking the user about VM or other resource SKUs, you MUST first query which SKUs are actually available in the target region. If a SKU is blocked due to capacity restrictions in a specific region, the deployment will fail.

VM SKU verification method:

Principles:

• Do not include unverified SKUs in the choices
• Do not recommend “commonly used SKUs” from memory — MUST verify via az cli or MS Docs
• Include only verified SKUs in ask_user choices
• Even for user-provided SKUs, verify availability before proceeding

This principle applies equally not just to VMs, but to ALL resources subject to capacity restrictions (Fabric Capacity, etc.).

🔹 Service Option Exploration Principle — “Listing from Memory” is Prohibited:

When the user asks about a service category (“What Spark options are there?”, “What are the message queue options?”), or when you need to explore services for a specific capability:

NEVER do this:

• Directly fetch URLs for only 2-3 services from your memory and list them
• State definitively “In Azure, X has A and B”

MUST do this:

1. Explore the full category via web_search — Search at the category level like "Azure managed Spark options site:learn.microsoft.com" to first discover what services exist
2. Cross-check with v1 scope — Regardless of search results, check whether v1 scope services (Foundry, Fabric, AI Search, ADLS Gen2, etc.) fall under the relevant category. e.g.: “Spark” → Microsoft Fabric’s Data Engineering workload also provides Spark
3. Targeted fetch of discovered options — Fetch MS Docs for the services found via search to collect accurate comparison information
4. Present all options to the user — Present all discovered options in a comprehensive comparison without omitting any

Example — When asked “What Spark instances are available?”:

This principle applies not only to service category exploration, but to all situations where the user requests “alternatives”, “other options”, “comparison”, etc.

🔹 ask_user Tool — Mandatory Usage:

For questions with choices, you MUST use the ask_user tool. It allows users to select with arrow keys for convenience, and they can also type a custom input.

ask_user usage rules:

• Questions with 2 or more choices MUST use ask_user (do not list them as text)
• choices MUST be passed as a string array (["A", "B"]) — passing as a string ("A, B") will cause an error
• If there is a recommended option, place it first and append (Recommended) at the end
• Include reference information in choices — e.g., "Standard S1 - Recommended for production. Ref: https://..."
• Only 1 question per call — if multiple items need to be asked, call ask_user sequentially for each
• Choices are limited to a maximum of 4. If there are 5 or more, include only the 3-4 most common ones (users can also type a custom input)
• If multiple selections are needed, split them into separate questions

Items requiring ask_user:

• Deployment location (region) selection
• SKU/tier selection
• Model selection (chat model, embedding model, etc.)
• Networking method selection
• Subscription selection (Phase 1 Step 2)
• Resource group selection (Phase 1 Step 3)
• Any other question requiring a user choice

Usage examples:

Note: The SKU and region values in the examples above are for illustration only. When actually asking, dynamically compose choices based on the latest information by querying MS Docs via web_fetch. Do not hardcode.

Example — When user input is insufficient:

🚨🚨🚨 [HARD GATE] Spec Collection Complete → Diagram Generation Required 🚨🚨🚨

Immediately after all confirmed items are filled in, you MUST perform the following steps IN ORDER. Skipping any step means Phase 1 is incomplete.

1. Compose services JSON + connections JSON based on the confirmed service list
2. Use the built-in diagram engine to generate <project-name>/01_arch_diagram_draft.html
3. Automatically open it in the browser via Start-Process
4. Show the diagram to the user in the report format below — this MUST include a detailed configuration table
5. Ask the user: “Would you like to change or add anything?”
6. If the user has no changes → proceed to Phase 2 transition (ask_user with next step guidance)

NEVER do this:

• ❌ Not generating the diagram and asking “The architecture is confirmed. Shall we proceed to the next step?”
• ❌ Deferring diagram generation to Phase 2 or later
• ❌ Saying “I’ll create the diagram later”
• ❌ Declaring “architecture confirmed” based solely on spec collection completion
• ❌ Generating the diagram but NOT showing the configuration table
• ❌ Skipping the “anything to change?” question and jumping straight to Phase 2

Validation condition: Phase 2 entry is NOT allowed if the 01_arch_diagram_draft.html file has not been generated.

Report format after diagram completion (ALL sections are MANDATORY):

After showing the report, immediately use ask_user with choices:

• If “proceed” → move to Phase 2 transition (collect subscription/RG info)
• If “modify” or “add” → apply changes, regenerate diagram, show report again

🚨 The configuration table is NOT optional. The user needs to visually verify what was confirmed before proceeding. Without the table, the user cannot validate the architecture.

1-2. Interactive HTML Diagram Generation

Use the built-in diagram engine (Python scripts included in the skill) to create an interactive HTML diagram. No pip install is needed as the scripts are directly available in the scripts/ folder, requiring no network connection or package installation. 605+ official Azure icons are built in.

Diagram file naming convention:

All diagrams are generated inside the Bicep project folder (<project-name>/). They are systematically managed with numbered prefixes per stage, and previous stage files are never overwritten.

Built-in module path discovery + Python path discovery:

🚨 The Python path + built-in module path are verified once during Phase 1 preload, and reused for all subsequent diagram generations. Do NOT re-discover every time.

Python API method is also available (alternative):

When JSON is very large, you can directly call the Python API to avoid CLI argument length limitations. Add the scripts folder to sys.path to import the built-in module:

🔹 CLI vs Python API Selection Criteria:

Full list of supported service types:

Available in the skill’s built-in reference files under references/. Supported service type values are listed below in the services JSON format section.

Diagram generation order: (1) Verify Python path → (2) Verify built-in module path → (3) Compose services/connections JSON → (4) Execute. If Python is not installed, guide the user to install it before composing JSON. This prevents the waste of building JSON only to fail because Python is missing.

🚨 Automatic Diagram Open (No Exceptions): When an HTML file is generated with the built-in diagram engine, it MUST always be opened in the browser regardless of the situation. Without exception, whenever a diagram is (re)generated, execute the Start-Process command. Diagram generation and browser opening are always executed together in a single PowerShell command block.

When this applies (not just these, but ALL times an HTML diagram is generated):

• Phase 1 design draft (01_arch_diagram_draft.html)
• Diagram regeneration after Delta Confirmation
• Phase 4 What-if preview (02_arch_diagram_preview.html)
• Phase 4 deployment result (03_arch_diagram_result.html)
• Architecture changes after deployment (04_arch_diagram_update_draft.html)
• Any other case where a diagram is regenerated for any reason

services JSON format:

Dynamically composed based on the user’s confirmed service list. Below is the JSON structure description.

Service Type — Canonical Reference:

⚠️ CRITICAL: Always use the canonical type from the table below. Do NOT use Azure ARM resource names (e.g., private_endpoints, storage_accounts, data_factories). The generator normalizes common variants, but using canonical types ensures correct icon rendering, PE detection, and color coding.

When Using Private Endpoints — PE Node Addition Required:

If Private Endpoints are included in the architecture, a PE node MUST be added to the services JSON for each service, and connections must also include the PE links for them to appear in the diagram.

🚨🚨🚨 PE Connections and Business Logic Connections Are Separate — BOTH MUST Be Included 🚨🚨🚨

PE connections ("type": "private") represent network isolation. But this alone does NOT show the actual data flow/API calls between services in the diagram.

MUST include both types of connections:

1. Business logic connections — Actual data flow between services (api, data, security types)
2. PE connections — Network isolation between service ↔ PE (private type)

NEVER do this:

• Create only PE connections and omit business logic connections
• Connect from/to of business logic connections to PE nodes (use the actual service ID, not the PE)
• Assume “the PE is there so the connection line will show up”

The PE groupId differs by service. Refer to the PE groupId & DNS Zone mapping table in references/service-gotchas.md.

Service naming convention: MUST use the latest official Azure names. If uncertain about the name, verify with MS Docs. For resource types and key properties per service, refer to references/ai-data.md.

connections JSON format:

Connection Types:

🔹 Diagram Multilingual Principle:

• The name, details in services and label in connections are written in the user’s language
• Example: "label": "RAG Search", "label": "Data Ingestion"
• Official Azure service names (Microsoft Foundry, AI Search, etc.) are always in English regardless of language

🔹 VNet Node — Do NOT add to services JSON:

• VNet is automatically displayed as a purple dashed boundary in the diagram (when PEs are present)
• Adding a separate VNet node to services JSON causes confusion by duplicating with the boundary line
• VNet information (CIDR, subnets) is sufficiently conveyed through the sidebar VNet boundary label

Provide the full path of the generated HTML file to the user.

1-3. Finalizing Architecture Through Conversation

The architecture is finalized incrementally through conversation with the user. When the user requests changes, do NOT ask everything from scratch; instead, reflect only the requested changes based on the current confirmed state and regenerate the diagram.

⚠️ Delta Confirmation Rule — Required Verification on Service Addition/Change:

Service addition/change is not a “simple update” — it is an event that reopens undecided required fields for that service.

Process:

1. Diff the current confirmed state + new request
2. Identify the required fields for newly added services (refer to domain-packs or MS Docs)
3. Fetch the region availability/options for the service from MS Docs
4. If any required fields are undecided, ask the user via ask_user first
5. Regenerate the diagram only after confirmation is complete

NEVER do this:

• Finalize diagram update while required fields remain undecided
• Arbitrarily add sub-components/workloads the user did not mention (e.g., automatically adding OneLake and data pipeline to a Fabric request)
• Vaguely assume SKU/model like “F SKU” without confirmation

Do not re-ask settings for already confirmed services. Only confirm undecided items for newly added/changed services.

🚨🚨🚨 [Top Priority Principle] Immediate Fact Check During Design Phase 🚨🚨🚨

The purpose of Phase 1 is to confirm a “feasible architecture”. No matter what the user requests, before reflecting it in the diagram, you MUST fact-check whether it is actually possible by directly querying MS Docs via web_fetch.

Design Direction vs Deployment Specs — Separate Information Paths:

• Design direction comes from architecture guidance, actual deployment values from dynamic sources. Do not mix these two paths.
• Do NOT use Architecture guidance document content to determine SKU/API version/region.
• Do NOT crawl through all Architecture Center sub-documents for every request. Perform trigger-based targeted fetch of at most 2 relevant documents.
• For trigger/fetch budget/decision rules by question type, refer to architecture-guidance-sources.md.

This principle applies to ALL requests without exception:

• Model addition/change → Verify in MS Docs whether the model exists and can be deployed in the target region
• Service addition/change → Verify in MS Docs whether the service is available in the target region
• SKU change → Verify in MS Docs whether the SKU is valid and supports the desired features
• Feature request → Verify in MS Docs whether the feature is actually supported
• Service combination → Verify in MS Docs whether inter-service integration is possible
• Any other request → Fact-check with MS Docs

MS Docs verification results:

• Possible → Reflect in diagram
• Not possible → Immediately explain the reason to the user and suggest available alternatives

Fact Check Process — Cross-Verification Required:

Do not simply query once and move on for user requests. Cross-verification using other MS Docs pages/sources MUST always be performed.

GHCP Environment Constraint: Sub-agents (explore/task/general-purpose) do NOT have web_fetch/web_search tools. Therefore, verification requiring MS Docs queries MUST be performed directly by the main agent.

Fact Check Quality Standards — Be Thorough, Not Cursory:

• When a MS Docs page is fetched, check ALL relevant sections, tabs, and conditions without omission
• When checking model availability: Check ALL deployment types including Global Standard, Standard, Provisioned, Data Zone, etc. Do NOT conclude “not supported” based on only one deployment type
• When checking SKUs: Fully verify the feature list supported by that SKU
• If the page is large, fetch relevant sections multiple times to ensure accuracy
• If uncertain, query additional pages. NEVER answer based on guesswork

NEVER do this:

• Add to the diagram without verification
• Defer verification with “I’ll check during Bicep generation” or “It will be validated during deployment”
• Rely only on your memory and answer “it should work” — MUST directly query MS Docs
• Fetch MS Docs but rush to conclusions after only partially reading
• Finalize based on a single query — MUST cross-verify with another source

🚫 Sub-Agent Usage Rules:

Sub-agents in GHCP = task tool:

• agent_type: "explore" — Read-only tasks like codebase exploration, file search (web_fetch/web_search NOT available)
• agent_type: "task" — Command execution like az cli, bicep build
• agent_type: "general-purpose" — High-level tasks like complex Bicep generation

⚠️ Sub-agent tool constraint: ALL sub-agents (explore/task/general-purpose) CANNOT use web_fetch or web_search. Fact checks requiring MS Docs queries, API version verification, model availability checks, etc. MUST be performed directly by the main agent.

Foreground vs Background Decision Criteria:

• If results are needed before proceeding to the next step → mode: "sync" (default)
  • e.g., Query SKU list then provide choices to user, verify model availability then reflect in diagram
  • Running in background here would leave the user idle waiting for results
• If there is other independent work that can be done while waiting for results → mode: "background"
  • e.g., Simultaneously web_fetch multiple MS Docs pages for cross-verification

Most fact checks should be run in foreground (mode: "sync") because the next question cannot be asked without the results.

How to run cross-verification in parallel:

NEVER do this:

• Run in background when results are needed, then sit idle doing nothing while waiting
• Delegate tasks requiring web_fetch/web_search to sub-agents (main agent MUST perform directly)
• Attempt to directly read files internal to sub-agents

⚠️ Important: Do NOT execute any shell commands until the user explicitly approves proceeding to the next step. However, MS Docs web_fetch for the above fact checks is exceptionally allowed.

Once the architecture is confirmed (user said no changes to the diagram), ask the user whether to proceed to the next step.

🚨 Phase 2 Transition Prerequisites — ALL of the following must be met before asking this question:

1. 01_arch_diagram_draft.html has been generated using the built-in diagram engine
2. The diagram has been opened in the browser and displayed to the user in the report format with the configuration table
3. The user was asked “Would you like to change or add anything?” and responded with no changes, or modifications have been reflected and final confirmation is given

If ANY of the above conditions are not met, do NOT proceed to Phase 2. If the diagram does not exist yet, generate it right now — follow the procedure in section 1-2. If the configuration table was not shown, show it right now before asking about changes.

Following the parallel preload principle, execute az account list and az group list simultaneously with ask_user to prepare subscription/RG choices in advance.

ask_user display format:

Once the user approves, collect information in the following order. Since az account show + az account list + az group list were already completed during preload, subscription/RG choices can be presented immediately.

Step 1: Azure Login Verification

The az account show result is already available from preload. No additional call needed.

• If logged in → Move to Step 2
• If not logged in → Guide the user:

  Copy

  Azure CLI login is required. Please run the following command in your terminal:
  az login
  Please let me know once completed.

Step 2: Subscription Selection

The az account list result is already available from preload. No additional call needed.

Provide up to 4 subscriptions from the query results as ask_user choices. If there are 5 or more, include the 3-4 most frequently used subscriptions as choices (users can also type a custom input). Once the user selects, execute az account set --subscription "<ID>".

Step 3: Resource Group Confirmation

The az group list result is already available from preload. No additional call needed.

Provide up to 4 existing resource groups from the list as ask_user choices. If the user selects an existing group, use it as-is; if they type a new name as custom input, create it during Phase 4 deployment.

Required confirmed items:

• Not done: Service list and SKUs
• Not done: Networking method (Private Endpoint usage)
• Not done: Subscription ID (confirmed in Step 2)
• Not done: Resource group name (confirmed in Step 3)
• Not done: Location (confirmed with user — regional availability per service verified via MS Docs)

🚨 Phase 1 Completion Checklist — Required Verification Before Phase 2 Entry

Before leaving Phase 1, verify ALL items below. If any are incomplete, do NOT proceed to Phase 2.

⚠️ Do NOT ask item 6 while items 3-5 are incomplete. The flow must be: diagram → table → ask changes → confirm → next step.

Phase 2 Handoff: Bicep Generation Agent

Once the user agrees to proceed, read the references/bicep-generator.md instructions and generate the Bicep template. Alternatively, this can be delegated to a separate sub-agent.

Sensitive Information Handling Principle (NEVER violate):

• NEVER ask for VM passwords, API keys, or other sensitive values in chat, and NEVER store them in parameter files
• During code review, if sensitive values are found in plaintext in main.bicepparam, remove them immediately

🔹 User-Input Sensitive Values Like VM Passwords — Complexity Validation Required:

When the user inputs a VM admin password or similar, validate complexity requirements before sending to Azure. Azure VMs must satisfy ALL of the following conditions:

• 12 characters or more
• Contains at least 3 of: uppercase letters, lowercase letters, numbers, special characters

On validation failure: Do NOT attempt deployment; immediately ask the user to re-enter:

⚠️ The password does not meet Azure complexity requirements. It must be 12 characters or more and contain at least 3 of: uppercase + lowercase + numbers + special characters.

NEVER do this:

• Warn “it may not meet requirements” but attempt deployment anyway — MUST block
• Send to Azure without complexity validation, causing deployment failure

🚨 @secure() Parameter and .bicepparam Compatibility Principle:

When a .bicepparam file has a using './main.bicep' directive, additional --parameters flags CANNOT be used together with az deployment group what-if/create. Therefore, @secure() parameter handling follows these rules:

1. @secure() parameters MUST have default values — Use Bicep functions like newGuid(), uniqueString()

   bicepCopy

   @secure()
   param sqlAdminPassword string = newGuid()  // Auto-generated at deployment, store in Key Vault if needed

2. If there are @secure() parameters that require user-specified values:
   • Do NOT use .bicepparam file; instead use --template-file + --parameters combination
   • Or generate a separate JSON parameter file (main.parameters.json)

   powershellCopy

   # When .bicepparam cannot be used — substitute with JSON parameter file
   az deployment group what-if `
     --template-file main.bicep `
     --parameters main.parameters.json `
     --parameters sqlAdminPassword='user-input-value'

3. Do NOT use .bicepparam and --parameters simultaneously in a deployment command

   Copy

   ❌ az deployment group create --parameters main.bicepparam --parameters key=value
   ✅ az deployment group create --parameters main.bicepparam
   ✅ az deployment group create --template-file main.bicep --parameters main.parameters.json --parameters key=value

Decision criteria:

• All @secure() parameters have default values (newGuid, etc.) → .bicepparam can be used
• Any @secure() parameter requires user input → Use JSON parameter file instead of .bicepparam

When MS Docs fetch fails:

• If web_fetch fails due to rate limiting, etc., MUST notify the user:

  Copy

  ⚠️ MS Docs API version lookup failed. Generating with the last known stable version.
  Verifying the actual latest version before deployment is recommended.
  Shall we continue?

• Do NOT silently proceed with a hardcoded version without user approval

Pre-Bicep generation reference files:

• references/service-gotchas.md — Required properties, common mistakes, PE groupId/DNS Zone mapping
• references/ai-data.md — AI/Data service configuration guide (v1 domain)
• references/azure-common-patterns.md — PE/security/naming common patterns
• references/azure-dynamic-sources.md — MS Docs URL registry (for API version fetch)
• For services not covered in the above files, directly fetch MS Docs to verify resource types, properties, and PE mappings

Output structure:

Bicep mandatory principles:

• Parameterize all resource names — param openAiName string = 'oai-${uniqueString(resourceGroup().id)}'
• Private services MUST have publicNetworkAccess: 'Disabled'
• Set privateEndpointNetworkPolicies: 'Disabled' on pe-subnet
• Private DNS Zone + VNet Link + DNS Zone Group — all 3 required
• When using Microsoft Foundry, Foundry Project (accounts/projects) MUST be created alongside — without it, the portal is unusable
• ADLS Gen2 MUST have isHnsEnabled: true (omitting this creates a regular Blob Storage)
• Store secrets in Key Vault, reference via @secure() parameters
• Add English comments explaining the purpose of each section

Immediately transition to Phase 3 after generation is complete.

Phase 3 Handoff: Bicep Review Agent

Review according to references/bicep-reviewer.md instructions.

⚠️ Key Point: Do NOT just visually inspect and say “pass”. You MUST run az bicep build to verify actual compilation results.

1. Compilation errors/warnings → Fix
2. Checklist review → Fix
3. Re-compile to confirm
4. Report results (including compilation results)

For detailed checklists and fix procedures, see references/bicep-reviewer.md.

After review is complete, show the user the results before transitioning to Phase 4, and MUST guide the user on the next steps.

🚨 Required Report Format When Phase 3 Is Complete:

NEVER do this:

• Completing Phase 3 and just providing the az deployment group create command without further guidance
• Deploying directly without What-if validation, or telling the user to run commands themselves
• Skipping the Phase 4 steps (What-if → Preview Diagram → Deployment)