pnp-engineering-review

name	pnp-engineering-review
description	How to run an engineering review of an Azure Architecture Center article when a human explicitly requests it. USE when an "engineering review" is requested of an article, or when asked to review, evaluate, assess, or check the completeness/quality of an article interactively. DO NOT USE for GitHub Copilot's automated pull request review (use pnp-copilot-pr-review instead), for ai assisted authoring, for pure link checking alone, or for drafting new content from scratch.
compatibility	Depends on the microsoft-learn-grounding skill, a web search tool, and the link-checker agent. Requires an internet connection.
disable-model-invocation	false
license	MIT
user-invocable	true
metadata	{"author":"Azure Patterns & Practices"}

Engineering review

This skill is a repeatable process for running an engineering review of an Azure Architecture Center article against a fixed set of quality criteria defined by the Azure Patterns & Practices engineering team. It produces feedback that the author should consider.

The review is read-only. You evaluate and report. You don't edit the article unless the invoker explicitly asks you to fix a specific finding.

Scope: the whole article

Review the article as it stands today in your workspace. Read the full content body and the paired .yml metadata, if one exists, before you evaluate anything.

Align your review to the article's content type. It changes how hard you press on some topics. A solution idea isn't expected to cover every Well-Architected pillar; a reference architecture is.

The target reader is a professional cloud architect or software engineer designing a real workload for Azure, usually greenfield. Judge guidance from that seat: "If I had to advise this customer today, is this what I'd say?"

Workflow

1. Build the todo list first. Enumerate the review steps (below, plus any the invoker adds) as tracked tasks. Wait for the invoker to confirm the list before starting. Insert or drop steps when the invoker asks.
2. Work one todo item at a time. Mark it in-progress, gather evidence, then report a verdict before moving on. Don't batch.
3. Report per todo item: a clear PASS / FAIL (or PASS-with-findings), then findings tagged by severity: Critical (wrong or broken), High (missing core guidance, undisclosed shortcoming), Medium (redirects, stale-but-working), Low (nice-to-have). Link findings to specific lines.
4. Close with a summary across all steps.

The steps

These are the todo items for the list. The user can take them in any order, but unless otherwise instructed, expect to operate on them sequentially as listed here.

1. Factually correct (grounded in Microsoft Learn)

Extract the article's load-bearing, falsifiable claims such as service names, limits, SLAs, feature behaviors, numeric thresholds, "you can / you can't" statements. Ground each one on Microsoft Learn by following the microsoft-learn-grounding skill. Report claims that are wrong, stale, or newly incomplete. Cite your source.

2. Matches the title, opening description, and metadata description

Break the title, H1, and descriptions (metadata and opening section) into their promises. Confirm the body delivers on each. Watch for scope drift: content that wanders off-title, or a title that promises more than the body covers. You can propose a more scoped title to match the body and/or call out what the body is missing or too broadly addressing.

3. No deprecated technology or operational processes

If the article recommends, showcases, or depends on anything that's deprecated, the design causes regret. Per policy, the data in this article must not showcase deprecated technology or solution approaches, and a deprecation notice is never a valid workaround. Treat a violation as a high-severity finding no matter how strong the surrounding guidance is.

Flag any of the following items:

• Deprecated, retired, or superseded technology. A service, SKU, API version, tool, or feature that Microsoft announced for retirement, replaced with a successor, or no longer recommends.
• Deprecated operational processes. A configuration, deployment, or management procedure that is no longer the supported or recommended mechanism when a documented replacement exists.
• Retirement paths. Something still supported today but carrying a published end-of-life or migration deadline the reader should know about.

Cite the retirement or replacement notice, and name the current successor the article author should instead pivot the architecture to use.

4. Great, opinionated guidance

Judge whether the article leads the architect to a durable, low-regret design. Check alignment with the Well-Architected Framework and Cloud Adoption Framework. Look specifically for:

• Undisclosed shortcomings. Manual steps presented as if automatic, constraints not stated, lock-in from a recommended option. Flag them even when every individual sentence is technically true.
• Internal contradictions.
• Missing core guidance. What would the architect reading this expect to find that isn't here?
• Non-"regular-way" approaches. An unusual or niche path chosen where a mainstream, supported approach exists.
• Weasel words and marketing speak. Language that doesn't help an architect understand or justify a decision to their product owner or team, such as vague and unquantified claims. Push for the underlying fact, metric, or limit instead, so the reader can weigh it against their own constraints.

