# UXHC MCP Bridge

This reference helps the skill route work to the UX Heuristics Compass MCP when the MCP is available. The skill remains useful without the MCP, but the MCP is preferred for structured scoring, validation, state, reports, and local artifacts.

## Core Rule

Use the MCP when the task needs structured source prep, checklist completeness, preferences, human-loop contracts, report validation, generated Markdown/HTML/PDF artifacts, calibration, comparison, or agent-run aggregation.

Use standalone skill mode when the user only needs a lightweight review or the MCP is unavailable.

## Tool Routing

| User need | Preferred tool | Notes |
| --- | --- | --- |
| First use, overview, current runtime contract | `get_started` | Best first call when the host does not know preferences, available profiles, or human-loop behavior. Response includes `profile_aliases` (e.g. `"empathy" → "inclusion"`, `"content_strategy" → "ux_writing"`) and a `checklist_rating_contract` example with all required fields. Re-call after MCP updates to get a fresh runtime contract. |
| Explain what UXHC can do | `ux_heuristic_overview` | Use for capability summaries and boundaries. |
| Discover the rubric | `list_heuristics` | Always pass `detail_level: "summary"` unless you need every checklist item text. Full detail output can exceed 100KB and will overflow context. Use the MCP for exact item IDs when assembling `audit_ux_surface` payloads. |
| Prepare screenshot, URL, or source evidence | `prepare_ux_source` | Use for bounded page capture and source manifests. Do not request crawling or authenticated flows. |
| Quick triage | `quick_scan_ux` | Best for compact findings when enough context exists. If context is missing, respect the HIL pause. Response includes `audit_scope_lock` listing any omitted optional profiles with rerun instructions — surface these to the user before summarizing coverage. |
| Full checklist audit | `audit_ux_surface` | Use when the user asks for a full audit, expanded profiles, checklist-level evidence, or report-ready output. Output can exceed 400KB on full-profile desktop audits — pass `output_detail: "compact"` when you only need scores and top findings, or query the saved file with jq (see Output Size section below). |
| Dry-run report readiness | `validate_ux_report_payload` | Always use before generating reports when the payload was assembled by the host. Each `checklist_ratings` entry must include `checklist_item_id`, `heuristic_id`, `platform`, `rating`, `rationale`, `evidence_refs` or `evidence_limits`, and `confidence`. Missing any of these fields will block the report. Use `references/report-payload-field-guide.md` and the `checklist_rating_contract` from `get_started` as field references. |
| Generate report artifacts | `generate_ux_audit_report` | Writes Markdown, static one-page HTML, and optional PDF. Do not call with invalid payloads. Do not use `canonical_payload_template` from `audit_ux_surface` output directly because it may contain circular references. Prefer `report_ready_payload`, `report_payload_ref.path`, or returned scored audit fields instead of manual reconstruction. If validation blocks, repair the payload and retry; do not handmake HTML. |
| Severity calibration | `calibrate_ux_sensitivity` | Canonical calibration tool. `calibrate_ux_severity` is a compatibility alias. |
| Compare two audits | `compare_ux_audits` | Use for before/after, desktop/mobile, or regression review. |
| Draft project-specific add-ons | `draft_project_addon_profile` | Keeps add-on criteria separate from core score. |
| Save or update preferences | `save_preferences`, `update_preferences` | Use only for explicit preference workflows. Partial onboarding should not create a preference record. |
| Multi-persona scorecard aggregation | `run_agent_audit` | Host submits researcher-persona scorecards; MCP aggregates and flags disagreement. Personas must be dict objects — `{"id": "...", "label": "...", "description": "..."}` — not plain strings. Passing strings causes a validation error. See `agents/researcher-panel.md` for the correct persona format. |
| Retrieve agent result | `get_agent_run` | Use when an agent run ID is available. |
| Bounded usability-test prep or synthetic walkthrough | `run_usability_test` | Not real user evidence unless real participant data is supplied. When the user wants a real study after the audit, hand off to `task-templates:usability-test-plan`, `task-templates:task-scenarios-write`, and `task-templates:screener-criteria`. |
| Challenge one finding | `stress_test_heuristic_finding` | Use for false-positive checks and fix-quality review. Particularly useful for severity 3–4 findings where audience context changed the score. |

## Human-Loop Handling

When a UXHC tool returns `PAUSE_REQUIRED=true`, stop the audit flow and render the questions through native question UI where available.

Expected contract fields may include:

- `human_loop_host_action`
- `required_surface: native_question_ui`
- `ask_user_question_call` — pre-built parameter block for `AskUserQuestion`
- `tool_name: AskUserQuestion`
- `HIL_BLOCKED_UNTIL_NATIVE_UI` — when `true`, do not flatten questions into markdown prose; use the native widget
- `resolved_gates`
- `unresolved_gates`
- `hil_compliance`
- `host_instruction` — plain-language direction for how to render the gate

When the MCP returns `HIL_BLOCKED_UNTIL_NATIVE_UI: true`, use the `AskUserQuestion` tool directly. The MCP may pre-build the exact `ask_user_question_call` parameters — use them as-is. Standard format:

```json
{
  "question": "...",
  "multiSelect": false,
  "options": [
    { "label": "Option A", "description": "When to choose this" },
    { "label": "Option B", "description": "When to choose this" }
  ]
}
```

For free-text gates (mission context, user goal), use `AskUserQuestion` without `options`. Do not ask multiple HIL questions in a single widget call — one question per call.

If native UI is unavailable, use the text fallback policy and record that fallback was used. Do not pretend a native UI pause happened.

## Common MCP Flows

### Quick Audit

