Merge remote-tracking branch 'upstream/main' into add-daily-focus-board-skill

2026-08-21 16:36:51 +00:00 · 2026-08-07 09:38:12 -07:00
parent 817800315c 811ed362dd
commit c73936e05e
50 changed files with 2329 additions and 1182 deletions
@@ -16,7 +16,7 @@ An ASP.NET Core app typically has a Program.cs file that "builds" the app. Find

 ## Configure App Insights connection string

-The App Insights resource has a connection string. Add the connection string as an environment variable of the running app. You can use Azure CLI to query the connection string of the App Insights resource. See [scripts/appinsights.ps1](scripts/appinsights.ps1) for what Azure CLI command to execute for querying the connection string.
+The App Insights resource has a connection string. Add the connection string as an environment variable of the running app. You can use Azure CLI to query the connection string of the App Insights resource. See [scripts/appinsights.ps1](../scripts/appinsights.ps1) for what Azure CLI command to execute for querying the connection string.

 After getting the connection string, set this environment variable with its value.

@@ -24,6 +24,6 @@ After getting the connection string, set this environment variable with its valu
 "APPLICATIONINSIGHTS_CONNECTION_STRING={your_application_insights_connection_string}"
 ```

-If the app has IaC template such as Bicep or terraform files representing its cloud instance, this environment variable should be added to the IaC template to be applied in each deployment. Otherwise, use Azure CLI to manually apply the environment variable to the cloud instance of the app. See [scripts/appinsights.ps1](scripts/appinsights.ps1) for what Azure CLI command to execute for setting this environment variable.
+If the app has IaC template such as Bicep or terraform files representing its cloud instance, this environment variable should be added to the IaC template to be applied in each deployment. Otherwise, use Azure CLI to manually apply the environment variable to the cloud instance of the app. See [scripts/appinsights.ps1](../scripts/appinsights.ps1) for what Azure CLI command to execute for setting this environment variable.

 > Important: Don't modify appsettings.json. It was a deprecated way to configure App Insights. The environment variable is the new recommended way.
@@ -114,7 +114,7 @@ When relevant, combine with:
 - `azure-resource-visualizer` for relationship diagrams.
 - `appinsights-instrumentation` for app and service telemetry patterns.

-Also use `references/arduino-official-best-practices.md` as a quality baseline for firmware and hardware recommendations.
+Also use `references/arduino-official-best-practices.md` as a quality baseline for firmware and hardware recommendations, and `references/arduino-iot-checklist.md` before finalizing architecture or implementation guidance.

 ## Required output

@@ -140,7 +140,7 @@ Wait for user confirmation before proceeding.
 **Title**: `[COST-OPT] [Resource Type] - [Brief Description] - $X/month savings`

 **Body**:
-```markdown
+````markdown
 ## 💰 Cost Optimization: [Brief Title]

 **Monthly Savings**: $X | **Risk Level**: [Low/Medium/High] | **Effort**: X days
@@ -170,7 +170,7 @@ Wait for user confirmation before proceeding.
 - [Risk and mitigation]

 **Priority Score**: X | **Value**: X/10 | **Risk**: X/10
-```
+````

 ### Step 7: Create EPIC Coordinating Issue
 **Action**: Create master tracking issue. Label with "cost-optimization" (green), "aws" (orange), "epic" (purple).
@@ -168,3 +168,6 @@ All supported — MS Docs are automatically consulted to generate at the same qu
 | `references/azure-dynamic-sources.md` | MS Docs URL registry |
 | `references/azure-common-patterns.md` | PE/security/naming patterns |
 | `references/ai-data.md` | AI/Data service guide |
+| `assets/06-architecture-diagram.png` | Example generated architecture diagram |
+| `assets/07-azure-portal-resources.png` | Example Azure portal resource view |
+| `assets/08-deployment-succeeded.png` | Example successful deployment result |
@@ -6,7 +6,7 @@ Use this template structure when generating `preflight-report.md` in the project

 ## Template

-```markdown
+````markdown
 # Azure Deployment Preflight Report

 **Generated:** {timestamp}
@@ -196,7 +196,7 @@ Please resolve the issues listed above before deploying. After fixes:
 ---

 *Report generated by Azure Deployment Preflight Skill*