Ground every "current best practice" claim you make on Microsoft Learn and cite your source.

5. Retain opinionated guidance from the prior article

Choose the prior version before comparing guidance. For an existing or renamed article, use the version on main as the authoritative baseline. Prefer to retrieve the corresponding rendered article through the Microsoft Learn MCP fetch tool, but use main if the published version differs. For a renamed article, trace the former path on main. Skip this step for a new article. For an article that replaces another article, use judgment: compare against the replaced article on main when the replacement carries forward its purpose or guidance; otherwise, skip this step. State which baseline you selected or why you skipped the comparison.

Compare the prior version of the article's opinionated guidance against the current version. Identify recommendations, decision criteria, tradeoffs, constraints, and shortcomings that were materially lost or weakened. Report only ideas that remain necessary for the current article to provide complete guidance. Don't report lost ideas that the current version supersedes with a better approach.

6. Images and text tell the same story

For each image in the article, compare what the image depicts against what the article says. They should describe the same design. Look for:

• Components or services in the diagram that the text never mentions, and text that describes important elements absent from the diagram.
• Numbered or lettered callouts that don't match between the figure and the step list, or that are out of order.
• Contradicting details such as different tier names, replication directions, zone or region counts, or connection topology between the picture and the words.

Report any place where a reader following the text would picture something different from the diagram.

Also evaluate arrow clarity in architecture diagrams. Arrows carry meaning, so they must be used consistently: either every arrow shows data-flow direction (rare) or, more usefully, every arrow shows a client-server interaction (who calls whom). Pick one convention and hold to it across the diagram. Flag double-headed arrows as they're almost always wrong, because a component is rarely both the client and the server of the same connection. The reader should be able to tell from the arrows what calls what, so they can reason about dependencies and network line-of-sight requirements. Describe on the diagram where the direction is ambiguous, inconsistent, or implies a relationship that doesn't exist.

7. Components section is complete, accurate, and purposeful

Only applies when the article has a Components section (the list of Azure services and other building blocks the architecture uses). If there's no such section, skip this step. When there is, check four things:

• No key component is missing. The list doesn't have to be exhaustive, but every major building block the architecture depends on should appear. Cross-check the list against the diagram, the data flow, and the body. A service the design clearly leans on but never lists is a gap.
• No listed component is absent from the architecture. Question or flag anything in the list that the architecture doesn't actually appear to use. "Services you could also consider" don't belong in a list of what this architecture is built from.
• Each entry states its specific role in this architecture. Every item must say what direct responsibility or capability it provides in this particular design, not just a generic product description lifted from the service's overview. Flag entries that only describe the product in general instead of its job here in this scenario.
• Each item in the components list must contain a link to the product's WAF service guide. If the Well-Architected Framework doesn't have a service guide for the product, then the component must link to its Microsoft Learn product documentation. If it is a non-Microsoft product that doesn't have Microsoft Learn documentation, it must link the official third-party documentation for that component.

8. Alternatives are captured, consolidated, and justified

Sound, common alternatives to the design belong in a dedicated Alternatives section, not scattered through the article. Alternatives are usually component-level swaps but can also be a different process or approach. The goal is to capture the most likely alternatives for this scenario, not to list all alternatives.

Check for:

• Scattered alternatives. If the article raises alternatives inline across multiple sections, recommend consolidating them into a single Alternatives section, and note where they currently appear.
• Missing likely alternatives. Research what the industry commonly uses for this scenario. When there's clear evidence that a mainstream alternative is widely used for this scenario and the article doesn't mention it, name it and cite your source.
• Weak or unjustified entries. If a listed alternative isn't meaningfully different, isn't realistic for this scenario, or gives no reason you'd ever choose it, suggest removing it or adding the tradeoff that justifies keeping it.

Every alternative that stays should say when a reader would pick it over the primary choice.

9. Well-Architected pillar content is filed under the right pillar

Only applies when the article organizes content by Well-Architected Framework pillar section. If the article doesn't have a pillar section, skip this step.

