---

name: analyze-performance description: >- Statically scans the entire local Power Pages codebase for performance anti-patterns — unpaginated Power Pages lists, webpages/web templates used as custom data APIs, FetchXML over-fetching / N+1 / advanced query hints / cache bypassing, unbounded Web API queries, disabled header/footer output caching, sign-in and page tracking, main-thread-blocking JS, CSS @import, frequent Web API polling, and oversized assets — then enriches findings with AI-driven suggestions and mitigations grounded in the affected customer-code snippets, reports them, and offers safe auto-fixes with per-fix approval. Use when the user wants to: "check performance", "perf check", "find performance issues", "why is my site slow", "optimize my Power Pages site", "find anti-patterns", "review FetchXML performance", "is my site over-fetching data", or "audit site performance". user-invocable: true argument-hint: "[optional: --review <out-dir>]" allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_search, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch model: opus

Plugin check: Run node "${PLUGIN_ROOT}/scripts/check-version.js" — if it outputs a message, show it to the user before proceeding.

analyze-performance

Statically analyzes the entire local Power Pages codebase for known performance anti-patterns, enriches the static findings with AI-driven, code-aware suggestions and mitigations, presents them by severity in an HTML report + plain-language summary, and offers safe auto-fixes with per-fix approval. Never applies a fix without explicit consent.

This skill reads local source only — it does not call the deployed site. For a live security/vulnerability scan use /scan-site.

Initial request: $ARGUMENTS

Prerequisites

• An existing local non-SPA Power Pages project or PAC CLI site download. .powerpages-site/, root-level .portalconfig/, website.yml, and portal content folders are useful discovery markers, but they are not all required when the user supplies an existing site folder.
• SPA websites are not supported yet. powerpages.config.json is the authoritative local SPA marker; if it exists at the selected project root, tell the user this skill currently supports non-SPA websites only and stop.
• Node.js (bundled scripts run under node).

No sign-in, PAC CLI, or Azure CLI is required — the analysis is fully offline.

What it detects

See references/performance-reference.md for the authoritative rule catalog (tags, severities, detection, fixes, thresholds, and Microsoft Learn sources). The scan must cover all of these categories:

• List pagination — Power Pages list definitions with no positive adx_pagesize / pagesize.
• Webpages used as APIs — FetchXML/entity-backed web templates or webpage content that emit JSON/XML instead of a normal HTML page.
• FetchXML anti-patterns — all-attributes, no explicit columns, too many columns, no paging, oversized count/top, N+1 queries inside Liquid loops, unnecessary returntotalrecordcount, leading-wildcard like filters, and related-table ordering.
• FetchXML query controls — advanced query hints (options, latematerialize, no-lock, useraworderby, filter hint) and request-time values or explicit settings that bypass server-side query caching.
• Web API anti-patterns — $select=*, missing $select, no page bound ($top safety cap or Prefer: odata.maxpagesize=N cursor paging), too many selected columns, oversized $top, $count=true, $expand without a nested $select, contains/endswith filters, request-time date filters, related-table ordering, request-per-item/N+1 loops, and short-interval polling.
• Rendering and caching — disabled Header/Footer output caching, render-blocking <head> scripts, runtime CSS @import, synchronous XHR/jQuery, and document.write.
• Tracking and volume — sign-in/page/file tracking, excessive web-file or web-role counts, and oversized static assets.

Phases

1. Prerequisites — locate the project, confirm the site exists, detect review mode 1.5. Ground in current performance guidance — optional Microsoft Learn cross-check (capped, offline-safe)
2. Scan — run the deterministic analyzer over the codebase 2.5. AI mitigation pass — inspect customer-code snippets behind each finding and add code-aware suggestions/mitigations
3. Present findings — severity table + coverage stats + AI suggestions
4. Offer auto-fixes — per-finding consent loop for the safely-automatable findings
5. Verify — re-run the analyzer to confirm fixes resolved their findings
6. Report & next action — render the HTML report, summarize, and route follow-ups

Task Tracking

Create tasks in three groups. Mark each in_progress when starting, completed when done.

| Group | When to create | Tasks | |-------|----------------|-------| | 1 | At start | Verify prerequisites and locate project | | 2 | After prerequisites pass | Scan codebase for anti-patterns · Add AI-driven suggestions and mitigations · Present findings | | 3 | After findings presented (skip all three in review mode) | Offer auto-fixes (only if any autoFixAvailable) · Verify fixes · Render report and route follow-ups |

---

Phase 1 — Verify Prerequisites and Locate Project

1. Detect review mode first: if $ARGUMENTS contains --review <out-dir>, remember <REVIEW_DIR>.
2. Resolve <PROJECT_ROOT> in this order:
   • If <REVIEW_DIR> itself contains recognizable Power Pages source, use it as both <PROJECT_ROOT> and <REVIEW_DIR>. This supports orchestrated reviews that pass the downloaded site folder directly.
   • Otherwise use an explicitly supplied project directory, then the current working directory. Use Glob to locate **/powerpages.config.json, **/.powerpages-site, **/.portalconfig, or **/website.yml when needed.