-```
+````

 ---

@@ -223,7 +223,7 @@ Please resolve the issues listed above before deploying. After fixes:

 ## Example Report

-```markdown
+````markdown
 # Azure Deployment Preflight Report

 **Generated:** 2026-01-16T14:32:00Z
@@ -338,7 +338,7 @@ azd provision --environment dev
 ---

 *Report generated by Azure Deployment Preflight Skill*
-```
+````

 ---

@@ -139,7 +139,7 @@ Always provide these outputs:

 ## Output template

-Use this response structure:
+Use `references/smart-city-solution-template.md` to standardize outputs for each scenario, with this response structure:

 1. Context and objectives
 2. Proposed architecture
@@ -55,9 +55,6 @@ Create a comprehensive system architecture diagram using Mermaid that shows how

 Use subgraphs to organize these layers clearly. Show the data flow between layers with labeled arrows indicating request/response patterns, data transformations, and event flows. Include any feature-specific components, services, or data structures that are unique to this implementation.

- **Technology Stack Selection**: Document choice rationale for each layer
-```
-
 - **Technology Stack Selection**: Document choice rationale for each layer
 - **Integration Points**: Define clear boundaries and communication protocols
 - **Deployment Architecture**: Docker containerization strategy
@@ -19,7 +19,7 @@ The specification file must define the requirements, constraints, and interfaces
 - Include examples and edge cases where applicable.
 - Ensure the document is self-contained and does not rely on external context.

-The specification should be saved in the [/spec/](/spec/) directory and named according to the following convention: `spec-[a-z0-9-]+.md`, where the name should be descriptive of the specification's content and starting with the highlevel purpose, which is one of [schema, tool, data, infrastructure, process, architecture, or design].
+The specification should be saved in the `/spec/` directory and named according to the following convention: `spec-[a-z0-9-]+.md`, where the name should be descriptive of the specification's content and starting with the highlevel purpose, which is one of [schema, tool, data, infrastructure, process, architecture, or design].

 The specification file must be formatted in well formed Markdown.

@@ -157,7 +157,7 @@ The key requirements from RFC 8805 that this skill enforces are summarized below
 - Generate a **script** for this phase.
 - Do NOT combine this phase with others.
 - Do NOT precompute future-phase data.
- Store the output as a JSON file at: [`./run/data/report-data.json`](./run/data/report-data.json)
+- Store the output as a JSON file at: `./run/data/report-data.json`

 #### Schema Definition

@@ -355,7 +355,7 @@ The goal is to ensure the file can be parsed reliably and normalized into a **co
    - Remove comment rows where the **first column begins with `#`**.
    - This also removes a header row if it begins with `#`.
    - Create a map of comments using the **1-based line number** as the key and the full original line as the value. Also store blank lines.
-    - Store this map in a JSON file at: [`./run/data/comments.json`](./run/data/comments.json)
+    - Store this map in a JSON file at: `./run/data/comments.json`
    - Example: `{ "4": "# It's OK for small city states to leave state ISO2 code unspecified" }`

 - **Notes**
@@ -543,7 +543,7 @@ Lookup all the `Entries` using Fastah's `rfc8805-row-place-search` tool.

 #### Step 1: Build Lookup Payload with Deduplication

-Load the dataset from: [./run/data/report-data.json](./run/data/report-data.json)
+Load the dataset from: `./run/data/report-data.json`
 - Read the `Entries` array. Each entry will be used to build the MCP lookup payload.

 Reduce server requests by deduplicating identical entries:
@@ -569,7 +569,7 @@ Build request batches:
 - When reading responses, match each response `rowKey` field to the corresponding deduplication entry to retrieve all associated `entryIndices`.

 Rules:
- Write payload to: [./run/data/mcp-server-payload.json](./run/data/mcp-server-payload.json)
+- Write payload to: `./run/data/mcp-server-payload.json`
 - Exit the script after writing the payload.

 #### Step 2: Invoke Fastah MCP Tool
@@ -591,7 +591,7 @@ Rules:
      {"rowKey": "550e8400-...", "countryCode":"CA", ...},
      {"rowKey": "690e9301-...", "countryCode":"ZZ", ...}
  ]
