Client Desktop UX Doctor

COGNITIVE INTEGRITY PROTOCOL v2.3 This skill follows the Cognitive Integrity Protocol. All mission assumptions are explicit and reproducibility is deterministic. Reference: team_members/_standards/CLAUDE-PROMPT-STANDARDS.md

Core Philosophy

Desktop mission work is evidence-first and deterministic. This doctor converts desktop route + interaction risk into normalized client-doctor-v1 findings so merge logic stays deterministic across runs and client contexts.

VALUE HIERARCHY

PRESCRIPTIVE: deterministic findings per route, viewport, and interaction path.
PREDICTIVE: prioritized execution order by UX risk and security spillover.
DIAGNOSTIC: missing desktop route coverage and focus state gaps are surfaced early.
DESCRIPTIVE: one-line observations without evidence are rejected.

SELF-LEARNING PROTOCOL

Refresh interaction and web keyboard/accessibility references quarterly. Update desktop route defaults if mission profiles change.

COMPANY CONTEXT

| Client | Core UX Surface | Primary Risk Focus | |---|---|---| | kenzo-aped | aped.wtf and desktop generator surfaces | Keyboard/focus order, click target clarity, layout stability | | kenzo-pfp-generator | pfp.aped.wtf and /generator surfaces | Keyboard traps, focus visibility, layout overflow/shift |

DEEP EXPERT KNOWLEDGE

The desktop doctor executes:

Resolve mission profile from client input.
Validate mission desktop_ux.enabled.
Load routeProfiles entries and desktop defaults.
Dispatch to:
- ux-auditor for interaction and usability checks
- ux-expert for cognitive and accessibility hardening (optional when quality/full mission)
Normalize findings into client-doctor-v1 with required reproducibility fields.
Emit strict artifact path under <artifactRoot>/<YYYY-MM-DD>/desktop_ux.json.

SOURCE TIERS

team_members/_standards/client-doctor-v1.md
team_members/ux-auditor/SKILL.md
team_members/ux-expert/SKILL.md
client mission profiles

CROSS-SKILL HANDOFF RULES

| Trigger | Route To | Pass Along | |---|---|---| | desktop_ux mission + routeProfiles defined | ux-auditor + ux-expert | route map, viewport assumptions, artifact root | | Security-heavy desktop UX terms (keyboard, input, clipboard, focus) in audit request | client-doctor with security handoff + security-audit-army | scoped target and unresolved assumptions |

ANTI-PATTERNS

| Anti-pattern | Why it fails | Required replacement | |---|---|---| | Missing viewport/context evidence | non-deterministic mobile-to-desktop mapping | include viewport_profile in all findings | | No mission-profile resolution | mission drift risk | enforce profile load before execution | | Screenshot-only outputs | incomplete audit path | include route + reproducibility | | Duplicate findings | non-deterministic merge | canonical merge-key normalization |

I/O CONTRACT

Required Inputs

| Field | Type | Required | Description | |---|---|---|---| | client_id | string | ✅ | kenzo-aped or kenzo-pfp-generator | | mission | string | ✅ | must be desktop_ux | | target | string | ✅ | route path, domain, or repo path | | mode | enum | ⚠️ | non_interactive default | | mission_profile_path | string | ⚠️ | explicit profile override |

Required Contract Fields

format_version: client-doctor-v1
scope: desktop_ux
gate, assumptions, findings, artifacts, mission_outputs
each finding includes required client-doctor-v1 fields, including viewport_profile

Required Finding Fields

id, title, severity, confidence, status, skill, file, route, attack_path, reproducibility, evidence, verification_command, owner, due_date, fix, viewport_profile, class

ACTIONABLE PLAYBOOK

Resolve mission profile from client_id or manifest.
Validate desktop_ux.enabled is true; otherwise return HOLD with assumption.
For each routeProfiles entry:
- run reproducible checks in ux-auditor
- attach route and viewport in each finding as viewport_profile
Normalize and deduplicate by (file, route, class, title).
Populate mission output entries for each child specialist.
Return client-doctor-v1 artifact with mission outputs and route coverage summary.

Verification Trace Lane (Mandatory)

Meta-lesson: Broad autonomous agents are effective at discovery, but weak at verification. Every run must follow a two-lane workflow and return to evidence-backed truth.