1. Call `get_started` if this is first use or the host lacks context.
2. Call `prepare_ux_source` if the evidence is not already structured.
3. Call `quick_scan_ux` with platform, user task, profiles, and observations or checklist ratings.
4. If paused, ask the required questions and resume with answers.
5. Return compact findings and evidence limits.

### Full Report

1. Prepare source evidence.
2. Run `audit_ux_surface` with the chosen platform and profile scope.
3. Resolve any human-loop gates.
4. Use `report_ready_payload` or the full scored audit payload.
5. Run `validate_ux_report_payload`.
6. Only if ready, call `generate_ux_audit_report`.
7. Share artifact paths and summarize what was generated.

### Advanced Agent Audit

1. Confirm platform, user task, and optional profile mode.
2. Ask beginning human-loop questions if required.
3. Host AI creates independent researcher-persona scorecards.
4. Submit those scorecards with `run_agent_audit`.
5. Use the result to report consensus, disagreement flags, top severity findings, and evidence limits.
6. Do not claim real user testing.

## Browser And Source Boundaries

UXHC source prep can support bounded public URL capture, but it is not a crawler or autonomous browser agent.

Respect these boundaries:

- no full-site crawling
- no authenticated flows
- no competitor scraping by default
- no uncontrolled navigation
- no killing or taking over browser sessions owned by another host
- no treating synthetic walkthroughs as participant evidence

## Report Readiness Guardrails

Before report generation, confirm:

- source manifest is ready
- platform is present
- active heuristics are named
- checklist ratings include stable IDs or evidence limits
- ratings use 0-4 severity
- rationales, evidence refs, confidence, and evidence limits are present
- grade fields match UXHC scoring rules
- optional profiles have ratings or explicit non-evaluability records

Each `checklist_ratings` entry requires these fields or validation will block:

| Field | Required | Notes |
| --- | --- | --- |
| `checklist_item_id` | Yes | e.g. `h01_d_01` |
| `heuristic_id` | Yes | e.g. `h01` |
| `platform` | Yes | `desktop` or `mobile` |
| `rating` | Yes | Integer 0-4 |
| `rationale` | Yes | Plain-language reason for the score |
| `evidence_refs` | Yes unless `evidence_limits` explains the gap | List of evidence strings |
| `confidence` | Yes | `high`, `medium`, or `low` |
| `evidence_limits` | Optional but required when evidence refs are unavailable | Describe what could not be observed |

Use the `checklist_rating_contract` from `get_started` as the authoritative field reference. Do not assemble ratings manually from scratch. Prefer the `checklist_ratings` array returned in the `scorecard` from `audit_ux_surface`, which already includes all required fields.

If validation blocks the report, return the blockers and the smallest resubmission path. Do not generate polished artifacts from a blocked payload.

For a full field guide, use `references/report-payload-field-guide.md`.

## Output Size and Token Management

Two UXHC tools produce large output that can overflow context:

**`list_heuristics`**
- Full detail output: ~100–150KB
- Always use `detail_level: "summary"` for rubric discovery and routing decisions
- Use full detail only when you need every checklist item's text and ID for a manual audit submission
- If output is auto-saved to a file, use `jq` to extract targeted sections:
  ```bash
  jq '.heuristics[] | {id, name, item_count}' output.txt
  jq '[.heuristics[] | select(.id == "h11")]' output.txt
  ```

**`audit_ux_surface`**
- Full output on all-profile desktop audit: ~400–500KB
- Use `output_detail: "compact"` when only scores and top findings are needed
- The full file is saved locally — use `jq` to extract what you need:
  ```bash
  jq '{overall_grade, overall_percentage, hil_state}' output.txt
  jq '[.heuristic_scores[] | {id, grade, percentage, top_finding}]' output.txt
  jq '[.top_findings[] | {severity, title, heuristic_id, fix}]' output.txt
  jq '.scorecard.checklist_ratings' output.txt
  ```

## Profile Aliases

`get_started` returns a `profile_aliases` map. These aliases are accepted in profile activation params:

| Alias | Resolves to |
| --- | --- |
| `empathy` | `inclusion` (H12) |
| `content_strategy` | `ux_writing` (H14) |
| `a11y` | `accessibility` (H11) |
| `cx` | `journey` (H13) |

Use canonical profile IDs in final audit calls. Aliases are for convenience in conversation and quick prompts.

## After The Audit: Real Research Handoffs

UXHC can prepare a user for real research, but it should not pretend synthetic walkthroughs are participant evidence.

When the audit reveals issues that need real users:

- use `task-templates:usability-test-plan` to plan a study
- use `task-templates:task-scenarios-write` to write task scenarios
- use `task-templates:screener-criteria` to draft participant criteria

When H11 surfaces severity 3-4 accessibility issues, recommend `patterns:accessibility-reality-check` or a formal accessibility/WCAG pass. Keep the boundary clear: UXHC flags likely risks; it does not certify compliance.

## Atlas Pattern Handoffs

| UXHC need | Atlas ID | How to use it |
| --- | --- | --- |
| Inclusion and Persona Spectrum calibration | `patterns:inclusive-design-framework` | Use with H12 and the Inclusion reviewer to compare permanent, temporary, and situational constraints. |
| Accessibility escalation | `patterns:accessibility-reality-check` | Use after H11 severity 3-4 findings to produce a deeper fix list or engineering handoff. |
| Ability-cost severity calibration | `patterns:fogg-behavior-model-fbm` | Use with H7 and H13 when low ability, low bandwidth, or high cognitive load changes severity. |
| Evaluator bias preflight | `patterns:heuristics-biases-preflight` | Use before accepting severe or surprising findings. |
| Cognitive debiasing | `patterns:cognitive-debiasing` | Use to seek disconfirming evidence and reduce confirmation bias before report generation. |