- Open [./run/data/mcp-server-payload.json](./run/data/mcp-server-payload.json) and send all deduplicated entries with their rowKeys.
+- Open `./run/data/mcp-server-payload.json` and send all deduplicated entries with their rowKeys.
 - If there are more than 1000 deduplicated entries after deduplication, split into multiple requests of 1000 entries each.
 - The server will respond with the same `rowKey` field in each response for mapping back.
 - Do NOT use local data.
@@ -599,7 +599,7 @@ Rules:
 #### Step 3: Attach Tuned Data to Entries

 - Generate a new **script** for attaching tuned data.
- Load both [./run/data/report-data.json](./run/data/report-data.json) and the deduplication map (held in memory from Step 1, or re-derived from the payload file).
+- Load both `./run/data/report-data.json` and the deduplication map (held in memory from Step 1, or re-derived from the payload file).
 - For each response from the MCP server:
  - Extract the `rowKey` from the response.
  - Look up the `entryIndices` array associated with that `rowKey` from the deduplication map.
@@ -633,7 +633,7 @@ The `TunedEntry` field is a **single object** (not an array). It holds the best

 Entries with no UUID match (i.e. the MCP server returned no response for their UUID) must receive an empty `TunedEntry: {}` object — never leave the field absent.

- Write the dataset back to: [./run/data/report-data.json](./run/data/report-data.json)
+- Write the dataset back to: `./run/data/report-data.json`
 - Rules:
  - Maintain all existing validation flags.
  - Do NOT create additional intermediate files.
@@ -351,7 +351,7 @@ EOF
 )"
 ```

-```PowerShell
+````PowerShell
 # Create PR body using here-string (preserves actual newlines, not escape sequences)
 $prBody = @"
 ## Release vX.Y.Z
@@ -367,16 +367,16 @@ This PR prepares the **vX.Y.Z** release.
 - [ ] CI passing

 After merging, create the tag on the merge commit:
-``````
+```
 git tag vX.Y.Z <merge-commit-sha>
 git push origin vX.Y.Z
-``````
+```
 "@

 # Write to file and use --body-file (do NOT use inline --body with escape sequences)
 $prBody | Out-File -FilePath release_pr_body.md -Encoding utf8 -NoNewline
 gh pr create --base main --head release/vX.Y.Z --title "Release vX.Y.Z" --body-file release_pr_body.md
-```
+````

 Paste the changelog section into the PR body's "What's included" block (or leave placeholder for manual review).

@@ -667,7 +667,7 @@ class McpServerTest {

 ## README.md Template

-```markdown
+````markdown
 # My MCP Server

 A Model Context Protocol server built with Java and the official MCP Java SDK.
@@ -740,7 +740,7 @@ Add to `claude_desktop_config.json`:
 ## License

 MIT