For each pillar subsection, confirm the recommendations under it actually belong to that pillar. You're looking for misfiled content such as a Reliability item that's actually a cost tradeoff. Flag anything that belongs under a different pillar. When an item genuinely spans pillars, it should sit under its primary concern and can reference the others rather than being duplicated.

Ground against the WAF pillar definitions on Microsoft Learn per the microsoft-learn-grounding skill. Report each misfiled item with the pillar it's under now and the pillar it belongs under and the Learn source for that reason.

10. Cost Optimization section links a pricing estimate

Only applies when the article has a Cost Optimization section. The section must include a link to a saved Azure Pricing Calculator estimate for this architecture, not the generic calculator URL. Confirm that the link targets a shared estimate, but don't evaluate whether the estimate's calculations are accurate or current.

11. Article and reference implementation align

This step applies only when the article includes a link to a deployable repo. If there's no such link, skip this step. When there is a link, fetch the linked implementation (for example, the GitHub repo it points to) and do a light comparison against what the article says. You're confirming the article and the code tell the same story, not auditing or running the code.

Look for divergences that would matter to a reader who deploys the code expecting what the article describes:

• Components or resources the article describes that the implementation doesn't deploy, or resources the code deploys that the article never mentions.
• Topology, SKUs or tiers, region or zone counts, or key settings that differ between the article and the code.
• Instructions or prerequisites in the article that no longer match the repo (renamed scripts, moved paths, changed parameters).

Call out significant differences and why they matter to the article. Ignore trivial or cosmetic drift.

12. Aligns with industry perspective

Compare the article's positions and terminology against how the broader industry describes the same system. Use your web search tool to consult reputable non-Microsoft sources: vendor technical reports and reference architectures, integrator and practitioner guides, and cloud-agnostic references. When the topic has a clear equivalent on another hyperscaler, check the other hyperscalers' documentation too (for example, AWS or Google Cloud documentation for the same workload or pattern). A competitor's treatment of the same problem is a legitimate industry-perspective signal, even though you'll ground the Azure specifics on Microsoft Learn.

Report scope divergence in both directions:

• The article covers something others don't. Novel or opinionated positions can be a strength, but flag them so the author can confirm the claim is intentional and defensible rather than an outlier or scope creep.
• Others cover something the article doesn't. A topic, constraint, or design consideration that the industry treats as important but the article omits is a gap candidate. The author decides whether it belongs in scope.

Sourcing rules: prefer first-party vendor and reputable practitioner sources, and attribute them. Watch for terminology misalignment such as cases where the article uses a product or domain term differently than the industry does.

13. Terminology and acronyms are accurate

Check the terminology and acronyms across the full article. Verify technical terms, acronym expansions, architecture names, product names, protocols, standards, and units in the complete sentence where each term appears. Don't assume a term is correct because the surrounding context is plausible or its link works.

• Confirm that an acronym and its expansion name the same concept. Clarify overloaded acronyms based on the sentence's meaning. For example, distinguish the Arm processor architecture from Azure Resource Manager (ARM).
• Read each sentence literally. Flag impossible attributions and category errors, such as assigning a processor architecture to a management plane or describing a control plane as a runtime component.
• Ground unfamiliar or ambiguous Microsoft product terminology in authoritative Microsoft Learn product documentation by following the microsoft-learn-grounding skill. For non-Microsoft terminology, use the applicable standards body or first-party vendor documentation.

14. URLs avoid redirects and dead-ends

Collect every link in the article and pair it with the context where it's used. Resolve site-relative and repo-relative links to their published absolute URLs for validation while retaining the original link and source context, then run the link-checker agent over that list.

Your job is to interpret the agent's table, not to re-verify it. Report real redirects, silent aliases, irrelevant content, and dead-ends with the lines where they appear. Watch for known false positives: the agent probes with a plain curl and no browser identity, so some hosts return blocking codes even though the page is fine in a browser. When the agent flags one of those as an error, label it a probable false positive for a human to confirm rather than reporting it as a dead-end.

What you won't be checking for

• Grammar and spelling
• Metadata correctness (for example, ms.date, author, ms.author, ms.topic, ai-usage)