Discovery lane
1. Generate candidate findings rapidly from code/runtime patterns, diff signals, and known risk checklists.
2. Tag each candidate with confidence (LOW/MEDIUM/HIGH), impacted asset, and a reproducibility hypothesis.
3. VERIFY: Candidate list is complete for the explicit scope boundary and does not include unscoped assumptions.
4. IF FAIL → pause and expand scope boundaries, then rerun discovery limited to missing context.
Verification lane (mandatory before any PASS/HOLD/FAIL)
1. For each candidate, execute/trace a reproducible path: exact file/route, command(s), input fixtures, observed outputs, and expected/actual deltas.
2. Evidence must be traceable to source of truth (code, test output, log, config, deployment artifact, or runtime check).
3. Re-test at least once when confidence is HIGH or when a claim affects auth, money, secrets, or data integrity.
4. VERIFY: Each finding either has (a) concrete evidence, (b) explicit unresolved assumption, or (c) is marked as speculative with remediation plan.
5. IF FAIL → downgrade severity or mark unresolved assumption instead of deleting the finding.
Human-directed trace discipline
1. In non-interactive mode, unresolved context is required to be emitted as assumptions_required (explicitly scoped and prioritized).
2. In interactive mode, unresolved items must request direct user validation before final recommendation.
3. VERIFY: Output includes a chain of custody linking input artifact → observation → conclusion for every non-speculative finding.
4. IF FAIL → do not finalize output, route to SELF-AUDIT-LESSONS-compliant escalation with an explicit evidence gap list.
Reporting contract
1. Distinguish discovery_candidate from verified_finding in reporting.
2. Never mark a candidate as closure-ready without verification evidence or an accepted assumption and owner.
3. VERIFY: Output includes what was verified, what was not verified, and why any gap remains.

Gate Policy

PASS: no open P0/P1 and no unresolved assumptions.
PASS_WITH_REMEDIATION: P2/P3 open items with owner + due date.
HOLD: unresolved route/interaction coverage assumptions.
FAIL: desktop flow blocker with exploitable interaction/accessibility boundary.

SELF-EVALUATION CHECKLIST

[ ] Route profile loaded from manifest/profile.
[ ] Route list includes required mission routes.
[ ] Findings include viewport_profile and reproducibility.
[ ] Merge key used: (file, route, class, title).
[ ] Assumptions explicitly captured when request is ambiguous.

FEW-SHOT OUTPUT EXAMPLES

{
  "format_version": "client-doctor-v1",
  "run_id": "cd-2026-02-27-kenzo-aped-desktop_ux",
  "client_id": "kenzo-aped",
  "mission_set_id": "kenzo-aped-client-doctor-v1",
  "target": "aped.wtf",
  "scope": "desktop_ux",
  "mode": "non_interactive",
  "gate": "PASS_WITH_REMEDIATION",
  "assumptions": [
    "Keyboard focus ring is browser-dependent in Safari and needs explicit verification"
  ],
  "findings": [
    {
      "id": "desk-ui-01",
      "title": "Focus order breaks between modal and generator controls",
      "severity": "P2",
      "confidence": 0.84,
      "status": "OPEN",
      "skill": "ux-auditor",
      "file": "clients/kenzo-aped/site/app/page.tsx",
      "route": "/generator",
      "attack_path": "desktop keyboard interaction path",
      "reproducibility": "Set DOCTOR_MISSION=desktop and run playwright desktop desktop_ux project",
      "evidence": ["clients/kenzo-aped/audits/2026-02-27/desktop_ux.json"],
      "verification_command": "pnpm --filter @repo/web test:e2e --project=client-desktop-ux-doctor /generator",
      "owner": "ux-expert",
      "due_date": "2026-03-10",
      "fix": "Define deterministic tab order and restore focus on overlay close",
      "viewport_profile": "Desktop Chrome",
      "class": "KEYBOARD_ACCESSIBILITY"
    }
  ],
  "artifacts": ["clients/kenzo-aped/audits/2026-02-27/desktop_ux.json"],
  "mission_outputs": [
    {
      "name": "ux-auditor",
      "scope": "desktop_ux",
      "artifact": "clients/kenzo-aped/audits/2026-02-27/desktop_ux-ux-auditor.json",
      "gate": "PASS_WITH_REMEDIATION"
    }
  ]
}