-```
+````

 ## Generation Instructions

@@ -1,6 +1,6 @@
 # 555

-[www.fairchildsemi.com](www.fairchildsemi.com)
+[www.fairchildsemi.com](https://www.fairchildsemi.com)

 The LM555/NE555/SA555 is  a highly stable controller capable of producing accurate timing pulses. With a monostable operation, the time delay is controlled by one external resistor and one capacitor. With an astable operation, the frequency and duty cycle are accurately controlled by two external resistors and one capacitor.

@@ -0,0 +1,198 @@
+---
+name: mcp-release-qa
+description: 'Verify an MCP server before release by exercising a real protocol session, comparing runtime capabilities with source and documentation, testing failure paths, and recording reproducible evidence. Use when shipping or reviewing an MCP server, tool, resource, prompt, catalog, or install path.'
+---
+
+# MCP Release QA
+
+Test the server that users will run. A schema review or a passing unit test is
+not runtime evidence.
+
+This skill complements security review. It focuses on protocol behavior,
+published-contract drift, transport correctness, and reproducible release
+evidence.
+
+## Rules
+
+- Run checks against a fresh server process built from the candidate revision.
+- Keep `initialize`, `notifications/initialized`, discovery, and invocation in
+  the same session. A new process is a new STDIO session.
+- Treat source registrations as implementation truth and public documentation
+  as a contract that must match it.
+- Record exact commands and raw responses. Do not replace missing evidence with
+  "looks correct."
+- Do not invoke mutation-capable tools against production data. Use fixtures, a
+  sandbox, or stop and name the missing safe test environment.
+- Derive the expected capability inventory from the candidate source on every
+  run.
+
+## 1. Establish the release surface
+
+Identify:
+
+- candidate commit and build command;
+- server entry point and transport: STDIO, Streamable HTTP, or SSE;
+- supported MCP protocol versions;
+- source files that register tools, resources, resource templates, and prompts;
+- generated catalogs, manifests, README tables, and install instructions;
+- existing protocol, integration, and smoke-test commands.
+
+Prefer repository-native commands. Inspect `package.json`, `pyproject.toml`,
+`Makefile`, CI workflows, and contributor instructions before inventing a test
+harness.
+
+## 2. Start a clean server
+
+Build the candidate and start the documented entry point with test-safe
+configuration. Capture:
+
+- the exact command;
+- commit SHA;
+- environment variable names, with values redacted;
+- stdout, stderr, and exit status;
+- the endpoint or child-process transport used by the client.
+
+For STDIO, stdout is protocol-only. Logs, banners, and stack traces belong on
+stderr. For HTTP transports, record the status, relevant MCP headers, and
+session identifier handling without printing credentials.
+
+If the server cannot start from its documented instructions, report that as a
+release failure and preserve the startup error verbatim.
+
+## 3. Exercise one complete session
+
+Run this sequence through a real MCP client or the repository's integration
+harness:
+
+1. `initialize` with a protocol version the server claims to support.
+2. Confirm the negotiated version and advertised capabilities.
+3. Send `notifications/initialized`.
+4. Call `ping`.
+5. Call each supported discovery method:
+   - `tools/list`
+   - `resources/list`
+   - `resources/templates/list`
+   - `prompts/list`
+6. Exercise at least one representative read-only item from every advertised
+   capability class.
+7. Follow pagination until no cursor remains when a list method is paginated.
+
+Do not send post-initialization requests through separate one-shot processes.
+That accidentally tests several incomplete sessions instead of one valid
+session.
+
+## 4. Prove inventory parity
+
+Build four inventories from current evidence:
+
+| Surface | Evidence |
+|---|---|
+| Source | Registered tool, resource, template, and prompt definitions |
+| Runtime | Results from the live discovery methods |
+| Generated metadata | Catalogs, manifests, or generated indexes |
+| Documentation | README, reference pages, and install output |
+
+Compare by stable identifier. Report:
+
+- source entries missing at runtime;
+- runtime entries absent from metadata or documentation;
+- stale names, descriptions, arguments, URIs, or prompt parameters;
+- documented install commands that do not start the candidate server.
+
+Regenerate derived files with the repository's own build command, then fail if
+the working tree still contains unexplained generated changes.
+
+## 5. Check published contracts
+
+For every discovered item, verify the runtime definition against its source:
+
+### Tools
+
+- Name and description are stable and specific.
+- `inputSchema` defines types, required fields, enums, and bounds where needed.
+- Unknown properties are rejected when the tool contract is closed.
+- Mutation, idempotence, read-only, and open-world annotations match behavior.
+- Successful calls conform to `outputSchema` when one is published.
+- Errors are protocol errors or structured tool failures, not leaked stack
+  traces.
+
+### Resources and templates
+
+- URIs and MIME types match the registered definitions.
+- Static resources are readable.
+- Template parameters are validated before resolution.
+- Missing or forbidden resources fail explicitly.
+
+### Prompts
+
+- Required and optional arguments match discovery output.
+- `prompts/get` returns usable messages for valid arguments.
+- Missing required arguments and unknown prompt names fail explicitly.
+
+## 6. Test failure paths
+
+At minimum, probe:
+
+- a request before initialization completes;
+- malformed JSON or an invalid JSON-RPC envelope;
+- an unknown method;
+- an unsupported protocol version;
+- repeated initialization;
+- unknown tool, resource, and prompt names;
+- missing, extra, wrong-type, and out-of-bounds arguments;
+- a request at the documented transport-size limit and one beyond it;
+- a controlled internal failure with credentials and stack traces redacted.
+
+Verify that each response has the correct request ID, a useful error message,
+and no successful side effect. For STDIO, also confirm every stdout line is a
+complete protocol message and a healthy session leaves stderr clean unless the
+server explicitly documents diagnostic output.
+
+## 7. Smoke-test installation
+
+When the project publishes an install command:
+
+1. Create a temporary destination outside the source checkout.
+2. Run the public install command exactly as documented.
+3. Start the installed artifact without relying on files from the source tree.
+4. Repeat initialization, discovery, and one read-only invocation.
+5. Remove the temporary destination after preserving the command output.
+
+An install string that was only inspected is unverified.
+
+## 8. Report the evidence
+
+Use this format:
+
+```markdown
+# MCP Release QA
+
+Candidate: [commit]
+Transport: [STDIO | Streamable HTTP | SSE]
+Verdict: PASS | PASS WITH CAVEATS | FAIL
+
+## Commands and results
+- `[exact command]` — [exit status and result]
+
+## Session transcript
+- initialize: [result]
+- discovery: [result]
+- representative calls: [result]
+- negative paths: [result]
+
+## Parity
+| Identifier | Source | Runtime | Metadata | Docs | Result |
+|---|---|---|---|---|---|
+
+## Findings
+| Severity | Evidence | Impact | Narrowest fix |
+|---|---|---|---|
+
+## Missing evidence
+- [check that could not run and why]
+```
+
+Use `FAIL` for a server that cannot start, complete a valid session, keep the
+transport parseable, or safely reject invalid input. Use `PASS WITH CAVEATS`
+only for bounded documentation or metadata drift that does not misrepresent a
+dangerous capability. Otherwise use `PASS`.
@@ -18,7 +18,7 @@ Run directly with `npx @microsoft/learn-cli <command>` or install globally with

 For client libraries, SDKs, and programming frameworks.

-```markdown
+````markdown
 ---
 name: {sdk-name}
 description: {What it does}. Use when agents need to {primary task} with {technology context}. Supports {languages/platforms}.
