diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f54e97ef..040f57b4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,6 +2,15 @@ This is a public repository for all of Azure Local Troubleshooting guides (TSGs), known issues and reporting feedback - this repo is intended to provide a central location for community driven supportability content. This is the material that is referenced by Customer Support Services when a ticket is created, by Azure Local engineering responding to an incident, and by users when self discovering resolutions to active system issues. +## Table of contents + +- [PR review guidelines and checklists](#pr-review-guidelines-and-checklists) +- [Applicability and automation metadata](#applicability-and-automation-metadata) +- [Language assistance guidelines](#language-assistance-guidelines) +- [PowerShell code guidelines](#powershell-code-guidelines) +- [Link guidelines](#link-guidelines) +- [New file guidelines](#new-file-guidelines) + ## PR Review Guidelines and Checklists ### Review Process Guidance - Focus on consistency with existing documentation and templates @@ -15,7 +24,7 @@ This is a public repository for all of Azure Local Troubleshooting guides (TSGs) ### Priority Review Areas When reviewing any document, prioritize checking these elements (in order of importance): 1. Safety issues (potentially harmful code) -2. Technical inaccuracies +2. Technical inaccuracies 3. Missing critical information 4. Structural improvements 5. Style and formatting issues (only if significantly impacting readability) @@ -33,6 +42,8 @@ Format each review comment with: - [ ] PowerShell examples include proper error handling - [ ] Version-specific information is clearly indicated - [ ] Prerequisites are accurate and complete + - [ ] Applicable Azure Local products, deployment modes, and supported versions are explicit + - [ ] Claims identify their evidence source and validation status - **Formatting and Structure** - [ ] Follows consistent markdown formatting for commands vs. outputs @@ -40,25 +51,41 @@ Format each review comment with: - [ ] Employs logical headings and subheadings - [ ] Contains Table of Contents for documents exceeding 3 sections - [ ] Code examples use consistent formatting and indentation + - [ ] Customer-facing prose contains no emoji - **User Experience** - [ ] Instructions are complete without assumptions of prior knowledge - [ ] Examples include realistic scenarios relevant to Azure Local - [ ] Links follow the guidelines (no version references in URLs) - [ ] Images are properly placed in an images/ subfolder + - [ ] Every action states the expected result and a stop condition for unexpected output + - [ ] The `azure-local-supportability/tsg-metadata/v1` marker is present and current #### Troubleshooting Guide (TSG) Checklist - [ ] Clear symptoms description at the beginning - [ ] Problem statement defines impact and scope +- [ ] Every administrator detection surface is shown or explicitly marked not evident - [ ] Diagnostic steps are in logical sequence - [ ] Resolution steps are distinct from diagnostic steps +- [ ] State-changing steps carry a [LOW RISK], [MEDIUM RISK], or [HIGH RISK] label +- [ ] Preconditions, workload impact, rollback, and escalation criteria are explicit - [ ] Verification steps confirm issue resolution - [ ] PowerShell code follows safety guidelines +- [ ] Causal claims are framed as evidence-backed contributing factors + +Use the administrator-surface states consistently: + +- `shown`: the article names the exact signal and where to find it. +- `not-evident`: an authoritative check with a stated scope, time window, or freshness basis shows + that this surface does not carry the issue. +- `absent`: the author has not characterized the surface. This is a documentation gap and is not + publish-ready evidence that the issue does not appear there. #### How-To Guide Checklist - [ ] Clear prerequisites section - [ ] Numbered step-by-step instructions - [ ] Each step has a single, clear action +- [ ] Each state-changing step includes risk, impact, expected result, and rollback - [ ] Verification steps follow configuration changes - [ ] Expected outcomes are clearly documented - [ ] Alternative approaches mentioned where applicable @@ -68,6 +95,60 @@ Format each review comment with: - [ ] Tables used for parameter/setting references - [ ] Examples provided for complex configurations - [ ] Default values clearly indicated +- [ ] Supported values, constraints, applicability, and validation methods are explicit + +## Applicability and automation metadata + +Every article template carries one hidden JSON marker with schema +`azure-local-supportability/tsg-metadata/v1`. Preserve it when creating an article and replace +its placeholders. The authoritative allowed values are in +[`tsg-metadata.schema.json`](../TSG/Templates/tsg-metadata.schema.json). The marker records: + +- Document type and applicable products +- Detector type and signal +- Validation fidelity level +- Technical grade, or `null` until TSG-FORGE produces one +- Reproduction substrate +- Automation status +- Last validation date and internal specification reference + +Do not place customer names, cluster names, subscription IDs, IP addresses, credentials, or other +environment-specific identifiers in this marker. + +Use these fidelity values consistently: + +| Level | Evidence required | +| --- | --- | +| L0 | Static structure, safety, and persona review only | +| L1 | Every diagnostic command exercised read-only | +| L2 | The real detector and remediation direction exercised with a safe proxy | +| L3 | The real failure and remediation exercised on an isolated scratch object | +| L4 | Full baseline, inject, detect, mitigate, and revalidate loop exercised live | + +Technical grade records the TSG outcome, not the cluster outcome: + +| Grade | Meaning | +| --- | --- | +| `null` | No TSG-FORGE technical grade has been established | +| A | The detector, discoverability, documented mitigation, and revalidation passed | +| B | The live loop passed, but documented discoverability is incomplete | +| C | Recovery required fallback automation or the failure detail was not actionable | +| F | The bad state was not detected or the documented mitigation did not restore service | + +Automation status is separate from execution surface: + +| Status | Meaning | +| --- | --- | +| `not-assessed` | No automation assessment has been completed | +| `scaffold` | Metadata exists, but executable automation is incomplete | +| `ready` | Automation is implemented and awaiting a qualifying live run | +| `proven` | Automation completed its declared validation loop | +| `blocked` | A named safety, access, or substrate requirement prevents the run | +| `manual` | The verification surface requires an operator | + +Execution surface describes where steps run. Use `on-device`, `mixed`, `cloud-diagnostic`, +`cloud-control`, or `thin`. `manual` is an automation status, not an execution surface. Do not +store execution-surface values in `validation.automation_status`. ## Language Assistance Guidelines When reviewing or suggesting language improvements (in order of importance): @@ -81,12 +162,16 @@ Frame language suggestions as "improvements" rather than "corrections" When reviewing or suggesting PowerShell code in documentation: - Pay special attention to commands that change environment state (e.g., restart, stop, remove, set, write). - For state-changing commands: + - Assign one canonical risk label: [LOW RISK], [MEDIUM RISK], or [HIGH RISK]. - Verify code is safe for production environments. - Implement defensive coding techniques (check conditions before taking action). But avoid excessive complexity. - - Include verification steps before and after changes. + - Include a pre-check, expected output, stop condition, rollback, and verification. - Ensure commands don't disrupt workloads. If they do, provide clear warnings. - Check for proper error handling. - Use placeholders like instead of hardcoded values. +- For read-only commands: + - Use [READ-ONLY] as the action type, not as a risk label. + - Record the risk label as not applicable because the command does not change state. Example: ```powershell @@ -113,6 +198,6 @@ Get-Service -Name "NonExistentService" ## New File Guidelines - Most new MD files should follow naming convention: --.md - Most new MD files should use one of the templates provided -- The table of contents in the component's README.md files should be updated when adding new content +- The component README.md inventory must be updated with the article type, applicable products, + owner, validation grade, automation readiness, and last validation date - Place images in an images/ subfolder within the relevant component - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 24ac64f9..f0658c66 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,6 +14,15 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. +## Table of contents + +- [Contribution process](#contribution-process) +- [Quick start](#quick-start-5-minutes) +- [Requirements](#requirements) +- [Detailed guidelines](#detailed-guidelines) +- [Need help](#need-help) +- [Additional resources](#additional-resources) + ## Contribution Process 1. **Fork** this repository @@ -55,10 +64,12 @@ Don't see a component? [See all components](./README.md#table-of-contents) 1. **Copy the template** from Step 1 2. **Replace placeholders** (marked with `{curly braces}`) -3. **Test all code examples** - they must be safe for production -4. **Save with correct naming**: `--.md` -5. **Update the component README.md** to list your new file -6. **Submit a pull request** with your changes +3. **Declare applicability**: products, deployment modes, versions, and exclusions +4. **Complete the hidden metadata marker**: detector, fidelity, substrate, and automation status +5. **Test all code examples**: they must be safe for production +6. **Save with correct naming**: `--.md` +7. **Update the component README.md** with validation and automation fields +8. **Submit a pull request** with evidence for every tested claim Reference [Markdown Snippets](./TSG/Templates/Markdown-Snippets.md) for helpful formatting tips, diagrams, and more. @@ -69,10 +80,14 @@ Reference [Markdown Snippets](./TSG/Templates/Markdown-Snippets.md) for helpful All PowerShell/scripts **MUST be safe for production** - Use placeholders like `` instead of real values -- Include verification steps after changes +- Label state-changing commands [LOW RISK], [MEDIUM RISK], or [HIGH RISK] +- Include a pre-check, expected output, stop condition, rollback, and verification - Add comments explaining what commands do - Test all examples before submitting +For a read-only command, use [READ-ONLY] as the action type and record risk as not applicable. +Do not label a non-mutating check [LOW RISK], because that blurs observation and state change. + ```powershell # Good: Check state before changing if ((Get-Service "ServiceName").Status -eq "Stopped") { @@ -83,6 +98,73 @@ if ((Get-Service "ServiceName").Status -eq "Stopped") { Start-Service "ServiceName" ``` +### Product applicability + +Verify product and version applicability against current public Microsoft documentation. State +what the article applies to and what it does not apply to. Consider Azure Local connected and +disconnected deployments, disaggregated deployments, multi-rack deployments, and any feature-specific +requirements. Do not infer applicability from a similar product or older release. + +### TSG automation metadata + +Every article created from a template includes one hidden +`azure-local-supportability/tsg-metadata/v1` JSON marker. Fill it in and keep it valid JSON. The +authoritative allowed values are in +[`tsg-metadata.schema.json`](./TSG/Templates/tsg-metadata.schema.json). The marker must identify: + +- Document type +- Applicable products +- Detector type and signal +- Validation fidelity level, from L0 through L4 +- Technical grade, or `null` until TSG-FORGE produces one +- Reproduction substrate +- Automation status +- Last validation date and the internal test specification reference, when available + +Use `null` for a validation date that has not been established. Never add customer or lab +identifiers to tracked metadata. + +Use the same fidelity scale for every article: + +| Level | Evidence required | +| --- | --- | +| L0 | Static structure, safety, and persona review only | +| L1 | Diagnostic commands exercised read-only | +| L2 | Real detector and remediation direction exercised with a safe proxy | +| L3 | Real failure and remediation exercised on an isolated scratch object | +| L4 | Full baseline, inject, detect, mitigate, and revalidate loop exercised live | + +Technical grade records the TSG outcome: + +| Grade | Meaning | +| --- | --- | +| `null` | No TSG-FORGE technical grade has been established | +| A | Detector, discoverability, documented mitigation, and revalidation passed | +| B | Live loop passed, but documented discoverability is incomplete | +| C | Recovery required fallback automation or failure detail was not actionable | +| F | The bad state was not detected or the documented mitigation did not restore service | + +Use `not-assessed`, `scaffold`, `ready`, `proven`, `blocked`, or `manual` for automation status. +Record `on-device`, `mixed`, `cloud-diagnostic`, `cloud-control`, or `thin` separately as the +execution surface. `manual` is an automation status, not an execution surface. + +### Evidence required in a pull request + +Include the following in the pull request description: + +1. Static structure and safety result +2. Commands or procedures exercised, with the environment class and product build +3. Expected and observed results +4. Rollback or cleanup result +5. Remaining automation blockers + +Maintainers run the TSG-FORGE persona and live-validation workflow. A static pass alone does not +prove that a remediation restores a cluster. + +For administrator detection surfaces, use `shown`, `not-evident`, or `absent`. A +`not-evident` claim requires an authoritative check with a stated scope, time window, or freshness +basis. `absent` means the surface is still uncharacterized and is a publication gap. + ## Detailed Guidelines
@@ -90,11 +172,11 @@ Start-Service "ServiceName" | Document Type | Purpose | Template | Structure | | ---------------- | ----------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------ | -| **Troubleshoot** | Help users fix specific errors or problems | [`Troubleshoot-Template.md`](./TSG/Templates/Troubleshoot-Template.md) | Symptoms → Root Cause → Resolution → Prevention | -| **Reference** | Provide configuration examples and settings | [`Reference-Template.md`](./TSG/Templates/Reference-Template.md) | Overview → Configuration → Examples → Validation | -| **How-To** | Step-by-step instructions | [`HowTo-Template.md`](./TSG/Templates/HowTo-Template.md) | Prerequisites → Steps → Verification → Next Steps | -| **Deep Dive** | Technical explanations and architecture details | [`DeepDive-Template.md`](./TSG/Templates/DeepDive-Template.md) | Overview → Technical Details → Examples → References | -| **Overview** | High-level introductions and summaries | [`Overview-Template.md`](./TSG/Templates/Overview-Template.md) | Introduction → Key Concepts → Architecture → Resources | +| **Troubleshoot** | Help users fix specific errors or problems | [`Troubleshoot-Template.md`](./TSG/Templates/Troubleshoot-Template.md) | Symptoms > Diagnosis > Contributing factors > Mitigation > Verification | +| **Reference** | Provide configuration examples and settings | [`Reference-Template.md`](./TSG/Templates/Reference-Template.md) | Overview > Configuration > Examples > Validation | +| **How-To** | Step-by-step instructions | [`HowTo-Template.md`](./TSG/Templates/HowTo-Template.md) | Prerequisites > Steps > Verification > Next steps | +| **Deep Dive** | Technical explanations and architecture details | [`DeepDive-Template.md`](./TSG/Templates/DeepDive-Template.md) | Overview > Technical details > Examples > References | +| **Overview** | High-level introductions and summaries | [`Overview-Template.md`](./TSG/Templates/Overview-Template.md) | Introduction > Key concepts > Architecture > Resources |
@@ -109,8 +191,8 @@ Type-Topic-Specifics.md **Examples:** -- `Troubleshoot-SDNExpress-HealthAlert-HostNotConnectedToController` -- `Reference-TOR-Disaggregated-Switched-Storage` +- `Troubleshoot-SDNExpress-HealthAlert-HostNotConnectedToController.md` +- `Reference-TOR-Disaggregated-Switched-Storage.md`
diff --git a/TSG/Templates/Component/CONTRIBUTING-Template.md b/TSG/Templates/Component/CONTRIBUTING-Template.md index 7645c4e1..c3733d3b 100644 --- a/TSG/Templates/Component/CONTRIBUTING-Template.md +++ b/TSG/Templates/Component/CONTRIBUTING-Template.md @@ -1,43 +1,235 @@ -# Contributing to Azure Local {COMPONENT_NAME} Documentation - - - -This document extends the [universal contribution guidelines](../Templates/CONTRIBUTING.md) with component-specific requirements. - -## Component-Specific Guidelines - - -{COMPONENT_SPECIFIC_GUIDELINES} - -## File Naming - -Follow the universal naming convention: `--.md` - -For this component (`{COMPONENT_NAME}`), use these specific topic areas, or create new ones as needed: - -### ``: - -- `{TOPIC_1}` - {TOPIC_1_DESCRIPTION} -- `{TOPIC_2}` - {TOPIC_2_DESCRIPTION} -- `{TOPIC_3}` - {TOPIC_3_DESCRIPTION} -- `{TOPIC_4}` - {TOPIC_4_DESCRIPTION} - -## Structure - -The repo is organized by major topic areas, you can add new files to existing folders or create new ones as needed. Here's a quick overview of the main folders: - - -| Folder | Description | -|---------------------------|----------------------------------------------------------------------| -| `{FOLDER_1}/` | {FOLDER_1_DESCRIPTION} | -| `{FOLDER_2}/` | {FOLDER_2_DESCRIPTION} | -| `{FOLDER_3}/` | {FOLDER_3_DESCRIPTION} | \ No newline at end of file +# Contributing to Azure Local {COMPONENT_NAME} Documentation + + + +This document extends the [repository contribution guide](../../CONTRIBUTING.md) with component-specific requirements for `{COMPONENT_NAME}`. + +Use this file to define how contributors should scope, validate, and review content for this component. Do not copy article-only sections such as Symptoms, Root Cause, or Resolution into this contribution guide. Instead, require authors to use the correct article template and to complete the checks below. + +## Table of Contents + +- [Fast Path: Copy, Lint, and PR Evidence](#fast-path-copy-lint-and-pr-evidence) +- [Component Scope and Applicability](#component-scope-and-applicability) +- [Required Article Metadata](#required-article-metadata) +- [Safe and Testable Authoring](#safe-and-testable-authoring) +- [Evidence, Validation, and Discoverability](#evidence-validation-and-discoverability) +- [File Naming](#file-naming) +- [Structure](#structure) +- [Before Opening a Pull Request](#before-opening-a-pull-request) +- [Need Help](#need-help) + +## Fast Path: Copy, Lint, and PR Evidence + +Use this path when turning the template into a component `CONTRIBUTING.md` and pull request (PR) evidence: + +1. Copy this file to `TSG/{ComponentName}/CONTRIBUTING.md` and customize all component-specific scope, topic, and folder entries. +2. Remove every instruction comment, `{curly brace}` placeholder, and `replace-me` value before the PR is ready for review. +3. Confirm the PR summary fields below are ready for a reviewer: + + | Field | PR-ready answer | + | --- | --- | + | Non-technical impact | What customer or operator problem this content helps with. | + | Owner and required sign-off | Component owner, support owner, partner, SI, or OEM reviewer. | + | Workload impact or downtime risk | None, possible disruption, maintenance window required, or unknown and blocked. | + | Technical grade and validation evidence | `validation.technical_grade`, TSG-FORGE report or spec evidence, lint result, link check, or not applicable with reason. | + | Remaining blockers | Open evidence, applicability, support-boundary, or owner questions. | + +4. Run source-branch lint from the repository that contains the changed markdown: + + ```bash + python3 --lint --tsg + ``` + + `` is the path to the TSG-FORGE `harness.py` script in the maintainer's checked-out tooling. Accepted output is `LINT (structure/safety component only) A` for this template, or a documented type false positive with the exact finding ID and reason. If the contributor cannot run TSG-FORGE locally, paste the command attempted, the error output, and a request for the maintainer to run the same lint before merge. + +5. Paste this evidence snippet into the PR description: + + ```text + Component owner: + Customer impact summary: + Workload impact or downtime risk: + Applicable products and supported versions: + validation.technical_grade: + TSG-FORGE report or spec evidence: + TSG-FORGE lint result: + Link check result: + Remaining blockers: + ``` + +The `../../CONTRIBUTING.md` link is intentional for the copied file at `TSG/{ComponentName}/CONTRIBUTING.md`. When reviewing this source template, validate that link in the copied component-file context. + +## Component Scope and Applicability + + + +Contributions for `{COMPONENT_NAME}` must declare the supported scope before any diagnostic or action steps are accepted: + +- **Applicable products**: Azure Local, plus any feature, extension, or component name this guidance applies to. +- **Supported versions**: Azure Local release, operating system build, solution build, Solution Builder Extension (SBE) version, firmware version, or driver version as applicable. Use `replace-me` until the exact range is known. +- **Operation phase**: Deployment, add node, update, upgrade, day-2 or post-deployment operations, or break/fix. +- **Topology and environment**: switchless or switched networking, storage type, Arc-connected state, Azure Kubernetes Service (AKS) Arc, Arc VMs, Original Equipment Manufacturer (OEM) family, or other component-specific topology. +- **Owner and handoff**: customer IT, partner or system integrator (SI), OEM vendor, Microsoft Customer Support Services (CSS), or product group. State when the issue is outside `{COMPONENT_NAME}`. +- **Support boundary**: prerequisites, unsupported configurations, or cases that need OEM or Microsoft support before proceeding. + +Completed mini-example: + +| Scope field | Completed sample | +| --- | --- | +| Component | Networking | +| Applicable products | Azure Local connectivity validation for Arc-connected clusters | +| Supported versions | Azure Local 23H2 and later, exact build range listed in each article | +| Operation phase | Deployment readiness and update readiness | +| Topology and environment | Switched or switchless, proxy mode, DNS forwarder, and outbound firewall path | +| Owner and handoff | Customer networking team for firewall or proxy, OEM vendor only when adapter firmware or driver support is involved | +| Support boundary | Stop when public endpoint allowlists, proxy credentials, or TLS inspection policy cannot be verified | + +### Component topic areas + + + +| Topic area | Use for | Applicability notes | +| --- | --- | --- | +| `OutboundConnectivity` | Firewall, proxy, DNS, and required endpoint access for Azure Local | Include topology, proxy mode, and Azure Local release or build. | +| `{TOPIC_1}` | {TOPIC_1_DESCRIPTION} | {TOPIC_1_APPLICABILITY} | +| `{TOPIC_2}` | {TOPIC_2_DESCRIPTION} | {TOPIC_2_APPLICABILITY} | +| `{TOPIC_3}` | {TOPIC_3_DESCRIPTION} | {TOPIC_3_APPLICABILITY} | +| `{TOPIC_4}` | {TOPIC_4_DESCRIPTION} | {TOPIC_4_APPLICABILITY} | + +Use this handoff matrix for cross-component cases: + +| Case | Primary owner or handoff | Article requirement | +| --- | --- | --- | +| Firmware, BIOS, driver, or hardware qualification | OEM vendor with Microsoft CSS as needed | Name model, firmware or driver range, and support-boundary evidence. | +| Solution Builder Extension package, model/SKU match, or solution extension content | OEM vendor or SBE publisher | Name SBE version, hardware family, and validation evidence. | +| Network symptom with storage, update, or compute impact | Start with the component whose evidence proves the failing layer | Explain why the issue is or is not in this component's lane. | +| VM workload drain, reboot, or live migration exposure | Customer workload owner and app or VM engineer | State workload impact, downtime risk, maintenance window, and validation plan. | +| Repeated site deployment variance | Partner or SI deployment owner | Record hardware family, topology, version variance, and reuse guidance for future sites. | + +## Required Article Metadata + +Component README files should index every article and include its title, document type, link, applicable products, supported versions, Highest action classification, Highest state-changing risk, workload impact or downtime risk, owner or handoff, metadata-marker status, validation fidelity, `validation.technical_grade`, TSG-FORGE report or spec evidence, reproduction substrate, automation status, execution surface, and last validated date. + +Each article that is created from an article template must contain one valid HTML-comment JSON marker that starts with the literal ` + +| Folder | Description | Required README entry | +| --- | --- | --- | +| `OutboundConnectivity/` | Proxy, DNS, firewall, and endpoint requirements for Azure Local connectivity. | Title, document type, link, applicable products, supported versions, Highest action classification, Highest state-changing risk, workload impact, owner, metadata-marker status, validation fidelity, `validation.technical_grade`, TSG-FORGE report or spec evidence, reproduction substrate, automation status, execution surface, last validated date. | +| `{FOLDER_1}/` | {FOLDER_1_DESCRIPTION} | {FOLDER_1_README_ENTRY_REQUIREMENT} | +| `{FOLDER_2}/` | {FOLDER_2_DESCRIPTION} | {FOLDER_2_README_ENTRY_REQUIREMENT} | +| `{FOLDER_3}/` | {FOLDER_3_DESCRIPTION} | {FOLDER_3_README_ENTRY_REQUIREMENT} | + +Place images in an `images/` subfolder under the relevant topic area. Use descriptive filenames and include alt text in the article. + +## Before Opening a Pull Request + +A component contribution is not ready for review until every item below is true: + +- The copied component `CONTRIBUTING.md` links to the repository contribution guide as `../../CONTRIBUTING.md`. +- The final file contains no `{curly brace}` placeholders and no authoring instruction comments. +- The component README indexes every new or changed article with title, document type, link, applicable products, supported versions, Highest action classification, Highest state-changing risk, workload impact, owner, metadata-marker status, validation fidelity, `validation.technical_grade`, TSG-FORGE report or spec evidence, reproduction substrate, automation status, execution surface, and last validated date. +- Every article uses the correct template and includes the required metadata marker from `../Templates/Markdown-Snippets.md` when it is an article template output. +- Every applicable product, supported version, operation phase, topology, owner, and support boundary is explicit. +- Every action uses [READ-ONLY] when no state changes or [LOW RISK], [MEDIUM RISK], or [HIGH RISK] when state may change, and includes pre-check, action, expected result/output, stop condition, rollback, and verification. +- Evidence is attached or cited in the PR: tested commands, expected outputs, logs, screenshots, Event IDs, telemetry samples, or source links as appropriate. +- Internal relative links resolve from the copied file location, and external links use public Microsoft documentation without release-specific query parameters. +- Public content contains no customer identifiers, secrets, tenant IDs, subscription IDs, private IP addresses, private support links, or internal-only URLs. +- Source-branch TSG-FORGE lint or review has been run on changed markdown. Fix real findings, record any type false positives with the reason, and include the result in the PR description. + +## Need Help + +- Use the repository contribution guide at [../../CONTRIBUTING.md](../../CONTRIBUTING.md) for universal process, CLA, document-type, and code-safety rules. +- Use Microsoft Learn for public Azure Local product references: . +- Ask the component owner when applicability, version support, risk, or support boundary is unclear. diff --git a/TSG/Templates/Component/README-Template.md b/TSG/Templates/Component/README-Template.md index 76b0c8a8..262083c7 100644 --- a/TSG/Templates/Component/README-Template.md +++ b/TSG/Templates/Component/README-Template.md @@ -1,33 +1,127 @@ -# TSG and Reference Documents for Azure Local {COMPONENT_NAME} +# Azure Local {COMPONENT_NAME} supportability index - + -## 📚 Table of Contents +## Directory inventory - + + +Use one row per support article. Every linked article must carry a valid HTML-comment metadata marker using schema `azure-local-supportability/tsg-metadata/v1`; this component index records that the marker exists and summarizes its routing fields, but does not embed article metadata itself. After copying this file to `TSG/{Component}/README.md`, use the schema at [`../Templates/tsg-metadata.schema.json`](../Templates/tsg-metadata.schema.json). + +### Inventory legend + +| Field | Required value | +| --- | --- | +| Article type | Record the article metadata `document_type`: `troubleshoot`, `reference`, `how-to`, `deep-dive`, or `overview`. To add another document type, extend `../Templates/tsg-metadata.schema.json` and add matching article-template guidance before using it in the index. | +| Title | Use the human-readable article title. | +| Link | Use a relative link to the article file. | +| Applicable products | Name the Azure Local product or feature family explicitly, for example `Azure Local 23H2 solution update`, `Arc VM management`, or `Storage Spaces Direct`. Do not use `all` unless the article truly applies to every Azure Local product path. | +| Supported versions | Name the supported release, build range, or `replace-me` until validated. | +| Owner | Name the accountable team, component owner, or alias. | +| Highest action classification | Use `[READ-ONLY]` when every action is non-mutating, `state-changing` when any action can change state, or `None, index-only` when the article has no actions. | +| Highest state-changing risk | Use the highest state-changing action risk label from the linked article: `[LOW RISK]`, `[MEDIUM RISK]`, or `[HIGH RISK]`. Use `Not applicable` for read-only-only or index-only articles. | +| Workload or maintenance impact | State whether the linked article can affect workloads, require a maintenance window, require elevated privileges, or is `None known`. | +| Metadata marker | Use `present` only after confirming the linked article contains the required metadata marker and validates against `../Templates/tsg-metadata.schema.json`. Otherwise use `missing` and fix the article before publishing. When `detector.type` is `none`, `detector.signal` must be JSON `null`; set both detector fields together when selecting another detector type. | +| Technical grade | Record the article metadata `validation.technical_grade`. Use `null` until TSG-FORGE produces `A`, `B`, `C`, or `F`; do not invent a grade from the README alone. | +| Validation evidence | Record the evidence pointer machine tooling or reviewers should read, for example the article metadata `validation.spec_ref`, a TSG-FORGE report name, or `None yet`. | +| Fidelity level | Record the article metadata `validation.fidelity_level`: `L0`, `L1`, `L2`, `L3`, or `L4`. | +| Reproduction substrate | Record the article metadata `validation.reproduction_substrate`: `vm`, `hardware`, `either`, or `none`. | +| Automation readiness | Record the article metadata `validation.automation_status`: `not-assessed`, `scaffold`, `ready`, `proven`, `blocked`, or `manual`. Use `manual` for intentionally human-run guidance and `blocked` only when automation is blocked by an unresolved dependency. | +| Execution surface | Keep this distinct from automation readiness. Use `on-device`, `mixed`, `cloud-diagnostic`, `cloud-control`, or `thin`. | +| Last validated | Use an ISO date such as `2026-08-17`, or `Not validated`. | + +For linked articles that include state-changing actions, confirm the article uses the canonical risk labels `[LOW RISK]`, `[MEDIUM RISK]`, or `[HIGH RISK]` and includes pre-check, action, expected result or output, stop condition, rollback, and verification steps. + +### Technical grade and automation rubric + +If older review text says validation grade, read it as the article metadata field `validation.technical_grade`. Do not create a separate grade value in this index. + +| Value | Meaning | +| --- | --- | +| `A` | TSG-FORGE evidence shows the article is complete for its type, safety gates are present, metadata is valid, links resolve, and lint is clean. | +| `B` | Usable, but non-blocking gaps remain, such as missing optional evidence or a documented false-positive warning. | +| `C` | Incomplete validation, fallback-only validation, missing required routing metadata, or unclear automation readiness. | +| `F` | Structural, safety, metadata, or command defect that must block publishing. | +| `null` | `validation.technical_grade` stays JSON `null` until TSG-FORGE produces `A`, `B`, `C`, or `F`. | +| `L0` | Static-only validation, such as metadata, lint, link, and persona review. | +| `L1` | Read-only diagnostic commands or evidence collection were validated. | +| `L2` | A reversible proxy, mocked input, or faithful data-source validation was used. | +| `L3` | A scratch object or isolated test object reproduced the failure and recovery path. | +| `L4` | Full live inject, detect, mitigate, and revalidate loop was proven on a lab substrate. | +| `not-assessed` | Automation readiness has not been reviewed. | +| `scaffold` | Automation metadata exists, but runnable automation is not built. | +| `ready` | Automation is designed and ready for validation, but not yet proven. | +| `proven` | Automation was validated with evidence. | +| `blocked` | Automation cannot proceed until a named dependency is resolved. | +| `manual` | The article intentionally requires a human action or judgment. | +| `vm`, `hardware`, `either`, `none` | Reproduction substrate values from the metadata schema. | +| `on-device` | Executable steps run on an Azure Local node. | +| `mixed` | Steps span on-device and cloud or control-plane surfaces. | +| `cloud-diagnostic` | Diagnostic evidence comes from cloud telemetry or service data. | +| `cloud-control` | Actions or checks run through Azure control-plane, portal, or ARM surfaces. | +| `thin` | No executable diagnostic or remediation surface is present. | ### {TOPIC_AREA_1} -- [{DOC_TYPE}: {DOC_TITLE}]({FOLDER_NAME}/{FILE_NAME}.md) +| Article type | Title | Link | Applicable products | Supported versions | Owner | Highest action classification | Highest state-changing risk | Workload or maintenance impact | Metadata marker | Technical grade | Validation evidence | Fidelity level | Reproduction substrate | Automation readiness | Execution surface | Last validated | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| {DOC_TYPE} | {DOC_TITLE} | [{FILE_NAME}.md]({FOLDER_NAME}/{FILE_NAME}.md) | {APPLICABLE_PRODUCTS} | {SUPPORTED_VERSIONS} | {OWNER} | {[READ-ONLY], state-changing, or None, index-only} | {[LOW RISK], [MEDIUM RISK], [HIGH RISK], or Not applicable} | {WORKLOAD_OR_MAINTENANCE_IMPACT} | {present or missing} | {A, B, C, F, or null} | {SPEC_REF, report name, PR evidence, or None yet} | {L0, L1, L2, L3, or L4} | {vm, hardware, either, or none} | {not-assessed, scaffold, ready, proven, blocked, or manual} | {on-device, mixed, cloud-diagnostic, cloud-control, or thin} | {YYYY-MM-DD or Not validated} | + - Replace {APPLICABLE_PRODUCTS} with explicit Azure Local product or feature scope + - Replace {SUPPORTED_VERSIONS} with the supported release or build range + - Replace {OWNER} with the accountable team, component owner, or alias + - Replace {[READ-ONLY], state-changing, or None, index-only} with the linked-article action classification + - Replace {[LOW RISK], [MEDIUM RISK], [HIGH RISK], or Not applicable} with the highest linked-article state-changing risk + - Replace {WORKLOAD_OR_MAINTENANCE_IMPACT} with workload, privilege, maintenance-window, or downtime impact + - Replace {present or missing} after checking the article metadata marker + - Replace {SPEC_REF, report name, PR evidence, or None yet} with the validation evidence source + - Replace {L0, L1, L2, L3, or L4} with the metadata fidelity level + - Replace {vm, hardware, either, or none} with the metadata reproduction substrate + - Replace {YYYY-MM-DD or Not validated} with the latest validation date or Not validated + Repeat this row pattern for each document in the topic area --> ### {TOPIC_AREA_2} -- [{DOC_TYPE}: {DOC_TITLE}]({FOLDER_NAME}/{FILE_NAME}.md) +| Article type | Title | Link | Applicable products | Supported versions | Owner | Highest action classification | Highest state-changing risk | Workload or maintenance impact | Metadata marker | Technical grade | Validation evidence | Fidelity level | Reproduction substrate | Automation readiness | Execution surface | Last validated | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| {DOC_TYPE} | {DOC_TITLE} | [{FILE_NAME}.md]({FOLDER_NAME}/{FILE_NAME}.md) | {APPLICABLE_PRODUCTS} | {SUPPORTED_VERSIONS} | {OWNER} | {[READ-ONLY], state-changing, or None, index-only} | {[LOW RISK], [MEDIUM RISK], [HIGH RISK], or Not applicable} | {WORKLOAD_OR_MAINTENANCE_IMPACT} | {present or missing} | {A, B, C, F, or null} | {SPEC_REF, report name, PR evidence, or None yet} | {L0, L1, L2, L3, or L4} | {vm, hardware, either, or none} | {not-assessed, scaffold, ready, proven, blocked, or manual} | {on-device, mixed, cloud-diagnostic, cloud-control, or thin} | {YYYY-MM-DD or Not validated} | +## Maintenance checklist + +- Update this index whenever an article is added, moved, renamed, re-owned, re-validated, or converted for automation. +- Keep applicable products and supported versions explicit in every row. +- Keep the owner field current so support, partner, OEM, and engineering readers know where to route follow-up. +- Keep action classification, state-changing risk, workload or maintenance impact, technical grade, validation evidence, fidelity level, reproduction substrate, automation readiness, execution surface, and last validated aligned with the linked article metadata and latest validation evidence. +- Use only public Microsoft links for external references in public article rows. + +## Before submitting this copied README + +Use this gate after copying the template to `TSG/{Component}/README.md`. + +| Check | Pass condition | +| --- | --- | +| Placeholders and instructions | No `{PLACEHOLDER}` values or ` - -# {Title} - - - - - - - - - - -
Component{Component Name}
Topic{Topic Name}: {Brief description of the topic}
- -## Overview - -{Brief description of what is covered in this document} - -## Table of Contents - -{Update Table of Contents as needed} - -- {Deep Dive Area 1} - -## {Deep Dive Topic} - -{Deep Dive templates should give the reader a better understanding of the topic. This template is very flexible.} - -### {Sub Topic 1} - ---- + + + + +# {Title} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Document typeDeep Dive
Purpose{State what the reader will understand or decide after reading this article.}
Applicable products{List the Azure Local products, features, components, or OEM platforms this article applies to.}
Supported versions{List supported Azure Local releases, OS builds, extension versions, firmware versions, or state "not version-specific" with why.}
Component{Component name}
Topic{Topic name and brief description.}
Audience{Primary readers, such as customer admin, Microsoft Customer Support Services (CSS) engineer, partner deployment engineer, original equipment manufacturer (OEM) engineer, or architect.}
Severity or risk posture{Use "informational" for explanation-only content. If any action changes state, label each action with [LOW RISK], [MEDIUM RISK], or [HIGH RISK].}
Last reviewed{YYYY-MM-DD}
+ +## Overview + +{Summarize the topic in 3 to 5 sentences. Explain why the topic matters, what problem or decision it helps with, and what the reader should be able to do after reading.} + +## Reader routing and publish gate + +Use this section as the one-screen summary for leaders, field engineers, workload owners, and specialists who need to decide what to do next before reading the deep details. + +### Publish-before-use checklist + +Do not publish or run copied actions from this template until every item is complete. + +| Gate | Required before publishing | +| --- | --- | +| Placeholders removed | Search for brace placeholders such as `{Title}` and replace every one with article-specific content. Do not publish while any placeholder remains. | +| Products and versions explicit | Fill in applicable products and supported versions. Include at least one explicit out-of-scope version, topology, or product case. | +| Public-link hygiene | Use public Microsoft Learn or Microsoft documentation links only. | +| Metadata marker valid | Keep exactly one `azure-local-supportability/tsg-metadata/v1` marker and update it if the article gains a detector or validation evidence. | +| Metadata schema checked | Validate the marker against the public schema. The schema lives at [`tsg-metadata.schema.json`](tsg-metadata.schema.json) in the template folder. After copying this article, use the copied file's relative path back to the schema: component root uses `../Templates/tsg-metadata.schema.json`, one nested topic folder uses `../../Templates/tsg-metadata.schema.json`, and each additional nested folder adds one `../`. | +| Safety contract complete | Every action has an action type, required privilege, workload or maintenance gate, pre-check, action, expected result or output, stop condition, rollback with expected output, rollback verification, final verification, and escalation target. State-changing actions also have a [LOW RISK], [MEDIUM RISK], or [HIGH RISK] label. | +| Evidence sanitized | Remove customer identifiers, secrets, private tenant values, internal URLs, and lab-only names from examples and artifacts. | + +### Choose the right template + +| Reader need | Use this template? | Use instead | +| --- | --- | --- | +| Explain how an Azure Local mechanism works, what evidence proves it, and where the boundaries are. | Yes. Use Deep Dive. | Not applicable. | +| Detect and resolve a specific failure or validator result. | No. | Troubleshoot template. | +| Perform a task through ordered steps. | No, unless the steps are only examples inside a broader explanation. | How-To template. | +| List settings, limits, defaults, or parameters. | No, unless the reference data supports a mechanism explanation. | Reference template. | +| Introduce a broad component or feature at a high level. | No. | Overview template. | + +### One-screen decision summary + +| Decision field | Author prompt | +| --- | --- | +| Customer capability gained | {State what the customer can understand, decide, prevent, or operate after reading.} | +| Business or workload impact | {State whether the topic can affect virtual machine (VM) availability, storage, networking, updates, security posture, deployment, or customer operations.} | +| Workload owner view | {State whether workload owners should expect downtime, live migration, restart, drain, degraded performance, or no workload impact.} | +| Downtime and maintenance window | {State expected downtime, maintenance-window need, rough duration, and the reason. Use "none expected" only when evidence supports it.} | +| Primary owner | {Name the likely owner, such as customer IT, Microsoft Customer Support Services (CSS), partner or system integrator (SI), Microsoft engineering, original equipment manufacturer (OEM) vendor, or network team.} | +| Handoff lane | {State how a reader proves this is their lane or not their lane, then name the next owner and the evidence to hand off.} | +| Fastest safe next action | {Give the first read-only check or decision that unblocks the customer fastest.} | +| Stop and escalate when | {List the first condition that should stop self-service and trigger Microsoft Support, partner, OEM, or product-group escalation.} | +| Multi-node or multi-site repeatability | {State whether the guidance applies per node, per cluster, per site, or per fleet, plus batching guidance and the validation loop to repeat after each batch.} | + +## Scope and non-goals + +| Area | Guidance | +| --- | --- | +| In scope | {List the concepts, scenarios, signals, and products covered.} | +| Out of scope | {List adjacent areas this article does not cover and point to public Microsoft documentation when available.} | +| Applies when | {Describe the product state, deployment phase, topology, or configuration where this explanation is valid.} | +| Does not apply when | {Describe clear exclusions so readers do not apply the guidance to the wrong product, version, or topology.} | + +## Prerequisites and assumptions + +| Prerequisite | Required value or condition | How to check | +| --- | --- | --- | +| Product and supported versions | {Example: Azure Local {release or later}.} | {How the reader confirms the product and version.} | +| Example, product and version | Azure Local 23H2 or later, if applicable to the topic. | In Azure portal, open the Azure Local cluster Overview page and record the reported version. | +| Permissions | {Required role or local privilege.} | {How to verify access before continuing.} | +| Tools | {Required tools, portals, PowerShell modules, or logs.} | {How to confirm the tool is present and current.} | +| Cluster or workload state | {Required health, maintenance, workload, or connectivity state.} | {Read-only pre-check.} | +| Required artifacts | {Logs, screenshots, configuration exports, or evidence needed.} | {Where to collect them.} | + +## Table of contents + +- [Overview](#overview) +- [Reader routing and publish gate](#reader-routing-and-publish-gate) +- [Scope and non-goals](#scope-and-non-goals) +- [Prerequisites and assumptions](#prerequisites-and-assumptions) +- [Architecture and technical details](#architecture-and-technical-details) +- [Evidence and observability](#evidence-and-observability) +- [Case-ready evidence and source authority](#case-ready-evidence-and-source-authority) +- [Operational boundaries and safety](#operational-boundaries-and-safety) +- [Action pattern, if this article includes steps](#action-pattern-if-this-article-includes-steps) +- [Validation](#validation) +- [Future test automation metadata](#future-test-automation-metadata) +- [References](#references) + +## Architecture and technical details + +{Explain the mechanism, architecture, data flow, trust boundary, control plane, data plane, dependencies, and important failure modes. Keep this section explanatory. Move step-by-step remediation to the action pattern section when applicable.} + +### Key concepts and definitions + +| Term | Definition | Why it matters | +| --- | --- | --- | +| {Term} | {Definition in plain language.} | {How this affects the reader's decision or operation.} | + +### Dependency map + +| Dependency | Direction | Required state | Timeout or degraded behavior | Failure mode | Evidence source | +| --- | --- | --- | --- | --- | --- | +| {Dependency name} | {Inbound, outbound, local, cluster, Azure control plane, or OEM.} | {Expected healthy state.} | {Expected timeout, retry, stale-data, or degraded-state behavior.} | {How this dependency fails and what component sees the failure first.} | {Log, cmdlet, portal surface, or public documentation source.} | + +## Evidence and observability + +Use this section to explain where the concept can be observed. Use admin surface states exactly as `shown`, `not-evident`, or `absent`: `shown` means the surface carries useful evidence, `not-evident` means the surface was checked and is not expected to show this topic, and `absent` means the author has not characterized the surface yet. Articles with `absent` surfaces are not publish-ready. + +| Surface | State | What to look for | Expected healthy signal | Abnormal or important signal | Limitations | +| --- | --- | --- | --- | --- | --- | +| PowerShell on an Azure Local node | {shown, not-evident, or absent} | {Get-* or Invoke-* command, if applicable.} | {Expected output.} | {Unexpected output.} | {Permissions, timing, or version limits.} | +| Azure portal | {shown, not-evident, or absent} | {Azure Local, Arc, resource health, updates, or other blade.} | {Expected status.} | {Unexpected status.} | {Portal refresh or data delay.} | +| Windows event logs | {shown, not-evident, or absent} | {Log name, provider, and Event ID.} | {Expected event or absence.} | {Important event.} | {Retention and clock-skew limits.} | +| Example, Windows event logs | shown | Event Viewer or `Get-WinEvent` for a named provider and Event ID. | The event is absent, informational, or matches the documented healthy state. | The event appears within the article's time window with the documented abnormal value. | Event logs can roll over and node clocks can differ. | +| Cluster logs | {shown, not-evident, or absent} | {Relevant `Get-ClusterLog` component or state.} | {Expected entry or not-evident rationale.} | {Unexpected entry.} | {Collection window and noise limits.} | +| Windows Failover Cluster Manager | {shown, not-evident, or absent} | {Role, resource, network, or node view.} | {Expected status or not-evident rationale.} | {Unexpected status.} | {May not show component-specific state.} | +| Windows Admin Center on a standalone host | {shown, not-evident, or absent} | {Where to check.} | {Expected status or not-evident rationale.} | {Unexpected status.} | {Extension and version limits.} | +| Windows Admin Center in the Azure portal | {shown, not-evident, or absent} | {Where to check.} | {Expected status or not-evident rationale.} | {Unexpected status.} | {Access and refresh limits.} | +| Component or tool log files on disk | {shown, not-evident, or absent} | {Path to component logs or generated reports.} | {Expected entry.} | {Unexpected entry.} | {Log rotation and privacy considerations.} | + +## Case-ready evidence and source authority + +Use this section when the article may support a support case, escalation, partner handoff, or OEM handoff. + +### Evidence package checklist + +| Artifact type | Collect | Sanitize before sharing | Used for | +| --- | --- | --- | --- | +| Timeline | {Coordinated Universal Time (UTC) start time, detection time, action time, and recovery time.} | {Remove personal names unless needed for support routing.} | {Correlates symptoms, actions, and validation.} | +| Product and version evidence | {Azure Local version, OS build, extension version, firmware or driver version if relevant.} | {Remove serial numbers unless the OEM support path requires them.} | {Confirms applicability and supported versions.} | +| Observability output | {Logs, events, command output, portal status, or screenshots named in the evidence table.} | {Remove tenant IDs, subscription IDs, secrets, and customer-specific names.} | {Confirms the scenario and rules out adjacent causes.} | +| Configuration snapshot | {Relevant settings before and after an action.} | {Remove credentials, keys, tokens, and private endpoints.} | {Proves pre-check, rollback, and verification states.} | +| Handoff summary | {Owner, lane, stop condition reached, and requested decision.} | {Keep only information needed for the next owner.} | {Prevents the next team from repeating discovery work.} | + +### Source-of-truth table + +| Mechanism claim | Evidence authority | Validation status | Notes | +| --- | --- | --- | --- | +| {Important mechanism, dependency, boundary, or limitation.} | {Public Microsoft documentation, product output, command output, event log, or lab validation.} | {Validated, partially validated, not validated, or not applicable.} | {What would disprove the claim or where it does not apply.} | + +### Ownership and vendor boundary + +| Boundary | Microsoft-owned evidence | OEM, partner, or customer-owned evidence | Handoff criteria | +| --- | --- | --- | --- | +| Product behavior | {Azure Local documentation, Azure portal status, PowerShell output, or event logs.} | {Customer configuration or partner deployment notes.} | {Escalate to Microsoft Support when product output contradicts documented behavior or the stop condition is reached.} | +| Hardware or firmware | {Azure Local signals showing the hardware-facing symptom, if any.} | {Firmware setting, BIOS setting, baseboard management controller (BMC) logs, driver package, qualified configuration, or OEM support bundle.} | {Hand off to the OEM when the required evidence points to firmware, driver, device health, or unsupported hardware state.} | +| Network or site infrastructure | {Azure Local network symptoms and affected nodes or adapters.} | {Switch configuration, firewall policy, Domain Name System (DNS), proxy, cabling, or site routing evidence.} | {Hand off to the network or site owner when Azure Local evidence shows dependency failure outside the cluster.} | + +## Operational boundaries and safety + +{Explain whether this Deep Dive is explanation-only or includes operational actions. If it includes actions, keep them safe for production and use the action pattern below.} + +- Risk labels: use exactly one of [LOW RISK], [MEDIUM RISK], or [HIGH RISK] for every action that may change state. +- Required privilege and security impact: {State the least privilege needed and whether the action touches identity, Role-Based Access Control (RBAC), certificates, firewall rules, secrets, or tenant resources.} +- Workload impact: {State whether the action can affect virtual machines (VMs), storage, networking, updates, quorum, Azure Arc connectivity, or customer workloads. Quorum means the cluster vote majority needed to keep cluster services online. Azure Arc is the Azure management connection for hybrid resources.} +- Maintenance and approval gate: {State whether a maintenance window, change approval, customer approval, or workload-owner approval is required before any state-changing action.} +- Do-not-proceed gates: {List conditions where the reader must stop and collect more evidence or escalate.} +- Rollback or recovery boundary: {Explain what can be undone, what cannot be undone, and who owns recovery.} +- Escalation: {State when to contact Microsoft Support, the product group, a partner, or an OEM vendor.} + +## Action pattern, if this article includes steps + +If this Deep Dive includes any command, configuration change, portal action, or mitigation example, use this pattern for each action. Do not omit any column. + +| Step | Action type | Risk label | Required privilege and security impact | Workload or maintenance gate | Pre-check | Action | Expected result or output | Stop condition and escalation | Rollback and expected rollback output | Rollback verification | Final verification | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| {Step name} | {[READ-ONLY] or state-changing.} | {Not applicable for [READ-ONLY]. For state-changing actions, use [LOW RISK], [MEDIUM RISK], or [HIGH RISK].} | {Least privilege required and security posture touched, such as RBAC, certificate, firewall, identity, or secret.} | {Maintenance window, customer approval, workload-owner approval, or "none expected" with evidence.} | {Read-only check that proves the action is applicable and safe.} | {One action only. Use placeholders, not real customer values.} | {Exact success output, status, or observable result.} | {Condition that means stop, do not retry blindly, and escalate or gather more evidence, plus the escalation owner.} | {How to undo the action or recover safely, and the expected rollback output or status.} | {Read-only check proving rollback restored the prior state.} | {Read-only check that confirms the intended state.} | +| Example, read-only inventory | [READ-ONLY] | Not applicable. | Reader access to the target cluster, no security posture change. | No maintenance window expected because the action is read-only. | Confirm the reader has the required role and is connected to the intended cluster. | Run the read-only inventory command or open the documented portal blade. | Output shows the product, version, component state, and timestamp described in this article. | Output is missing, stale, from the wrong cluster, or shows an unexpected state that changes the scenario. Escalate to the article owner or Microsoft Support with the evidence package. | No rollback needed for read-only inventory. Expected rollback output is not applicable. | Not applicable because no state changed. | Repeat the same read-only check after any later action and compare the timestamp and state. | + +## Validation + +{State how the article was validated. Include what was tested, what was not tested, and how a reader can validate the claims in their environment.} + +| Claim or procedure | Validation method | Result | Evidence | Gaps | +| --- | --- | --- | --- | --- | +| {Claim, explanation, or action.} | {Documentation review, lab run, command output, log evidence, or not validated.} | {Pass, fail, not applicable, or not assessed.} | {Public documentation link, sanitized output, or artifact reference.} | {Known uncertainty or future validation needed.} | + +### Verify the fix or validate the guidance + +{For explanation-only content, describe how the reader validates that they understood the topic and selected the right next step. For operational content, describe the final read-only verification that proves the action reached the intended state.} + +## Future test automation metadata + +Use this section to make future TSG-FORGE automation possible. Keep placeholders until the article is assessed. + +| Field | Value | +| --- | --- | +| Automation candidate | {yes, no, or unknown.} | +| `detector.type` | {none, envchecker, eventlog, command, service, feature, registry, telemetry, manual, portal, or control-plane.} | +| Detector signal | {Exact check name, Event ID, command, service, feature, registry key, telemetry table, or manual surface.} | +| `validation.reproduction_substrate` | {none, vm, hardware, or either. Use only these schema values.} | +| Special fixture note | {Plain-language detail for a lab fixture, scratch object, cluster shape, or manual condition, if any. This is not a `validation.reproduction_substrate` value.} | +| Current fidelity level | {L0, L1, L2, L3, or L4.} | +| Technical grade | {Use null in the JSON metadata marker until TSG-FORGE produces A, B, C, or F. This is the authoritative technical grade field for README indexes and companion evidence.} | +| Automation status | {not-assessed, scaffold, ready, proven, blocked, or manual.} | +| Last validated | {Use YYYY-MM-DD after validation, or null in the JSON metadata marker when not validated.} | +| Execution surface | {on-device, mixed, cloud-diagnostic, cloud-control, or thin. This is separate from automation status.} | +| Spec reference | {Path to future companion spec, or blank.} | + +Plain-language detector explanation: describe what evidence source the selected detector represents and why it matches the article. When `detector.type` is `none`, keep `detector.signal` as JSON `null`. When selecting any other detector type, set both `detector.type` and `detector.signal` together so automation can find the exact signal. + +### Automation vocabulary + +Automation status records test readiness. It is separate from execution surface terms such as on-device, cloud, or mixed, which describe where a generated action can run. + +| Vocabulary | Values | Meaning | +| --- | --- | --- | +| Fidelity level | L0 | Static structure, metadata, and persona review only. No live validation. | +| Fidelity level | L1 | Read-only diagnostics or claims were run or checked against a real or authoritative source. | +| Fidelity level | L2 | A safe proxy, synthetic input, or data-source override exercised the same decision path without reproducing the full real-world failure. | +| Fidelity level | L3 | A scratch object or isolated fixture exercised the real mechanism without changing the whole system. | +| Fidelity level | L4 | Full inject, detect, mitigate, and revalidate loop was proven end to end on an appropriate lab substrate. | +| Technical grade | null | No TSG-FORGE technical grade has been produced yet. | +| Technical grade | A, B, C, or F | The authoritative TSG-FORGE technical grade, backed by report or spec evidence. Do not invent a separate grade vocabulary. | +| Detector type | none | No machine detector applies yet. Use with `detector.signal: null`. | +| Detector type | envchecker | Azure Local Environment Validator result or health-check signal. | +| Detector type | eventlog | Windows event log provider, log name, and Event ID. | +| Detector type | command | Read-only command or script result. | +| Detector type | service, feature, registry | Operating system state probe for a service, Windows feature, or registry value. | +| Detector type | telemetry | Fleet or service telemetry query used by internal validation. | +| Detector type | manual or portal | Human-observed portal, visual, or manual validation surface. | +| Detector type | control-plane | Azure Resource Manager or other Azure control-plane state. | +| Automation status | not-assessed | No automation assessment has been completed. | +| Automation status | scaffold | Metadata exists, but detector or validation automation is incomplete. | +| Automation status | ready | Automation is authored and ready to run, but not yet proven. | +| Automation status | proven | Automation has successful validation evidence and a validation date. | +| Automation status | blocked | Automation is known to be blocked, with the blocking reason documented. | +| Automation status | manual | Validation intentionally requires human judgment or an external manual step. | + +## References + +- {Public Microsoft Learn or Microsoft documentation link. Example: https://learn.microsoft.com/azure/azure-local/} diff --git a/TSG/Templates/HowTo-Template.md b/TSG/Templates/HowTo-Template.md index 541d8d23..42b1b0d9 100644 --- a/TSG/Templates/HowTo-Template.md +++ b/TSG/Templates/HowTo-Template.md @@ -1,109 +1,516 @@ - - -# {Title} - - - - - - - - - - - - - - -
Component{Component Name}
Topic{Topic Name}: {Brief description of the how to}
Applicable Scenarios{Applicable Scenarios}: {List of scenarios this guide applies to}
- -## Overview - -{Brief description of what this guide will help the reader accomplish} - -## What and Why - -### What This Guide Covers - -{Clearly describe what specific configuration, setup, or management task is covered by this guide} - -### When to Use This Guide - -{Describe the scenarios or conditions under which this guide should be followed} - -## Prerequisites - -{List any requirements, permissions, or setup needed before starting} - -- {Prerequisite 1} -- {Prerequisite 2} - -## Table of Contents - -{Update Table of Contents as needed} - -- [Overview](#overview) -- [What and Why](#what-and-why) -- [Prerequisites](#prerequisites) -- [{Section 1 Title}](#section-1-title) -- [Verification](#verification) -- [Troubleshooting](#troubleshooting) - -## {Section 1 Title} - -{Brief explanation of this scenario or configuration. Add as many sections as needed. An example might be: 1 Node Cluster vs 4 Node Cluster or Update vs Add Node} - -### Step 1: {Action Description} - -{Brief explanation of what this step accomplishes} - -1. {Detailed instruction} - -2. {Next instruction} - -### Step 2: {Action Description} - -{Brief explanation of what this step accomplishes} - -1. {Detailed instruction} - -2. {Next instruction} - -### Verification - -{Steps to confirm the configuration was completed successfully and is working as expected} - -1. {Verification step 1} - -2. {Verification step 2} - -### Troubleshooting - -{Common issues and their solutions} - -#### {Common Issue 1} - -**Symptoms:** {Description of what the user might see} -**Solution:** {How to resolve it} - -##### {Common Issue 2} - -**Symptoms:** {Description of what the user might see} -**Solution:** {How to resolve it} - ---- + + + +# {Title} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Document typeHow-To
Purpose{State the customer or operator outcome this guide helps achieve and why it matters.}
Business impact{State the customer capability, workload, deployment, or operations outcome this procedure protects or restores.}
Audience{Primary reader or owner, such as Azure Local administrator, Microsoft Customer Support Services (CSS) engineer, partner or system integrator (SI) deployment engineer, original equipment manufacturer (OEM) field engineer, or workload owner.}
Owner and approver{Execution owner, approval owner, and handoff team if the assigned reader is not the owner.}
Component{Azure Local component or feature area.}
Applicable products{List exact Azure Local products, SKUs, deployment types, and related Microsoft products. Verify against public documentation before publishing.}
Supported versions{List supported Azure Local releases, builds, extension versions, firmware versions, or tool versions. State the source used to verify support.}
Applies to{List environments, cluster states, operations, and scenarios where this guide applies.}
Does not apply to{List explicit out-of-scope products, versions, symptoms, or conditions. Tell the reader where to go instead.}
Estimated duration{Expected operator time and elapsed time. Include whether the task needs a maintenance window.}
Overall action type and risk{Use [READ-ONLY] when the guide only gathers information and state that risk is not applicable because no state changes. For state-changing guides, choose one: [LOW RISK], [MEDIUM RISK], [HIGH RISK]. Explain the reason in one sentence.}
Customer update cadence{Who receives updates, how often they receive them, and the next update time if the procedure takes longer than expected.}
+ +## Overview + +{Briefly describe the task, the end state, and the benefit to the customer or operator. Keep this section short enough for a decision maker to skim.} + +## Decision summary + +Fill this summary before the first command so leaders, account teams, and field engineers can make the same proceed or stop decision. + +| Decision field | Required author input | +| --- | --- | +| Owner | {Person, team, or role that runs the procedure.} | +| Approver | {Person, team, or role that approves the maintenance window or state change.} | +| Customer impact | {Plain-language statement of what customer capability is affected now and what capability is restored after success.} | +| Fastest safe unblock | {Shortest approved path, first stop condition, and fallback owner if the path is not safe.} | +| Proceed decision | {Proceed only when prerequisites, approvals, rollback, and evidence capture are ready. Name the approver.} | +| Next customer update | {Time, audience, and content for the next update.} | +| Success statement | {One sentence the support or account team can use to explain that the capability is restored.} | + +## Outcome + +After completing this guide, the reader should be able to: + +- {Outcome 1 with a measurable result.} +- {Outcome 2 with a measurable result.} +- {Completion signal that proves the task succeeded.} + +## Scope and routing + +Use this guide only when all of the following are true: + +- {In-scope condition 1.} +- {In-scope condition 2.} +- {Required product or version condition.} + +Do not use this guide when any of the following are true: + +- {Out-of-scope condition 1.} +- {Out-of-scope condition 2.} +- {Escalation or handoff condition, such as original equipment manufacturer (OEM)-owned firmware work, network-team ownership, or product-group investigation.} + +If the guide is assigned to the wrong owner, collect this handoff evidence before sending it to the owning team. + +| Handoff scenario | Owning team or role | Evidence to collect before handoff | Handoff trigger | +| --- | --- | --- | --- | +| Network-owned change | {Network team or partner.} | {Adapter names, switch ports, IP configuration, route or DNS output, and timestamp.} | {Condition that proves the issue is network-owned.} | +| OEM-owned hardware or firmware change | {OEM vendor field engineer.} | {Platform model, firmware levels, baseboard management controller (BMC), integrated Dell Remote Access Controller (iDRAC), or HPE Integrated Lights-Out (iLO) evidence, and supported configuration source.} | {Condition that requires OEM action.} | +| Workload-owned change | {Application or virtual machine (VM) owner.} | {Affected VM or workload list, expected outage, drain status, and approval.} | {Condition that requires workload-owner approval.} | +| Microsoft support or product escalation | {Microsoft CSS or product group.} | {Logs, command outputs, error text, timestamps, versions, and failed verification result.} | {Condition that blocks safe customer action.} | + +Document safe alternatives and rejected approaches so the reader knows what not to try. + +| Option | Status | Why it is safe, preferred, or rejected | Evidence or approval needed | +| --- | --- | --- | --- | +| {Preferred safe path} | {Use} | {Why this is the lowest-risk approved path.} | {Required evidence or approval.} | +| {Alternative path} | {Use only when...} | {Tradeoff, added risk, or prerequisite.} | {Required evidence or approval.} | +| {Rejected approach} | {Do not use} | {Why this approach is unsafe, unsupported, untested, or outside the guide scope.} | {Who can approve or replace it, if anyone.} | + +## Prerequisites + +Complete these checks before starting. Do not proceed until every required item is satisfied. + +| Prerequisite | Required value or condition | How to check | Stop condition | +| --- | --- | --- | --- | +| Permissions | {Role, role-based access control (RBAC) assignment, local admin right, or tool access required.} | {Command, portal page, or public documentation link.} | {Stop if permission is missing.} | +| Cluster health | {Required health state, quorum state, update state, or node state.} | {Command or portal page to verify.} | {Stop if health state is not safe for this task.} | +| Backup or recovery material | {Backup, recovery key, config export, or rollback artifact required.} | {How to confirm it exists and is usable.} | {Stop if recovery material is unavailable.} | +| Maintenance window | {Required or not required. Include duration and customer communication needs.} | {How to confirm approval.} | {Stop if required approval is missing.} | +| Tools and versions | {PowerShell modules, Azure CLI extensions, browser, portal access, firmware package, or vendor utility.} | {Command to show version or public Microsoft link.} | {Stop if an unsupported tool version is present.} | + +## Safety and impact + +Classify each action before it appears in this guide: + +- [READ-ONLY]: Diagnostics, checks, and information gathering that do not change state. Risk is not applicable because no state changes. +- [LOW RISK]: State-changing actions with no expected customer workload impact and a documented rollback. +- [MEDIUM RISK]: State-changing actions that can affect management operations, validation results, or a single node, but should not interrupt running workloads when prerequisites are met. +- [HIGH RISK]: State-changing actions that can interrupt workloads, require node drain or reboot, alter security posture, modify firmware, delete resources, or require coordinated maintenance. + +Document the maintenance impact before any action that changes state: + +| Impact area | Author prompt | +| --- | --- | +| Workloads and virtual machines (VMs) | {Can this affect VM availability, live migration, storage paths, network connectivity, or application traffic?} | +| Cluster availability | {Does this require draining a node, rebooting, changing quorum-sensitive state, or pausing an update?} | +| Security posture | {Does this change authentication, certificates, BitLocker, Secure Boot, Defender, firewall, RBAC, or secrets?} | +| OEM or partner ownership | {Is this owned by an OEM, networking team, partner SI, Microsoft CSS, or customer IT?} | +| Customer communication | {Who must be notified, what duration should they expect, and what completion signal should they receive?} | + +## Glossary and do-not-proceed checklist + +Add short definitions for terms that a first-time Azure Local operator must understand before running commands. + +| Term | Plain-language definition | Where the reader verifies it | +| --- | --- | --- | +| Role-based access control (RBAC) | {Define the Azure permission model or role assignment needed for this procedure.} | {Command, portal surface, or public Microsoft documentation link.} | +| Quorum | {Define the minimum cluster voting state needed to keep the cluster available.} | {Command, portal surface, or public Microsoft documentation link.} | +| Microsoft Customer Support Services (CSS) | {Define when Microsoft support owns the next action.} | {Escalation or support handoff link.} | +| System integrator (SI) | {Define when a deployment partner owns the next action.} | {Partner handoff process.} | +| Original equipment manufacturer (OEM) | {Define when the hardware vendor owns the next action.} | {Vendor support path or public Microsoft hardware guidance.} | + +Do not proceed unless every row below is satisfied. + +| Guardrail | Required proof before continuing | If not satisfied | +| --- | --- | --- | +| All placeholders are replaced | {Every placeholder has a real customer-safe value or a documented reason it is not used.} | Stop and complete the filled-in variables table. | +| Target scope is clear | {State whether the action affects one node, all nodes, one cluster, a resource group, a subscription, or a tenant.} | Stop and get owner approval for the correct scope. | +| Workload impact is approved | {VM, app, network, security, and maintenance impact are documented.} | Stop and obtain the required approval or handoff. | +| Rollback is ready | {Rollback command, portal action, or support path is documented and available.} | Stop unless the approver accepts that rollback is not possible. | +| Expected output is known | {Normal output and stop-condition output are documented.} | Stop and add expected output before running the action. | + +## Table of contents + +- [Overview](#overview) +- [Decision summary](#decision-summary) +- [Outcome](#outcome) +- [Scope and routing](#scope-and-routing) +- [Prerequisites](#prerequisites) +- [Safety and impact](#safety-and-impact) +- [Glossary and do-not-proceed checklist](#glossary-and-do-not-proceed-checklist) +- [Execution contract](#execution-contract) +- [{Procedure section title}](#procedure-section-title) +- [Rollback](#rollback) +- [Verification](#verification) +- [Expected output examples](#expected-output-examples) +- [Troubleshooting](#troubleshooting) +- [Handoff and escalation package](#handoff-and-escalation-package) +- [Evidence to collect](#evidence-to-collect) +- [Claims and validation evidence](#claims-and-validation-evidence) +- [Metadata vocabulary](#metadata-vocabulary) +- [Future test automation metadata](#future-test-automation-metadata) +- [Next steps](#next-steps) +- [References](#references) + +## Execution contract + +Complete this contract before the procedure. It is the compact checklist for literal followers, multi-node rollouts, workload owners, and reviewers. + +### Filled-in variables and target scope + +| Placeholder or variable | Exact value to use | Target scope | Current value | New value | Approval owner | Verification command or surface | +| --- | --- | --- | --- | --- | --- | --- | +| {Placeholder 1} | {Value to use.} | {Node, cluster, resource group, subscription, tenant, site, or workload.} | {Current value or state.} | {New value or state.} | {Approver.} | {Command or UI surface.} | +| {Placeholder 2} | {Value to use.} | {Node, cluster, resource group, subscription, tenant, site, or workload.} | {Current value or state.} | {New value or state.} | {Approver.} | {Command or UI surface.} | + +### Action checklist + +Every generated action must complete each row. Use [READ-ONLY] for diagnostics and state that risk is not applicable because no state changes. Use risk labels only for state-changing actions. + +| Required item | Author prompt | +| --- | --- | +| Action type | {Use [READ-ONLY] for diagnostics or information gathering. Use state-changing when the action modifies configuration, data, resources, firmware, or workload state.} | +| Risk label for state-changing action | {Required only when action type is state-changing. Choose one: [LOW RISK], [MEDIUM RISK], or [HIGH RISK]. For [READ-ONLY], write "not applicable, no state changes."} | +| Privilege required | {Least-privilege role, RBAC assignment, local right, or tool access required for this action.} | +| Workload impact | {State whether the action affects VM uptime, app traffic, live migration, storage paths, networking, security posture, or update flow.} | +| Drain or maintenance approval | {State whether VM drain, node pause, reboot, maintenance window, or customer approval is required.} | +| Pre-check | {Read-only command or UI surface that proves the target is safe to change.} | +| Action | {One command or UI action, with placeholders replaced.} | +| Error handling and retry behavior | {State ErrorAction or equivalent behavior, retry count, delay, and when a retry is unsafe.} | +| Idempotency | {State whether it is safe to run the action more than once and how the command detects existing state.} | +| Expected result or output | {Exact success output, status, or portal state.} | +| Stop condition | {Exact failure output, unexpected state, or blast-radius concern that stops the procedure.} | +| Rollback | {Undo command, portal action, or support path.} | +| Expected rollback output | {Exact output or state that proves the rollback action ran.} | +| Rollback verification | {Read-only command or UI surface that proves the previous state is restored.} | +| Verification | {Read-only command or UI surface that proves the step succeeded.} | +| Escalation | {Owner to contact if action, rollback, or verification fails.} | + +### Rollout tracker + +Use this tracker when the procedure repeats across nodes, clusters, resource groups, or sites. + +| Batch or site | Targets | Order | Pre-validation | Approved window | Re-run validation | Stop criteria | Status | +| --- | --- | --- | --- | --- | --- | --- | --- | +| {Batch 1} | {Targets included.} | {Order and dependency.} | {Read-only validation before the batch.} | {Window and approver.} | {Validation after the batch.} | {When to stop before the next batch.} | {Not started, running, complete, or stopped.} | +| {Batch 2} | {Targets included.} | {Order and dependency.} | {Read-only validation before the batch.} | {Window and approver.} | {Validation after the batch.} | {When to stop before the next batch.} | {Not started, running, complete, or stopped.} | + +## {Procedure section title} + +{Explain the scenario or configuration this procedure covers. State whether the actions are per node, per cluster, per resource group, per subscription, or per tenant.} + +Repeat the following action pattern for every generated step. Every action must include action type, pre-check, action, expected result or output, stop condition, rollback, and verification. Use [READ-ONLY] for diagnostics and state that rollback and risk are not applicable because no state changes. Use [LOW RISK], [MEDIUM RISK], or [HIGH RISK] only for state-changing actions. + +### Step 1: {Action description} + +**Action type:** {Use [READ-ONLY] for diagnostics or information gathering and state that risk is not applicable because no state changes. Use state-changing when the action modifies configuration, data, resources, firmware, or workload state.} + +**Risk label for state-changing action:** {Required only for state-changing actions. Choose one: [LOW RISK], [MEDIUM RISK], [HIGH RISK]. For [READ-ONLY], write "not applicable, no state changes."} + +**Privilege required:** {Least-privilege role, RBAC assignment, local right, or tool access required for this step.} + +**Workload impact and approval:** {State VM, app, live migration, network, security, and maintenance impact. State whether drain, reboot, maintenance approval, or workload-owner approval is required.} + +**Purpose:** {Explain what this step changes or confirms.} + +**Pre-check:** {Confirm the required state before this step. Include the command, portal page, or UI surface.} + +```powershell +<# Replace with a read-only pre-check command, if this step uses PowerShell. #> +{PreCheckCommand} +``` + +**Action:** {Give one clear action. If this is a command, use placeholders such as or instead of real customer values.} + +```powershell +<# Replace with the safe action command, if this step uses PowerShell. #> +{ActionCommand} +``` + +**Error handling and retry behavior:** {State ErrorAction or equivalent behavior, retry count, retry delay, and when a retry is unsafe.} + +**Idempotency:** {State whether running this step more than once is safe and how the command checks existing state before changing it.} + +**Expected result or output:** {Show the expected success message, table values, portal state, or command output shape.} + +```text +{ExpectedOutput} +``` + +**Stop condition:** {State the exact output, error, state, or risk signal that means the reader must stop before continuing.} + +**Rollback for this step:** {State how to undo this step if it fails or produces the wrong output. If no rollback exists, explain why and require approval before the action.} + +**Expected rollback output:** {Show the output, state, or portal value that proves rollback ran.} + +**Rollback verification:** {State the read-only command or UI surface that proves the previous state is restored.} + +**Verification for this step:** {State how to prove this single step succeeded before moving to the next step.} + +**Escalation:** {State who owns the next action if the step, rollback, or verification fails.} + +### Step 2: {Next action description} + +**Action type:** {Use [READ-ONLY] for diagnostics or information gathering and state that risk is not applicable because no state changes. Use state-changing when the action modifies configuration, data, resources, firmware, or workload state.} + +**Risk label for state-changing action:** {Required only for state-changing actions. Choose one: [LOW RISK], [MEDIUM RISK], [HIGH RISK]. For [READ-ONLY], write "not applicable, no state changes."} + +**Privilege required:** {Least-privilege role, RBAC assignment, local right, or tool access required for this step.} + +**Workload impact and approval:** {State VM, app, live migration, network, security, and maintenance impact. State whether drain, reboot, maintenance approval, or workload-owner approval is required.} + +**Purpose:** {Explain what this step changes or confirms.} + +**Pre-check:** {Confirm the required state before this step.} + +```powershell +<# Replace with a read-only pre-check command, if this step uses PowerShell. #> +{PreCheckCommand} +``` + +**Action:** {Give one clear action.} + +```powershell +<# Replace with the safe action command, if this step uses PowerShell. #> +{ActionCommand} +``` + +**Error handling and retry behavior:** {State ErrorAction or equivalent behavior, retry count, retry delay, and when a retry is unsafe.} + +**Idempotency:** {State whether running this step more than once is safe and how the command checks existing state before changing it.} + +**Expected result or output:** {Show the expected output or state.} + +```text +{ExpectedOutput} +``` + +**Stop condition:** {State when to stop and who to contact.} + +**Rollback for this step:** {State how to undo this step or restore the previous state.} + +**Expected rollback output:** {Show the output, state, or portal value that proves rollback ran.} + +**Rollback verification:** {State the read-only command or UI surface that proves the previous state is restored.} + +**Verification for this step:** {State how to prove this step succeeded.} + +**Escalation:** {State who owns the next action if the step, rollback, or verification fails.} + +## Rollback + +Use this section if a step fails, the expected output does not match, the stop condition is reached, or the customer asks to return to the previous state. + +| Rollback trigger | Rollback action | Expected result or output | Verification after rollback | +| --- | --- | --- | --- | +| {Trigger 1} | {Command or portal action to restore the previous state.} | {Expected rollback output.} | {How to prove rollback succeeded.} | +| {Trigger 2} | {Command or portal action to restore the previous state.} | {Expected rollback output.} | {How to prove rollback succeeded.} | + +If rollback is not possible, replace this section with the explicit reason, the approval required before proceeding, and the support or escalation path. + +## Verification + +Run these checks after the final step and after any rollback. The guide is not complete until every pass criterion is met. + +| Check | Command or UI surface | Expected result or output | Pass criteria | If it fails | +| --- | --- | --- | --- | --- | +| {Verification check 1} | {Command, portal page, or tool.} | {Expected output.} | {Exact values or state that prove success.} | {Rollback, retry, or escalation instruction.} | +| {Verification check 2} | {Command, portal page, or tool.} | {Expected output.} | {Exact values or state that prove success.} | {Rollback, retry, or escalation instruction.} | + +## Expected output examples + +Use examples with placeholders only. Do not include customer identifiers, subscription identifiers, tenant identifiers, secrets, tokens, or private links. + +```text +{Command or portal surface} +Expected: {Expected success value, status, or message} +Unexpected: {Unexpected value, status, or message that triggers a stop condition} +``` + +## Troubleshooting + +### {Common issue 1} + +**Symptoms:** {What the reader sees.} + +**Likely cause:** {Most likely cause, with evidence.} + +**Action:** {Safe next step. If it is diagnostic, label it [READ-ONLY] and state risk is not applicable because no state changes. If it changes state, use the same action contract as the procedure: action type, risk label, privilege, workload or maintenance gate, pre-check, action, expected result or output, stop condition, rollback, expected rollback output, rollback verification, verification, and escalation.} + +**Escalate when:** {Condition that requires Microsoft CSS, product group, OEM, network team, partner SI, or customer IT escalation.} + +### {Common issue 2} + +**Symptoms:** {What the reader sees.} + +**Likely cause:** {Most likely cause, with evidence.} + +**Action:** {Safe next step. If it is diagnostic, label it [READ-ONLY] and state risk is not applicable because no state changes. If it changes state, use the same action contract as the procedure: action type, risk label, privilege, workload or maintenance gate, pre-check, action, expected result or output, stop condition, rollback, expected rollback output, rollback verification, verification, and escalation.} + +**Escalate when:** {Condition that requires escalation.} + +## Handoff and escalation package + +Create this package when a mis-assigned reader needs to hand off the case or when verification fails after rollback. + +| Package item | Required detail | +| --- | --- | +| Summary | {One-line problem, impact, and current state.} | +| Owner requested | {Network, OEM, workload owner, Microsoft CSS, product group, partner SI, or customer IT.} | +| Evidence | {Logs, command outputs, portal screenshots, exact error text, and timestamps in UTC.} | +| Environment | {Product, supported version, cluster state, node count, hardware model if relevant, and tool versions.} | +| Actions already tried | {Pre-checks, actions, expected result, actual result, rollback status, and verification result.} | +| Escalation trigger | {The condition that proves the current reader should not continue.} | +| Redaction | {Customer identifiers, subscription identifiers, tenant identifiers, secrets, tokens, and private data removed.} | + +## Evidence to collect + +Collect enough evidence for support, audit, or PR review without exposing secrets or customer-private data. + +| Evidence | Where to collect it | Redaction required | Why it matters | +| --- | --- | --- | --- | +| {Evidence item 1} | {Command, portal page, event log, component log, or public tool.} | {Values to redact.} | {How this confirms success or explains failure.} | +| {Evidence item 2} | {Command, portal page, event log, component log, or public tool.} | {Values to redact.} | {How this confirms success or explains failure.} | + +## Claims and validation evidence + +Use this table for mechanism statements, version requirements, safety claims, and rollback claims. Do not publish a technical claim without a source or validation status. + +| Claim | Source or evidence | Tested status | Failure mode covered | Rollback proof | +| --- | --- | --- | --- | --- | +| {Technical claim 1} | {Public Microsoft documentation, command output, lab validation, or product source summary that supports the claim.} | {Not tested, static-reviewed, read-only validated, lab validated, or customer validated.} | {What can go wrong if the claim is false or incomplete.} | {How rollback was tested or why rollback is not available.} | +| {Technical claim 2} | {Public Microsoft documentation, command output, lab validation, or product source summary that supports the claim.} | {Not tested, static-reviewed, read-only validated, lab validated, or customer validated.} | {What can go wrong if the claim is false or incomplete.} | {How rollback was tested or why rollback is not available.} | + +## Metadata vocabulary + +Use these definitions when completing the metadata marker or the future test automation table. The public schema is [tsg-metadata.schema.json](../Templates/tsg-metadata.schema.json) for articles copied into a component folder under `TSG//`. If the article is copied into a deeper folder, adjust the relative path so the link still reaches `TSG/Templates/tsg-metadata.schema.json`. + +| Field or value | Definition | +| --- | --- | +| detector.type `none` | No detector has been selected. Set `detector.signal` to JSON `null`. When authors select a detector later, they must set `detector.type` and `detector.signal` together. | +| detector.type `command` | A read-only command or script detects the state. Set `detector.signal` to the command or function name. | +| detector.type `envchecker` | An Azure Local Environment Checker validation detects the state. Set `detector.signal` to the validator or check name. | +| detector.type `feature` | An installed Windows feature state detects the condition. Set `detector.signal` to the feature name. | +| detector.type `portal` or `manual` | A human checks a portal or manual surface. Set `detector.signal` to the exact blade, page, or manual check. | +| detector.type `eventlog`, `service`, `registry`, `telemetry`, or `control-plane` | A specific event, service state, registry value, telemetry query, or Azure control-plane state detects the condition. Set `detector.signal` to the exact signal. | +| fidelity level `L0` | Static review only. No live command or detector proof. | +| fidelity level `L1` | Read-only commands or verification steps were run and returned the claimed shape. | +| fidelity level `L2` | The detection signal and reversible remediation direction were validated with a safe proxy or synthetic input. | +| fidelity level `L3` | The real failure pattern was validated on an isolated scratch object or disposable target. | +| fidelity level `L4` | Full inject, detect, mitigate, and revalidate loop was proven end to end on a safe lab substrate. | +| technical_grade `null`, `A`, `B`, `C`, or `F` | Use JSON `null` until a TSG-FORGE grade exists. Use `A`, `B`, `C`, or `F` only when a grading artifact records that grade. This is separate from `fidelity_level`. | +| safe injectability `none` | No safe inject is known. Keep fidelity at L0 or L1 unless read-only validation exists. | +| safe injectability `proxy` | A safe substitute input exercises the same decision logic without causing the real failure. | +| safe injectability `scratch object` | A temporary object, such as a test resource or file, carries the failure and can be deleted. | +| safe injectability `reversible lab-only change` | A lab change can be undone and is not suitable for customer production. | +| safe injectability `destructive` | The action is not safely reversible. Do not use it for live validation without explicit approval and a disposable target. | +| automation_status `not-assessed` | No automation assessment has been performed. | +| automation_status `scaffold` | Metadata exists, but the detector or automation is not ready to run. | +| automation_status `ready` | Automation is defined and ready to run, but not yet proven. | +| automation_status `proven` | Automation has passed validation and cites evidence. | +| automation_status `blocked` | Automation is blocked by safety, access, substrate, or product limitations. | +| automation_status `manual` | Validation remains manual by design. | +| Execution surface | Where an action runs: `on-device`, `mixed`, `cloud-diagnostic`, `cloud-control`, or `thin`. Do not put execution-surface values in `automation_status`. | + +## Future test automation metadata + +Complete this section so TSG-FORGE or another validation harness can evaluate this How-To later. + +| Field | Required author input | +| --- | --- | +| Metadata schema | Link to [tsg-metadata.schema.json](../Templates/tsg-metadata.schema.json). Adjust the relative path if the article is copied into a deeper folder. | +| Automation candidate | {yes, no, or partial. Explain why.} | +| detector.type | {Choose the exact JSON detector type: none, command, control-plane, envchecker, eventlog, feature, manual, portal, registry, service, or telemetry. Use the adjacent explanation columns or notes for plain-language validation-surface details.} | +| Automation status | {Choose one: not-assessed, scaffold, ready, proven, blocked, or manual. Do not use execution-surface values here.} | +| Technical grade | {Use null until graded, or A, B, C, or F after a TSG-FORGE grading artifact exists.} | +| Safe injectability | {none, proxy, scratch object, reversible lab-only change, or destructive.} | +| Rollback automation | {How rollback could be automated and what state it restores.} | +| Reproduction substrate | {Choose one: none, vm, hardware, or either. Use none with automation_status manual when validation is intentionally manual.} | +| Target fidelity level | {L0, L1, L2, L3, or L4.} | +| validation.last_validated | {Use JSON null until validation has run. After validation, use the ISO date in YYYY-MM-DD format and cite the report, spec, or evidence.} | +| Validation history | {Date, build, substrate, result, and evidence link when available.} | +| Spec reference | {Path to future companion spec, if one exists.} | + +## Next steps + +After verification passes, state what happens next so the work is closed cleanly. + +| Next step | Required author input | +| --- | --- | +| Monitor | {Signals, logs, portal surfaces, or customer symptoms to watch after completion, and for how long.} | +| Close or hand back | {Who accepts the result, what evidence they receive, and how the task is closed or returned to the owning team.} | +| Follow-up work | {Any deferred cleanup, documentation, ticket update, support handoff, or future automation item.} | +| Customer update | {Plain-language completion note, remaining risk, and next update cadence if monitoring continues.} | + +## References + +Add only public Microsoft links, such as: + +- [Azure Local documentation](https://learn.microsoft.com/azure/azure-local/) +- {Public Microsoft documentation link for this task} diff --git a/TSG/Templates/Markdown-Snippets.md b/TSG/Templates/Markdown-Snippets.md index a1a88737..0085413a 100644 --- a/TSG/Templates/Markdown-Snippets.md +++ b/TSG/Templates/Markdown-Snippets.md @@ -1,289 +1,742 @@ -# Markdown Formatting Reference - -This document provides copy-paste snippets for common formatting elements used in Azure Local Supportability documentation. - ---- - -## Alert & Emphasis Boxes - -### Important Information - -```markdown -> [!IMPORTANT] -> This is critical information that readers must understand before proceeding. -``` - -### Warning Messages - -```markdown -> [!WARNING] -> This action could cause system downtime or data loss. Proceed with caution. -``` - -### Helpful Notes - -```markdown -> [!NOTE] -> This provides additional context or clarification for the reader. -``` - -### Helpful Tips - -```markdown -> [!TIP] -> This offers a useful suggestion or best practice. -``` - -### Caution Alerts - -```markdown -> [!CAUTION] -> This warns about potential issues or risks to consider. -``` - ---- - -## Mermaid Markdown Diagrams and Flow Charts - -For consistency and readability in Light and Dark mode, use the following flowchart template. - -```mermaid -flowchart TD - %% Basic nodes with different shapes/text formatting - Start["Starting Node"] - Decision{"Decision Node"} - Action["Action Node"] - Warning["Warning Node"] - - %% Different types of arrows and labels - Start --> Decision %% Simple arrow - Decision -- "Yes" --> Action %% Arrow with text - Decision --"No"--> Warning %% Arrow with text (no spaces) - Action ==> Warning %% Thick arrow - Warning -.-> Start %% Dotted arrow - - %% Subgraph example - subgraph ProcessGroup - direction TB %% Top to Bottom direction - Step1["First Step"] - Step2["Second Step"] - Step3["Third Step"] - - Step1 --> Step2 - Step2 --> Step3 - end - - %% Connection to subgraph - Decision --> ProcessGroup - - %% Styling definitions - classDef action stroke:#dc2626,stroke-width:3px,fill:none; - classDef warning stroke:#ea580c,stroke-width:3px,fill:none; - classDef decision stroke:#2563eb,stroke-width:3px,fill:none; - classDef success stroke:#059669,stroke-width:3px,fill:none; - - %% Apply styles to nodes - class Action action; - class Warning warning; - class Decision decision; - class Start success; -``` - ---- - -## Advanced HTML Callout Boxes - -### Basic Note Box - -
- 📘 Note: This is a general note for additional information or clarification on a topic. -
- -```html -
- 📘 Note: This is a general note for additional information or - clarification on a topic. -
-``` - -### Warning/Info Callout Box - -
- ⏳ Waiting Time: Allow 10–15 minutes for logs to accumulate before proceeding with the next steps. -
- -```html -
- ⏳ Waiting Time: Allow 10–15 minutes for logs to accumulate - before proceeding with the next steps. -
-``` - -### Important Info Box - -
- ⚠️ Important: Please ensure you follow the recommended steps carefully to avoid unintended issues. -
- -```html -
- ⚠️ Important: Please ensure you follow the recommended steps - carefully to avoid unintended issues. -
-``` - -### Common Causes Box - -
-