3. Treat any of these as recognizable Power Pages source: .powerpages-site/, root-level .portalconfig/, website.yml, or a characteristic portal export layout containing folders such as web-pages/, web-templates/, or web-files/. Do not reject an explicitly supplied existing site folder merely because it lacks .powerpages-site/.
4. If <PROJECT_ROOT>/powerpages.config.json exists, tell the user that the selected path is a SPA website and this skill currently supports non-SPA Power Pages websites only, then stop.
5. If no existing directory with recognizable non-SPA Power Pages source can be located, tell the user and recommend /create-site, then stop.
6. In review mode Phases 3, 4, and 6-presentation are skipped: Phase 2 runs, Step 6.2 writes JSON only, and the skill stops after writing it.

Report: "Found project: <PROJECT_ROOT>. Scanning for performance anti-patterns."

Phase 1.5 — Ground in current performance guidance

Skip in review mode. Cap this step at ~30 seconds. If MCP search / fetch errors out or is unavailable, log a one-line note and continue — this skill must remain runnable offline.

1. Run microsoft_docs_search with the query: Power Pages Site Checker performance FetchXML output caching best practices.
2. Optionally microsoft_docs_fetch https://learn.microsoft.com/en-us/power-pages/admin/site-checker-performance.
3. Extract a one-paragraph summary of what Microsoft Learn currently says. Compare it against the rule catalog in references/performance-reference.md. If Learn documents a performance pattern not covered by any analyzer rule, surface it to the user in Phase 6 as a manual follow-up — do not silently invent findings the analyzer did not produce.

Phase 2 — Scan the codebase

Run the deterministic analyzer over the whole project:

node "${PLUGIN_ROOT}/skills/analyze-performance/scripts/analyze-performance.js" --projectRoot "<PROJECT_ROOT>"

The analyzer prints a single JSON object { status, findings, details, severityCounts } to stdout. Parse it. Each finding has id, tag, severity, title, location, details, fix, autoFixAvailable, and (when auto-fixable) fixAction. See references/performance-reference.md for the finding envelope and every tag's meaning.

If the only finding is PERF-NONE, the codebase is clean — note this and skip Phase 4/5 (still render the report in Phase 6 so the user has a record).

Phase 2.5 — Add AI-driven suggestions and mitigations

Run this after every deterministic scan result that will be presented or written to analyze-performance.json (including review mode). Skip only PERF-NONE.

For each finding, inspect the relevant customer-code context before writing the final JSON:

1. Read the file named by finding.location and capture a tight snippet around the line (about 20 lines before/after, capped so the report stays readable). If the file no longer exists or the finding has no location, use the finding's details and fix only.
2. Add these fields to the finding object:
   • aiSuggestion: one or two sentences explaining the best next change for this specific code path, grounded in the snippet and the rule catalog.
   • mitigation: a concrete mitigation plan that preserves behavior. Name the likely code/config edit, the safer alternative when there are tradeoffs, and anything the user must verify manually.
3. Keep the deterministic fields (tag, severity, fix, fixAction, autoFixAvailable) unchanged. Do not downgrade, suppress, or invent analyzer findings during this AI pass.
4. For heuristic findings (for example webpage-as-API, Web API N+1, cache bypassing, related-column ordering), say that the suggestion is conditional and name the observation that would confirm it.
5. For auto-fixable site-setting/tracking findings, keep mitigation aligned with the existing fixAction and repeat any important caveat, especially the Header/Footer output-cache substitution requirement.

The report renderer displays aiSuggestion and mitigation as separate fields, so write them into the JSON rather than only mentioning them in chat. If the current AI context cannot safely inspect a file because it is restricted or too large, add a conservative mitigation based on details/fix and explicitly say the source snippet was not inspected.

Phase 3 — Present findings

Skip in review mode (go straight to Step 5.1's JSON write).

Present all findings grouped by severity, highest first. Include the AI suggestion and mitigation under each row (or immediately after the table for long items) so the user sees both the static check and the code-aware recommendation:

| # | Severity | Tag | Issue | Location | Auto-fix? | |---|----------|-----|-------|----------|-----------| | 1 | high | PERF-FETCHXML-ALLATTR | FetchXML retrieves all attributes | ...:2 | No | | 2 | warning | PERF-HEADER-OUTPUTCACHE | Header output caching disabled | ...sitesetting.yml | Yes |

Then show the coverage stats from details.entries (FetchXML/Liquid, list, Web API/script and CSS files scanned; web-file/web-role counts; total findings). Keep the language plain; explain a tag only when asked. Make clear that AI suggestions are grounded in the local snippet but still require developer judgment for business-specific behavior.

Phase 4 — Offer auto-fixes

Skip in review mode. Skip entirely if no finding has autoFixAvailable: true.

Only the site-setting and tracking findings are safely automatable (PERF-HEADER-OUTPUTCACHE, PERF-FOOTER-OUTPUTCACHE, PERF-SIGNIN-TRACKING, PERF-WEBPAGE-TRACKING, PERF-WEBFILE-TRACKING). List pagination, webpage-as-API, FetchXML, Web API, query-hint, cache-bypass, and asset findings require human judgment — present th