@@ -83,7 +83,7 @@ See [best-practices.md](references/best-practices.md) for detailed guidance.
 | {Advanced topic 1} | `microsoft_docs_search(query="{sdk} {topic}")` |
 | {Advanced topic 2} | `microsoft_docs_fetch(url="{url}")` |
 | {Code examples} | `microsoft_code_sample_search(query="{sdk} {scenario}", language="{lang}")` |
-```
+````

 ---

@@ -91,7 +91,7 @@ See [best-practices.md](references/best-practices.md) for detailed guidance.

 For Azure services and cloud resources.

-```markdown
+````markdown
 ---
 name: {service-name}
 description: Work with {Azure Service}. Use when agents need to {primary capabilities}. Covers provisioning, configuration, and SDK usage.
@@ -169,7 +169,7 @@ For more issues: `microsoft_docs_search(query="{service} troubleshoot {symptom}"
 | REST API | `microsoft_docs_fetch(url="{url}")` |
 | ARM/Bicep | `microsoft_docs_search(query="{service} bicep template")` |
 | Security | `microsoft_docs_search(query="{service} security best practices")` |
-```
+````

 ---

@@ -177,7 +177,7 @@ For more issues: `microsoft_docs_search(query="{service} troubleshoot {symptom}"

 For development frameworks and platforms (e.g., ASP.NET, MAUI, Blazor).

-```markdown
+````markdown
 ---
 name: {framework-name}
 description: Build {type of apps} with {Framework}. Use when agents need to create, modify, or debug {framework} applications.
@@ -248,7 +248,7 @@ For detailed deployment: `microsoft_docs_search(query="{framework} deploy {targe
 | {Advanced feature} | `microsoft_docs_search(query="{framework} {feature}")` |
 | {Integration} | `microsoft_docs_fetch(url="{url}")` |
 | {Samples} | `microsoft_code_sample_search(query="{framework} {scenario}")` |
-```
+````

 ---

