Client Mobile 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

Mobile mission work is execution-only; this doctor never edits product code. It converts route + viewport requirements into normalized client-doctor-v1 findings so client-wide merge logic remains deterministic.

VALUE HIERARCHY

PRESCRIPTIVE: deterministic findings per route and viewport profile.
PREDICTIVE: prioritized execution order by risk of conversion and security impact.
DIAGNOSTIC: missing route coverage and viewport context are surfaced immediately.
DESCRIPTIVE: one-line observations not attached to evidence are rejected.

SELF-LEARNING PROTOCOL

Refresh web/mobile accessibility and device behavior references quarterly. Update route profiles if mission profiles change.

COMPANY CONTEXT

| Client | Core UX Surface | Primary Risk Focus | |---|---|---| | kenzo-aped | aped.wtf and /generator surfaces | Touch target, focus path, Safari/WebKit behavior | | kenzo-pfp-generator | pfp.aped.wtf and /generator surfaces | Gesture correctness, viewport adaptation, touch ergonomics |

DEEP EXPERT KNOWLEDGE

The mobile doctor executes this sequence:

Resolve mission profile from client input.
Validate mission set includes mobile_ux.enabled.
Load routeProfiles entries and required viewport assumptions.
Dispatch to:
- ux-auditor for interaction and usability checks
- ux-expert for accessibility and cognition-risk 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>/mobile_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 | |---|---|---| | mobile_ux mission + routeProfiles defined | ux-auditor + ux-expert | route map, viewport assumptions, artifact root | | Security-heavy mobile UX terms (touch-jacking, jank, keyboard, input) inside 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 evidence | cannot reproduce findings | require viewport_profile on every finding | | Screenshot-only results | no route/reproducibility trace | include route IDs and commands | | Duplicate findings | merges become non-deterministic | normalize by merge key |

I/O CONTRACT

Required Inputs

| Field | Type | Required | Description | |---|---|---|---| | client_id | string | ✅ | kenzo-aped or kenzo-pfp-generator | | mission | string | ✅ | must be mobile_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: mobile_ux
gate, assumptions, findings, artifacts, mission_outputs
each finding contains 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 mobile_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 viewport/route coverage assumptions.
FAIL: mobile flow blocker with exploitable accessibility/security 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-mobile_ux",
  "client_id": "kenzo-aped",
  "mission_set_id": "kenzo-aped-client-doctor-v1",
  "target": "pfp.aped.wtf",
  "scope": "mobile_ux",
  "mode": "non_interactive",
  "gate": "PASS_WITH_REMEDIATION",
  "assumptions": [
    "Safari WebKit behavior for fixed positioning is not explicitly documented in profile"
  ],
  "findings": [
    {
      "id": "mob-ui-01",
      "title": "Touch target below WCAG-recommended 44px in /generator CTA",
      "severity": "P2",
      "confidence": 0.88,
      "status": "OPEN",
      "skill": "ux-auditor",
      "file": "clients/kenzo-aped/site/components/generator.tsx",
      "route": "/generator",
      "attack_path": "mobile interaction path",
      "reproducibility": "Set DOCTOR_MISSION=mobile and run iPhone 13 project",
      "evidence": ["clients/kenzo-aped/audits/2026-02-27/mobile_ux.json"],
      "verification_command": "pnpm --filter @repo/web test:e2e --project=client-mobile-ux-doctor /generator",
      "owner": "ux-auditor",
      "due_date": "2026-03-10",
      "fix": "Increase CTA hit area to minimum 44px and spacing policy in mobile layout",
      "viewport_profile": "iPhone 13",
      "class": "TOUCH_TARGET"
    }
  ],
  "artifacts": ["clients/kenzo-aped/audits/2026-02-27/mobile_ux.json"],
  "mission_outputs": [
    {
      "name": "ux-auditor",
      "scope": "mobile_ux",
      "artifact": "clients/kenzo-aped/audits/2026-02-27/mobile_ux-ux-auditor.json",
      "gate": "PASS_WITH_REMEDIATION"
    }
  ]
}