Common Causes

-
    -
  • Potential cause one
    • -
  • Potential cause two
    • -
  • Potential cause three
    • -
-
- -```html -
-

Common Causes

-
    -
  • Potential cause one
    • -
  • Potential cause two
    • -
  • Potential cause three
    • -
-
-``` - -### Advanced Tips Box - -
- 💡 Tip: This box can provide advanced tips or optional steps for users seeking deeper insights. -
- -```html -
- 💡 Tip: This box can provide advanced tips or optional steps - for users seeking deeper insights. -
-``` - ---- - -## Code Blocks - -### PowerShell Commands - -````markdown -```powershell -# Description of what this command does -Get-Process | Where-Object {$_.ProcessName -eq "example"} -``` -```` - -### Console/Terminal Output - -````markdown -```console -# Network configuration example -interface Ethernet1/1 - description Azure Local Node Connection - switchport mode trunk - switchport trunk allowed vlan 100,200,711,712 -``` -```` - -### JSON Configuration - -````markdown -```json -{ - "property": "value", - "setting": { - "enabled": true, - "timeout": 30 - } -} -``` -```` - -### Generic Code Block - -````markdown -``` -Generic text or configuration content -that doesn't fit a specific language -``` -```` - ---- - -## Tables - -### Basic Specifications Table - -```markdown -| Requirement | Specification | Notes | -| ------------- | ------------- | ------------------------ | -| **Component** | Details here | Additional context | -| **Setting** | Value here | Important considerations | -``` - -### Comparison Table - -```markdown -| Feature | Option 1 | Option 2 | Option 3 | -| --------------- | ----------------- | ---------- | ----------- | -| **Performance** | High | Medium | Low | -| **Complexity** | Low | Medium | High | -| **Use Case** | Small deployments | Enterprise | Specialized | -``` - -### Metadata Table (for TSG documents) - - - - - - - - - - -
ComponentComponent Name
TopicTopic Name: Brief description
- -```markdown - - - - - - - - - -
ComponentComponent Name
TopicTopic Name: Brief description
-``` - ---- - -## Emojis - -```markdown -- ✅ Recommended approach -- ⚠️ Proceed with caution -- 🚫 Not recommended -- 🔧 Requires configuration -- 📋 Note -``` - ---- +# Markdown Formatting Reference + +This document provides copy-ready snippets for common formatting elements used in Azure Local Supportability documentation. It is a reference authoring aid, not an article template. Copy the sections you need into a troubleshooting guide, how-to guide, reference, overview, or deep dive. In this file, TSG means troubleshooting guide. + +Use text labels in addition to any visual styling. Do not use icons as the only status signal. + +--- + +## Table of Contents + +- [Article metadata marker](#article-metadata-marker) +- [Applicable products and supported versions](#applicable-products-and-supported-versions) +- [Risk and safety labels](#risk-and-safety-labels) +- [Prerequisites and stop gates](#prerequisites-and-stop-gates) +- [Author assembly checklist](#author-assembly-checklist) +- [Complete action pattern](#complete-action-pattern) +- [Expected output and validation](#expected-output-and-validation) +- [Where this appears](#where-this-appears) +- [Test automation metadata](#test-automation-metadata) +- [Owner, impact, and handoff snippets](#owner-impact-and-handoff-snippets) +- [Worked safe-action and rollout snippets](#worked-safe-action-and-rollout-snippets) +- [Evidence, glossary, and validation snippets](#evidence-glossary-and-validation-snippets) +- [Alert and emphasis boxes](#alert-and-emphasis-boxes) +- [Mermaid Markdown diagrams and flow charts](#mermaid-markdown-diagrams-and-flow-charts) +- [Optional HTML callout boxes](#optional-html-callout-boxes) +- [Code blocks](#code-blocks) +- [Tables](#tables) +- [Status labels](#status-labels) + +--- + +## Article metadata marker + +Article templates and finished articles should include exactly one HTML-comment JSON marker. Keep this marker near the top of the article, then replace the placeholder values. Component README and CONTRIBUTING templates should require and index this marker, but should not embed article metadata themselves. + +````markdown + +```` + +Validate the completed marker against [`tsg-metadata.schema.json`](./tsg-metadata.schema.json). Keep `validation.technical_grade` as JSON `null` until TSG-FORGE produces `A`, `B`, `C`, or `F` with report or spec evidence. When `detector.type` is `none`, keep `detector.signal` as JSON `null`. When an author selects a real detector, such as `envchecker`, `eventlog`, or `command`, they must set both `detector.type` and `detector.signal` together. + +--- + +## Applicable products and supported versions + +Use this table whenever guidance depends on product, release, hardware, or operation phase. Be explicit about supported versions and out-of-scope cases. + +```markdown +## Applicable products + +| Product | Supported versions | Scope | Out of scope | Source | +| --- | --- | --- | --- | --- | +| Azure Local | | | | | +| | | | | | +``` + +--- + +## Risk and safety labels + +Use `[READ-ONLY]` for steps that do not change state. It is not a risk label. When an action may change state, use one of the canonical risk labels and replace the placeholders with the actual impact, gate, and rollback for the article. + +```markdown +## Risk and safety + +> [!WARNING] +> [] This action changes , or is read-only. Expected impact: . Do not continue unless is true, is present, is satisfied for the workload impact, and is available. + +| Label | When to use | Required pre-check | Required privilege | Workload or maintenance gate | Stop condition | Rollback | +| --- | --- | --- | --- | --- | --- | --- | +| [READ-ONLY] | Non-mutating detection or validation only | | | | | Not applicable because no state changes | +| [LOW RISK] | Reversible changes with no expected workload impact | | | | | | +| [MEDIUM RISK] | Reversible state changes that can interrupt management, networking, or workload placement | | | | | | +| [HIGH RISK] | Firmware, reboot, destructive cleanup, storage, quorum, or workload-impacting actions | | | | | | +``` + +--- + +## Prerequisites and stop gates + +Use this table before any action pattern. The reader should know what to check, what success looks like, and when to stop. + +```markdown +## Prerequisites + +| Requirement | How to confirm | Expected result | Stop if not met | +| --- | --- | --- | --- | +| Administrative PowerShell on an Azure Local node | `whoami /groups` | The required admin group is present | Escalate to a cluster administrator | +| Maintenance window, if workloads may move or restart | | The window covers the expected impact | Schedule the change first | +| Current state captured | Save the output from the pre-check command | Output is attached to the case or pull request (PR) | Do not run the action until current state is recorded | +``` + +--- + +## Author assembly checklist + +Use this checklist before copying snippets into an article. It keeps article authors from guessing which sections are required for each document type. + +| Document type | Required snippet blocks | Optional snippet blocks | Fast path placement | +| --- | --- | --- | --- | +| Troubleshooting guide | Metadata marker, applicable products, risk and safety, prerequisites, where this appears, complete action pattern, expected output, verify the fix, evidence bundle | Owner handoff, workload impact, OEM boundary, multi-node rollout | Put the fastest safe diagnosis and stop gate before deeper explanation | +| How-to guide | Metadata marker, applicable products, prerequisites, risk and safety, complete action pattern, expected output, rollback, verification | Workload impact, rollout table, customer summary | Put the top three actions before background information | +| Reference article | Metadata marker, applicable products, supported versions, defaults, constraints, expected output, validation command | Glossary, owner handoff, evidence bundle | Put required settings and supported versions before examples | +| Overview | Metadata marker, applicable products, owner and impact summary, customer-facing summary, scope, next action | Glossary, handoff table | Put the reader decision and owner first | +| Deep dive | Metadata marker, applicable products, glossary, evidence, validation command, operational boundaries | Workload impact, OEM boundary, rollout table | Put the mechanism summary before detailed internals | + +Use this fast-path table when the reader needs the shortest safe path before the full article. + +| Step | Prompt to fill | Stop gate | Revalidation | +| --- | --- | --- | --- | +| 1. Confirm scope | Product, supported version, node or site, and owner | Stop if the product or version is out of scope | Record the scope in the evidence bundle | +| 2. Run read-only detection | The command or portal check that proves the issue exists | Stop if the output is healthy, empty when empty is healthy, or inconclusive | Save the exact output and timestamp | +| 3. Choose the action | The risk-labeled action, privilege, workload gate, maintenance window, rollback, and escalation owner | Stop if rollback is unavailable, privilege is missing, workload approval is missing, or maintenance gating is unresolved | Run the verification command and record pass or fail | + +--- + +## Complete action pattern + +Every generated action pattern should prompt for pre-check, action, expected result or output, stop condition, rollback, and verification. + +````markdown +## Action: + +> [!WARNING] +> [] + +### Privilege and workload gate + +| Gate | Required value | +| --- | --- | +| Required privilege | | +| Workload impact | | +| Maintenance or approval gate | | +| Escalation owner | | + +### Pre-check + +Run this before changing state. + +```powershell + # Read the current state. + +``` + +Expected output: + +```console + +``` + +Stop if: . + +### Action + +Run this only after the pre-check matches the expected state. + +```powershell + # Change only the documented state. + +``` + +Expected result: + +```console + +``` + +### Rollback + +Use this if the action fails, the expected result does not appear, or the customer requests backout. + +```powershell + # Restore the prior state captured in the pre-check. + +``` + +Expected rollback output: + +```console + +``` + +Rollback verification: + +```powershell + +``` + +Resume only if: . + +### Verification + +Re-run the detection command and confirm the healthy output. + +```powershell + +``` + +Pass criteria: . +Fail criteria: . +Escalation: . +```` + +--- + +## Expected output and validation + +Show the reader what success, failure, empty output, and inconclusive output mean for the specific check. + +````markdown +## Expected output + +Healthy output: + +```console +Name Status Detail + Success +``` + +Unhealthy output: + +```console +Name Status Detail + Failure +``` + +No output means: . + +## Verify the fix + +1. Re-run the same detection command used in the diagnosis section. +2. Confirm the result matches the healthy output above. +3. If the issue was discovered during pre-update validation, re-run the documented health check, for example `Invoke-SolutionUpdatePrecheck -SystemHealth`, then confirm `Get-SolutionUpdateEnvironment` shows `HealthState` as `Success`. +4. If validation still fails, collect the evidence listed in the detection surfaces table and escalate with the before and after output. +```` + +--- + +## Where this appears + +Use this table to document administrator detection surfaces. Use only these states: `shown`, `not-evident`, and `absent`. `shown` means the surface displays the issue. `not-evident` means the surface was actually checked with a named command, blade, log, time window, timestamp, or freshness proof and did not display the issue. `absent` means the surface has not been characterized yet, so treat it as a draft work item rather than a publishable final state for troubleshooting content. + +```markdown +## Where this appears + +| Surface | State: shown, not-evident, or absent | What to look for | Evidence and freshness required for shown or not-evident | +| --- | --- | --- | --- | +| PowerShell on an Azure Local node | | | | +| Azure portal | | | | +| Windows event logs | | | | +| Cluster logs, `Get-ClusterLog` | | | | +| Failover Cluster Manager | | | | +| Windows Admin Center, standalone | | | | +| Windows Admin Center in Azure portal | | | | +| Component or tool log files | | | | +``` + +--- + +## Test automation metadata + +Use this block when a troubleshooting guide (TSG) has been linted or live-tested by TSG-FORGE. Keep customer identifiers, cluster names, IP addresses, subscription IDs, and tenant-specific values out of public files. + +````markdown +## Test automation metadata + +```json +{ + "schema": "azure-local-supportability/tsg-metadata/v1", + "document_type": "troubleshoot", + "products": ["Azure Local"], + "detector": {"type":"none","signal":null}, + "validation": { + "fidelity_level": "L0", + "technical_grade": null, + "reproduction_substrate": "none", + "automation_status": "not-assessed", + "last_validated": null, + "spec_ref": "" + } +} +``` +```` + +Use these compact rubrics when filling the schema fields and companion evidence. Record execution surface, loop steps, report links, and evidence in the article body, PR description, or companion spec rather than adding out-of-schema fields to the marker. + +| Field | Values | Meaning | +| --- | --- | --- | +| `document_type` | deep-dive, how-to, overview, reference, troubleshoot | Use the token that matches the article template filename. Do not use display names such as Deep Dive or How To inside the JSON marker. | +| `detector.type` | command, control-plane, envchecker, eventlog, feature, manual, none, portal, registry, service, telemetry | Use `none` only when the article has no detector. When using `none`, `detector.signal` must be JSON `null`. | +| `fidelity_level` | L0, L1, L2, L3, L4 | L0 means static lint or persona review only. L1 means read-only diagnostics were run. L2 means a faithful detector, proxy, or synthetic input was tested. L3 means the real mechanism was tested on a scratch or isolated object. L4 means the full genuine inject, detect, mitigate, and revalidate loop passed. | +| `technical_grade` | null, A, B, C, F | This is the authoritative technical grade field. Use JSON `null` until TSG-FORGE produces A, B, C, or F with report or spec evidence. | +| `automation_status` | not-assessed, scaffold, ready, proven, blocked, manual | Test readiness. Use not-assessed before review, scaffold when planned but not implemented, ready when automation exists but is not proven, proven when it has passed with evidence, blocked when automation cannot proceed yet, and manual when a human must verify. | +| `execution_surface` | on-device, mixed, cloud-diagnostic, cloud-control, thin | Runtime location. This is separate from `automation_status`: on-device runs on a node, mixed uses node plus cloud checks, cloud-diagnostic depends on cloud telemetry, cloud-control changes connected Azure state, and thin has no executable diagnostic or action. | + +```markdown +## Validation evidence + +| Field | Value | +| --- | --- | +| Execution surface | | +| TSG-FORGE report | | +| Companion spec | | +| Loop evidence | | +| Freshness | | +``` + +--- + +## Owner, impact, and handoff snippets + +Use this compact set when the article needs a decision owner, customer context, workload impact, or a handoff boundary. + +| Snippet | Copy-ready prompt | +| --- | --- | +| Owner and impact summary | State the business impact, technical owner, customer-visible impact, expected duration, downtime risk, and escalation path in one paragraph. | +| Customer-facing summary | In plain language, state the current state, who owns the next action, what will happen next, expected timing, and what the customer can safely do while waiting. | +| Owner handoff | Record the primary owner, secondary owner, evidence already collected, evidence still needed, and the condition that transfers ownership. | +| Workload impact | State whether VMs move, live migrate, pause, restart, drain, or experience downtime. Name the required approval and maintenance window. | +| OEM boundary | State the hardware evidence, firmware or driver target, owner, and the signal that this is not an OEM action. | +| Accessibility context | Explain why the step matters, who it helps, what risk it avoids, and the safe next action for a reader who cannot perform the change. | + +```markdown +## Owner, impact, and handoff + +| Field | Value | +| --- | --- | +| Business or customer impact | | +| Primary owner | | +| Secondary owner or handoff target | | +| Expected duration |