@@ -256,7 +256,7 @@ For detailed deployment: `microsoft_docs_search(query="{framework} deploy {targe

 For APIs, protocols, and specifications (e.g., Microsoft Graph, OOXML).

-```markdown
+````markdown
 ---
 name: {api-name}
 description: Interact with {API/Protocol}. Use when agents need to {primary operations}. Covers authentication, endpoints, and common operations.
@@ -321,7 +321,7 @@ description: Interact with {API/Protocol}. Use when agents need to {primary oper
 | Full endpoint reference | `microsoft_docs_fetch(url="{url}")` |
 | Permissions | `microsoft_docs_search(query="{api} permissions {resource}")` |
 | SDKs | `microsoft_docs_search(query="{api} SDK {language}")` |
-```
+````

 ---

@@ -34,6 +34,8 @@ Standard RAG re-discovers knowledge from scratch on every query. This skill is d

 ## ⚡ Quick Start for Agents

+A complete runnable version of this workflow is in `scripts/template_agent_workflow.py` — copy and adapt it.
+
 ```python
 from scripts.contextgraph import ContextGraphSkill
 from scripts.tools import wiki_store
@@ -151,4 +151,5 @@ It looks like we haven't started a napkin yet. Want me to open one for you?
 - Always check for the PNG first. If it isn't found, prompt the user to click "Share with Copilot."
 - If the clipboard doesn't have JSON data, proceed with the PNG alone.
 - The HTML template is located at `assets/napkin.html` relative to this SKILL.md file.
+- The walkthrough images `assets/step1-activate.svg`, `assets/step2-whiteboard.svg`, `assets/step3-draw.svg`, `assets/step4-share.svg`, and `assets/step5-response.svg` are documentation illustrations, not runtime inputs.
 - If the noob-mode skill is also active, use its risk indicator format (green/yellow/red) when requesting file or bash permissions.
@@ -24,6 +24,7 @@ Build evaluators for AI/LLM applications. Code first, LLM for nuance, validate a
 | Build code evaluator | [evaluators-code-python](references/evaluators-code-python.md), [evaluators-code-typescript](references/evaluators-code-typescript.md) |
 | Build LLM evaluator | [evaluators-llm-python](references/evaluators-llm-python.md), [evaluators-llm-typescript](references/evaluators-llm-typescript.md), [evaluators-custom-templates](references/evaluators-custom-templates.md) |
 | Batch evaluate DataFrame | [evaluate-dataframe-python](references/evaluate-dataframe-python.md) |
+| Understand experiments | [experiments-overview](references/experiments-overview.md) |
 | Run experiment | [experiments-running-python](references/experiments-running-python.md), [experiments-running-typescript](references/experiments-running-typescript.md) |
 | Create dataset | [experiments-datasets-python](references/experiments-datasets-python.md), [experiments-datasets-typescript](references/experiments-datasets-typescript.md) |
 | Generate synthetic data | [experiments-synthetic-python](references/experiments-synthetic-python.md), [experiments-synthetic-typescript](references/experiments-synthetic-typescript.md) |
@@ -85,10 +85,6 @@ Reference these guidelines when:
 - [fundamentals-required-attributes](references/fundamentals-required-attributes.md) - Required fields per span type
 - [fundamentals-universal-attributes](references/fundamentals-universal-attributes.md) - Common attributes (user.id, session.id)
 - [fundamentals-flattening](references/fundamentals-flattening.md) - JSON flattening rules
- [attributes-messages](references/attributes-messages.md) - Chat message format
- [attributes-metadata](references/attributes-metadata.md) - Custom metadata schema
- [attributes-graph](references/attributes-graph.md) - Agent workflow attributes
- [attributes-exceptions](references/attributes-exceptions.md) - Error tracking

 ## Common Workflows

@@ -126,6 +126,8 @@ Always provide:

 ## Output Template

+Use `references/python-edge-module-template.md` to structure implementation proposals and reviews.
+
 1. Context and assumptions
 2. Module architecture
 3. Deployment and configuration
@@ -591,7 +591,6 @@ grep -c '^| [0-9]' quality/PROGRESS.md
 find quality/code_reviews -name "*.md" -size +500c | wc -l  # should be >= 1
 find quality/spec_audits -name "*triage*" -size +500c | wc -l  # should be >= 1
 ```
-```

 **Baseline vs with-docs comparison pattern:** Run the skill twice on the same repo — once without supplemental docs, once with a `reference_docs/` folder containing project history. Compare: requirement count, scenario count, bug count, and pipeline completion. The with-docs run should produce equal or more requirements and equal or more bugs. If the baseline outperforms the with-docs run on bug detection, that's a finding about the docs quality, not a skill failure.

@@ -208,7 +208,6 @@ This prevents the failure mode observed in v1.3.4 where express and zod silently

 Save audit reports to `quality/spec_audits/YYYY-MM-DD-[model].md`
 Save triage summary to `quality/spec_audits/YYYY-MM-DD-triage.md`
-```

 ## The Four Guardrails (Critical for All Auditors)

@@ -163,7 +163,7 @@ function Post({ postId }) {
  return <PostContent post={post} />;
 }

-// After:
+// After:
 function Post({ postId }) {
  const post = use(fetchPost(postId));
  return <PostContent post={post} />;
@@ -98,3 +98,4 @@ expect(mockFn).toHaveBeenCalledTimes(1);
 ```jsx
 // Render-phase calls (component body)  still double-invoked in React 19 StrictMode:
 expect(renderSpy).toHaveBeenCalledTimes(2);  // stays at 2 for render body calls
+```
@@ -526,7 +526,7 @@ end

 ## README.md Template

-```markdown
+````markdown
 # My MCP Server

 A Model Context Protocol server built with Ruby and the official MCP Ruby SDK.
@@ -644,7 +644,7 @@ my-mcp-server/
 ## License

 MIT
-```
+````

 ## Generation Instructions

@@ -265,7 +265,7 @@ WHERE order_date >= '2024-01-01'
 ## 🎯 Review Output Format

 ### Issue Template
-```
+````
 ## [PRIORITY] [CATEGORY]: [Brief Description]

 **Location**: [Table/View/Procedure name and line number if applicable]
@@ -285,7 +285,7 @@ WHERE order_date >= '2024-01-01'
 ```

 **Expected Improvement**: [Performance gain, security benefit]
-```
+````

 ### Summary Assessment
 - **Security Score**: [1-10] - SQL injection protection, access controls
@@ -567,7 +567,7 @@ Include at end of Executive Summary:

 ⚠️ **This ENTIRE section is REQUIRED.** Previous iterations skipped it entirely. Include ALL sub-sections below, even if tables are empty.

-```markdown
+````markdown
 ## Analysis Context & Assumptions

 ### Analysis Scope
@@ -601,7 +601,7 @@ Include at end of Executive Summary:
 <!-- Any other context from the user's prompt -->

 [Freeform notes provided by user]
-```
+````

 ### References Consulted Template

@@ -41,10 +41,12 @@ Choose format based on file types and existing content:

 ### Option 2: Detailed Table

+```markdown
 | File | Type | Description |
 |------|------|-------------|
 | [filename.ext](path/to/filename.ext) | Extension | Description |
 | [filename2.ext](path/to/filename2.ext) | Extension | Description |
+```

 ### Option 3: Categorized Sections

@@ -19,7 +19,7 @@ The specification file must define the requirements, constraints, and interfaces
 - Include examples and edge cases where applicable.
 - Ensure the document is self-contained and does not rely on external context.

-The specification should be saved in the [/spec/](/spec/) directory and named according to the following convention: `[a-z0-9-]+.md`, where the name should be descriptive of the specification's content and starting with the highlevel purpose, which is one of [schema, tool, data, infrastructure, process, architecture, or design].
+The specification should be saved in the `/spec/` directory and named according to the following convention: `[a-z0-9-]+.md`, where the name should be descriptive of the specification's content and starting with the highlevel purpose, which is one of [schema, tool, data, infrastructure, process, architecture, or design].

 The specification file must be formatted in well formed Markdown.

@@ -105,6 +105,8 @@ Detection targets:

 ### 2.2 Inspection Items

+Work through [references/visual-checklist.md](references/visual-checklist.md) during inspection and again during post-fix verification.
+
 #### Layout Issues

 | Issue | Description | Severity |