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
- 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)
- 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
- Present findings — severity table + coverage stats + AI suggestions
- Offer auto-fixes — per-finding consent loop for the safely-automatable findings
- Verify — re-run the analyzer to confirm fixes resolved their findings
- 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
- Detect review mode first: if
$ARGUMENTS contains --review <out-dir>,
remember <REVIEW_DIR>.
- 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.
- 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/.
- 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.
- If no existing directory with recognizable non-SPA Power Pages source can be located,
tell the user and recommend
/create-site, then stop.
- 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.
- Run
microsoft_docs_search with the query: Power Pages Site Checker performance FetchXML output caching best practices.
- Optionally
microsoft_docs_fetch https://learn.microsoft.com/en-us/power-pages/admin/site-checker-performance.
- 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:
- 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.
- 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.
- Keep the deterministic fields (
tag, severity, fix, fixAction,
autoFixAvailable) unchanged. Do not downgrade, suppress, or invent
analyzer findings during this AI pass.
- 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.
- 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 those as manual fixes only.
For each finding with autoFixAvailable: true, in order:
🚦 Gate (consent · analyze-performance:4.auto-fix): Per-finding consent before applying any auto-fix. Loops once per autoFixAvailable finding — each gets its own Yes / No / Skip-all AskUserQuestion naming the finding's tag and the exact change. Never batch fixes — three fixable findings = three separate prompts (unless the user picks "Skip all", which short-circuits the loop). Each fix has its own blast radius (a different site setting or YAML file), so approving one does not approve the next.
Trigger: Phase 4, once per fixable finding.
Why we ask: Enabling output caching alone can break header/footer rendering unless the web templates also use {% substitution %} (see caveat below); toggling tracking edits committed YAML. The user must consent to each concrete change.
Cancel leaves: Nothing — declining a fix leaves that finding untouched and reported as manual.
For the approved finding, apply its fixAction:
Output-cache caveat (always surface this): enabling Header/Footer/OutputCache/Enabled is not sufficient on its own — the Header, Footer, and Languages-Dropdown web templates must also use the {% substitution %} Liquid tag, or those regions stop rendering. After applying an output-cache fix, tell the user to update those templates and verify the site still renders.
Mark each finding Fixed, Skipped, or Manual required as you go.
Phase 5 — Verify fixes
Skip in review mode. Skip if no auto-fix was applied.
Re-run the analyzer to confirm the applied fixes resolved their findings:
node "${PLUGIN_ROOT}/skills/analyze-performance/scripts/analyze-performance.js" --projectRoot "<PROJECT_ROOT>"
Confirm each fixed finding's tag/location is gone (or downgraded from warning to info for the absent→present caching case). If a fix did not take, report it and offer to retry or hand it to the user. Use this re-scanned result set as the basis for the Phase 6 report so it reflects the post-fix state.
Phase 6 — Report & next action
6.1 Review mode short-circuit
Handled at Step 6.2 below — review mode never reaches the HTML render or the follow-up walk-through.
Step 6.2 — Write the review JSON
Write the enriched { status, findings, details } object (the Phase 5 re-scan result if a re-scan ran, otherwise the Phase 2 result, with Phase 2.5 aiSuggestion/mitigation fields applied) to a JSON file:
- Review mode: write to
<REVIEW_DIR>/analyze-performance.json, then stop. The orchestrating skill (e.g., security-review) handles presentation.
- Interactive mode: write to
<TEMP_DIR>/analyze-performance.json where <TEMP_DIR> is a scratch directory containing only this file.
The filename must be analyze-performance.json — that is the key
build-review-data.js maps to the Performance section.
Step 6.3 — Render the HTML report
Skip in review mode. Reuse the shared report pipeline (same template as the security review and site scan):
The final HTML report is a persistent website artifact under
<PROJECT_ROOT>/docs/, consistent with the other review reports. Only
analyze-performance.json and data.json are temporary scratch files; delete their
temporary directory after the HTML render succeeds.
node "${PLUGIN_ROOT}/scripts/build-review-data.js" \
--reportName "Performance Analysis" \
--inputDir "<TEMP_DIR>" \
--siteName "<SITE_NAME>" \
--goalLabel "Performance" \
--scopeLabel "Local codebase" \
--summary "<SUMMARY_TEXT>" \
--output "<TEMP_DIR>/data.json"
node "${PLUGIN_ROOT}/scripts/render-review.js" \
--data "<TEMP_DIR>/data.json" \
--output "<PROJECT_ROOT>/docs/performance-analysis-<YYYY-MM-DD-HHMMSS>.html"
node "${PLUGIN_ROOT}/skills/analyze-performance/scripts/validate-analyze-performance.js" \
--reportPath "<PROJECT_ROOT>/docs/performance-analysis-<YYYY-MM-DD-HHMMSS>.html"
<SITE_NAME> comes from the site's website.yml; fall back to the folder name.
The filename must include the local timestamp (e.g.,
performance-analysis-2026-05-14-053805.html). Delete <TEMP_DIR> after the
render and explicit validation succeed, then open the report in the browser.
Step 6.4 — Summarize and route follow-ups
🚦 Gate (plan · analyze-performance:6.next-action): After the report, recommend the single most useful next step and let the user accept or choose differently via AskUserQuestion — walk through the manual (non-auto-fixable) findings one at a time, re-scan, or finish. Reviewing findings and re-scanning are read-only; nothing is changed without a later Phase 4 consent.
Trigger: Phase 6, after the report is rendered (interactive mode only).
Why we ask: The manual list, webpage-as-API, FetchXML, Web API, query-hint,
cache-bypass, and asset fixes need edits the user must drive; auto-walking every
finding would be noisy if they only wanted the report.
Cancel leaves: Nothing — the report is already written; declining ends the skill cleanly.
Give a plain-language summary: total findings, count by severity, and how many
were auto-fixed. For manual findings (list pagination, webpage-as-API patterns,
FetchXML/Web API anti-patterns, query hints, cache bypassing, volume counts, and
large assets), offer to walk through them one at a time with the concrete edit
each needs. If nothing meaningful remains, end the skill — do not ask just to ask.
Record Skill Usage
Reference: ${PLUGIN_ROOT}/references/skill-tracking-reference.md
Use --skillName "AnalyzePerformance".
Constraints
- Read-only until consent. The analyzer never mutates anything. The only writes are the HTML report, the scratch JSON, and auto-fixes the user explicitly approves in Phase 4.
- High-signal findings. Heuristics (Web API N+1, missing-but-defaultable caching) are intentionally conservative to avoid false positives. When a finding is a heuristic, say so.
- Plain language. Explain a tag only when asked; lead with the impact, not the internal name.
- Offline-safe. Phase 1.5 is best-effort; the skill must complete with no network access.
References
references/performance-reference.md — authoritative rule catalog: tags, severities, detection logic, fixes, auto-fix actions, thresholds, manual-only checks, key nuances, and Microsoft Learn sources. Read when explaining a finding or deciding whether a fix is safe.
Progress Tracking Table
| Task subject |
activeForm |
Description |
| Verify prerequisites and locate project |
Verifying prerequisites |
Locate an explicit/current code-site or PAC-download folder, confirm recognizable Power Pages source, detect review mode |
| Scan codebase for anti-patterns |
Scanning codebase |
Run analyze-performance.js over the project, parse findings JSON |
| Present findings |
Presenting findings |
Show severity table and coverage stats |
| Offer auto-fixes |
Applying auto-fixes |
Per-finding consent loop; apply site-setting/tracking fixes, surface substitution caveat |
| Verify fixes |
Verifying fixes |
Re-run analyzer, confirm fixed findings are gone |
| Render report and route follow-ups |
Rendering report |
Build review JSON, render HTML, summarize, route manual follow-ups |
1---2name: analyze-performance3description: >-4 Statically scans the entire local Power Pages codebase for performance5 anti-patterns — unpaginated Power Pages lists, webpages/web templates used as6 custom data APIs, FetchXML over-fetching / N+1 / advanced query hints / cache7 bypassing, unbounded Web API queries, disabled header/footer output caching,8 sign-in and page tracking, main-thread-blocking JS, CSS @import, frequent Web9 API polling, and oversized assets — then enriches findings with AI-driven10 suggestions and mitigations grounded in the affected customer-code snippets,11 reports them, and offers safe auto-fixes with per-fix approval.12 Use when the user wants to: "check performance", "perf check", "find13 performance issues", "why is my site slow", "optimize my Power Pages site",14 "find anti-patterns", "review FetchXML performance", "is my site over-fetching15 data", or "audit site performance".16user-invocable: true17argument-hint: "[optional: --review <out-dir>]"18allowed-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_fetch19model: opus20metadata:21 source: https://skillmd.com/skills/microsoft/analyze-performance22---2324> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.2526# analyze-performance2728Statically 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.2930This skill reads local source only — it does not call the deployed site. For a live security/vulnerability scan use `/scan-site`.3132**Initial request:** $ARGUMENTS3334## Prerequisites3536- An existing local **non-SPA** Power Pages project or PAC CLI site download.37 `.powerpages-site/`, root-level `.portalconfig/`, `website.yml`, and portal38 content folders are useful discovery markers, but they are not all required39 when the user supplies an existing site folder.40- SPA websites are not supported yet. `powerpages.config.json` is the41 authoritative local SPA marker; if it exists at the selected project root,42 tell the user this skill currently supports non-SPA websites only and stop.43- Node.js (bundled scripts run under `node`).4445No sign-in, PAC CLI, or Azure CLI is required — the analysis is fully offline.4647## What it detects4849See `references/performance-reference.md` for the authoritative rule catalog (tags,50severities, detection, fixes, thresholds, and Microsoft Learn sources). The scan51must cover all of these categories:5253- **List pagination** — Power Pages list definitions with no positive54 `adx_pagesize` / `pagesize`.55- **Webpages used as APIs** — FetchXML/entity-backed web templates or webpage56 content that emit JSON/XML instead of a normal HTML page.57- **FetchXML anti-patterns** — `all-attributes`, no explicit columns, too many58 columns, no paging, oversized `count`/`top`, N+1 queries inside Liquid loops,59 unnecessary `returntotalrecordcount`, leading-wildcard `like` filters, and60 related-table ordering.61- **FetchXML query controls** — advanced query hints (`options`,62 `latematerialize`, `no-lock`, `useraworderby`, filter `hint`) and request-time63 values or explicit settings that bypass server-side query caching.64- **Web API anti-patterns** — `$select=*`, missing `$select`, no page bound65 (`$top` safety cap or `Prefer: odata.maxpagesize=N` cursor paging),66 too many selected columns, oversized `$top`, `$count=true`, `$expand` without67 a nested `$select`, `contains`/`endswith` filters, request-time date filters,68 related-table ordering, request-per-item/N+1 loops, and short-interval polling.69- **Rendering and caching** — disabled Header/Footer output caching,70 render-blocking `<head>` scripts, runtime CSS `@import`, synchronous XHR/jQuery,71 and `document.write`.72- **Tracking and volume** — sign-in/page/file tracking, excessive web-file or73 web-role counts, and oversized static assets.7475## Phases76771. **Prerequisites** — locate the project, confirm the site exists, detect review mode781.5. **Ground in current performance guidance** — optional Microsoft Learn cross-check (capped, offline-safe)792. **Scan** — run the deterministic analyzer over the codebase802.5. **AI mitigation pass** — inspect customer-code snippets behind each finding and add code-aware suggestions/mitigations813. **Present findings** — severity table + coverage stats + AI suggestions824. **Offer auto-fixes** — per-finding consent loop for the safely-automatable findings835. **Verify** — re-run the analyzer to confirm fixes resolved their findings846. **Report & next action** — render the HTML report, summarize, and route follow-ups8586## Task Tracking8788Create tasks in three groups. Mark each `in_progress` when starting, `completed` when done.8990| Group | When to create | Tasks |91|-------|----------------|-------|92| 1 | At start | Verify prerequisites and locate project |93| 2 | After prerequisites pass | Scan codebase for anti-patterns · Add AI-driven suggestions and mitigations · Present findings |94| 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 |9596---9798## Phase 1 — Verify Prerequisites and Locate Project991001. **Detect review mode first**: if `$ARGUMENTS` contains `--review <out-dir>`,101 remember `<REVIEW_DIR>`.1022. Resolve `<PROJECT_ROOT>` in this order:103 - If `<REVIEW_DIR>` itself contains recognizable Power Pages source, use it as104 both `<PROJECT_ROOT>` and `<REVIEW_DIR>`. This supports orchestrated reviews105 that pass the downloaded site folder directly.106 - Otherwise use an explicitly supplied project directory, then the current107 working directory. Use `Glob` to locate `**/powerpages.config.json`,108 `**/.powerpages-site`, `**/.portalconfig`, or `**/website.yml` when needed.1093. Treat any of these as recognizable Power Pages source:110 `.powerpages-site/`, root-level `.portalconfig/`, `website.yml`, or a111 characteristic portal export layout containing folders such as `web-pages/`,112 `web-templates/`, or `web-files/`. Do **not** reject an explicitly supplied113 existing site folder merely because it lacks `.powerpages-site/`.1144. If `<PROJECT_ROOT>/powerpages.config.json` exists, tell the user that the115 selected path is a SPA website and this skill currently supports non-SPA116 Power Pages websites only, then **stop**.1175. If no existing directory with recognizable non-SPA Power Pages source can be located,118 tell the user and recommend `/create-site`, then **stop**.1196. In review mode Phases 3, 4, and 6-presentation are skipped: Phase 2 runs,120 Step 6.2 writes JSON only, and the skill stops after writing it.121122Report: "Found project: `<PROJECT_ROOT>`. Scanning for performance anti-patterns."123124## Phase 1.5 — Ground in current performance guidance125126> 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.1271281. Run `microsoft_docs_search` with the query: `Power Pages Site Checker performance FetchXML output caching best practices`.1292. Optionally `microsoft_docs_fetch` `https://learn.microsoft.com/en-us/power-pages/admin/site-checker-performance`.1303. 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.131132## Phase 2 — Scan the codebase133134Run the deterministic analyzer over the whole project:135136```bash137node "${PLUGIN_ROOT}/skills/analyze-performance/scripts/analyze-performance.js" --projectRoot "<PROJECT_ROOT>"138```139140The 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.141142If 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).143144## Phase 2.5 — Add AI-driven suggestions and mitigations145146Run this after every deterministic scan result that will be presented or written147to `analyze-performance.json` (including **review mode**). Skip only `PERF-NONE`.148149For each finding, inspect the relevant customer-code context before writing the150final JSON:1511521. Read the file named by `finding.location` and capture a tight snippet around153 the line (about 20 lines before/after, capped so the report stays readable).154 If the file no longer exists or the finding has no location, use the finding's155 `details` and `fix` only.1562. Add these fields to the finding object:157 - `aiSuggestion`: one or two sentences explaining the best next change for158 this specific code path, grounded in the snippet and the rule catalog.159 - `mitigation`: a concrete mitigation plan that preserves behavior. Name the160 likely code/config edit, the safer alternative when there are tradeoffs, and161 anything the user must verify manually.1623. Keep the deterministic fields (`tag`, `severity`, `fix`, `fixAction`,163 `autoFixAvailable`) unchanged. Do **not** downgrade, suppress, or invent164 analyzer findings during this AI pass.1654. For heuristic findings (for example webpage-as-API, Web API N+1, cache166 bypassing, related-column ordering), say that the suggestion is conditional167 and name the observation that would confirm it.1685. For auto-fixable site-setting/tracking findings, keep `mitigation` aligned169 with the existing `fixAction` and repeat any important caveat, especially the170 Header/Footer output-cache substitution requirement.171172The report renderer displays `aiSuggestion` and `mitigation` as separate fields,173so write them into the JSON rather than only mentioning them in chat. If the174current AI context cannot safely inspect a file because it is restricted or too175large, add a conservative mitigation based on `details`/`fix` and explicitly say176the source snippet was not inspected.177178## Phase 3 — Present findings179180> Skip in **review mode** (go straight to Step 5.1's JSON write).181182Present all findings grouped by severity, highest first. Include the AI183suggestion and mitigation under each row (or immediately after the table for long184items) so the user sees both the static check and the code-aware recommendation:185186| # | Severity | Tag | Issue | Location | Auto-fix? |187|---|----------|-----|-------|----------|-----------|188| 1 | high | PERF-FETCHXML-ALLATTR | FetchXML retrieves all attributes | `...:2` | No |189| 2 | warning | PERF-HEADER-OUTPUTCACHE | Header output caching disabled | `...sitesetting.yml` | Yes |190191Then show the coverage stats from `details.entries` (FetchXML/Liquid, list,192Web API/script and CSS files scanned; web-file/web-role counts; total findings).193Keep the language plain; explain a tag only when asked. Make clear that AI194suggestions are grounded in the local snippet but still require developer195judgment for business-specific behavior.196197## Phase 4 — Offer auto-fixes198199> Skip in **review mode**. Skip entirely if no finding has `autoFixAvailable: true`.200201Only 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 those as manual fixes only.202203For each finding with `autoFixAvailable: true`, in order:204205<!-- gate: analyze-performance:4.auto-fix | category=consent | cancel-leaves=nothing -->206> 🚦 **Gate (consent · analyze-performance:4.auto-fix):** Per-finding consent before applying any auto-fix. **Loops once per `autoFixAvailable` finding** — each gets its own Yes / No / Skip-all `AskUserQuestion` naming the finding's tag and the exact change. **Never batch fixes** — three fixable findings = three separate prompts (unless the user picks "Skip all", which short-circuits the loop). Each fix has its own blast radius (a different site setting or YAML file), so approving one does not approve the next.207>208> **Trigger:** Phase 4, once per fixable finding.209> **Why we ask:** Enabling output caching alone can break header/footer rendering unless the web templates also use `{% substitution %}` (see caveat below); toggling tracking edits committed YAML. The user must consent to each concrete change.210> **Cancel leaves:** Nothing — declining a fix leaves that finding untouched and reported as manual.211212For the approved finding, apply its `fixAction`:213214- **`create-site-setting`** (setting is absent from a per-record `.powerpages-site`215 layout): create it with the shared helper —216 ```bash217 node "${PLUGIN_ROOT}/scripts/create-site-setting.js" --projectRoot "<PROJECT_ROOT>" --name "<fixAction.name>" --value "<fixAction.value>" --type boolean --description "<short why>"218 ```219 If it reports the setting already exists, treat it as already handled and switch to the `set-site-setting` path.220- **`set-site-setting`** (setting exists but is wrong): use `Edit` on the finding's `location` file to flip the `value:` line (`false` → `true`, or tracking `true` → `false`). Do **not** call `create-site-setting.js` — it refuses to overwrite.221- **`set-yaml-field`**: use `Edit` at the finding's precise `location` to set222 `<fixAction.field>: <fixAction.value>` (e.g., `adx_enabletracking: false`).223 For a non-SPA aggregate `sitesetting.yml`, `fixAction.recordName` identifies the224 setting record and the location points at its exact `adx_value` line. Do not225 replace another record's matching boolean.226227> **Output-cache caveat (always surface this):** enabling `Header/Footer/OutputCache/Enabled` is **not** sufficient on its own — the Header, Footer, and Languages-Dropdown web templates must also use the `{% substitution %}` Liquid tag, or those regions stop rendering. After applying an output-cache fix, tell the user to update those templates and verify the site still renders.228229Mark each finding **Fixed**, **Skipped**, or **Manual required** as you go.230231## Phase 5 — Verify fixes232233> Skip in **review mode**. Skip if no auto-fix was applied.234235Re-run the analyzer to confirm the applied fixes resolved their findings:236237```bash238node "${PLUGIN_ROOT}/skills/analyze-performance/scripts/analyze-performance.js" --projectRoot "<PROJECT_ROOT>"239```240241Confirm each fixed finding's tag/location is gone (or downgraded from `warning` to `info` for the absent→present caching case). If a fix did not take, report it and offer to retry or hand it to the user. Use this re-scanned result set as the basis for the Phase 6 report so it reflects the post-fix state.242243## Phase 6 — Report & next action244245### 6.1 Review mode short-circuit246247Handled at Step 6.2 below — review mode never reaches the HTML render or the follow-up walk-through.248249### Step 6.2 — Write the review JSON250251Write the enriched `{ status, findings, details }` object (the Phase 5 re-scan result if a re-scan ran, otherwise the Phase 2 result, with Phase 2.5 `aiSuggestion`/`mitigation` fields applied) to a JSON file:252253- **Review mode**: write to `<REVIEW_DIR>/analyze-performance.json`, then **stop**. The orchestrating skill (e.g., `security-review`) handles presentation.254- **Interactive mode**: write to `<TEMP_DIR>/analyze-performance.json` where `<TEMP_DIR>` is a scratch directory containing only this file.255256The filename **must** be `analyze-performance.json` — that is the key257`build-review-data.js` maps to the Performance section.258259### Step 6.3 — Render the HTML report260261Skip in **review mode**. Reuse the shared report pipeline (same template as the security review and site scan):262263The final HTML report is a persistent website artifact under264`<PROJECT_ROOT>/docs/`, consistent with the other review reports. Only265`analyze-performance.json` and `data.json` are temporary scratch files; delete their266temporary directory after the HTML render succeeds.267268```bash269node "${PLUGIN_ROOT}/scripts/build-review-data.js" \270 --reportName "Performance Analysis" \271 --inputDir "<TEMP_DIR>" \272 --siteName "<SITE_NAME>" \273 --goalLabel "Performance" \274 --scopeLabel "Local codebase" \275 --summary "<SUMMARY_TEXT>" \276 --output "<TEMP_DIR>/data.json"277278node "${PLUGIN_ROOT}/scripts/render-review.js" \279 --data "<TEMP_DIR>/data.json" \280 --output "<PROJECT_ROOT>/docs/performance-analysis-<YYYY-MM-DD-HHMMSS>.html"281282node "${PLUGIN_ROOT}/skills/analyze-performance/scripts/validate-analyze-performance.js" \283 --reportPath "<PROJECT_ROOT>/docs/performance-analysis-<YYYY-MM-DD-HHMMSS>.html"284```285286`<SITE_NAME>` comes from the site's `website.yml`; fall back to the folder name.287The filename **must** include the local timestamp (e.g.,288`performance-analysis-2026-05-14-053805.html`). Delete `<TEMP_DIR>` after the289render and explicit validation succeed, then open the report in the browser.290291### Step 6.4 — Summarize and route follow-ups292293<!-- gate: analyze-performance:6.next-action | category=plan | cancel-leaves=nothing -->294> 🚦 **Gate (plan · analyze-performance:6.next-action):** After the report, recommend the single most useful next step and let the user accept or choose differently via `AskUserQuestion` — walk through the manual (non-auto-fixable) findings one at a time, re-scan, or finish. Reviewing findings and re-scanning are read-only; nothing is changed without a later Phase 4 consent.295>296> **Trigger:** Phase 6, after the report is rendered (interactive mode only).297> **Why we ask:** The manual list, webpage-as-API, FetchXML, Web API, query-hint,298> cache-bypass, and asset fixes need edits the user must drive; auto-walking every299> finding would be noisy if they only wanted the report.300> **Cancel leaves:** Nothing — the report is already written; declining ends the skill cleanly.301302Give a plain-language summary: total findings, count by severity, and how many303were auto-fixed. For manual findings (list pagination, webpage-as-API patterns,304FetchXML/Web API anti-patterns, query hints, cache bypassing, volume counts, and305large assets), offer to walk through them one at a time with the concrete edit306each needs. If nothing meaningful remains, end the skill — do not ask just to ask.307308### Record Skill Usage309310> Reference: `${PLUGIN_ROOT}/references/skill-tracking-reference.md`311>312> Use `--skillName "AnalyzePerformance"`.313314## Constraints315316- **Read-only until consent.** The analyzer never mutates anything. The only writes are the HTML report, the scratch JSON, and auto-fixes the user explicitly approves in Phase 4.317- **High-signal findings.** Heuristics (Web API N+1, missing-but-defaultable caching) are intentionally conservative to avoid false positives. When a finding is a heuristic, say so.318- **Plain language.** Explain a tag only when asked; lead with the impact, not the internal name.319- **Offline-safe.** Phase 1.5 is best-effort; the skill must complete with no network access.320321## References322323- `references/performance-reference.md` — authoritative rule catalog: tags, severities, detection logic, fixes, auto-fix actions, thresholds, manual-only checks, key nuances, and Microsoft Learn sources. Read when explaining a finding or deciding whether a fix is safe.324325## Progress Tracking Table326327| Task subject | activeForm | Description |328|---|---|---|329| Verify prerequisites and locate project | Verifying prerequisites | Locate an explicit/current code-site or PAC-download folder, confirm recognizable Power Pages source, detect review mode |330| Scan codebase for anti-patterns | Scanning codebase | Run analyze-performance.js over the project, parse findings JSON |331| Present findings | Presenting findings | Show severity table and coverage stats |332| Offer auto-fixes | Applying auto-fixes | Per-finding consent loop; apply site-setting/tracking fixes, surface substitution caveat |333| Verify fixes | Verifying fixes | Re-run analyzer, confirm fixed findings are gone |334| Render report and route follow-ups | Rendering report | Build review JSON, render HTML, summarize, route manual follow-ups |