# ux-dx-evaluation-diagnostician (Unified Skill)

## Core Instructions (SKILL.md)

# UX/DX Evaluation Diagnostician

Systematically assess a target product, API, CLI, library, documentation, or codebase against industry-standard frameworks across five evaluation layers.

## Procedure
1.  **Analyze Input:** Identify the `[TARGET]`, `[LAYER_FOCUS]`, `[AUDIENCE]`, and `[CONTEXT]`.
2.  **Select Layers:** Determine which of the five layers apply to the target.
3.  **Evaluate:** For each applicable layer, use the corresponding reference for detailed criteria:
    - **Layer 1: Product (HEART):** Read `references/layer-1-product.md`.
    - **Layer 2: Engineering (SPACE):** Read `references/layer-2-engineering.md`.
    - **Layer 3: Interface (CLI/API):** Read `references/layer-3-interface.md`.
    - **Layer 4: Ecosystem (CHAOSS):** Read `references/layer-4-ecosystem.md`.
    - **Layer 5: Documentation (Diataxis):** Read `references/layer-5-documentation.md`.
4.  **Synthesize:** Use `references/report-template.md` to generate the final diagnostic report.

## Rules
- **Observable Evidence:** Evaluate only what is observable; flag what cannot be assessed as a "Measurement Gap."
- **Status Rollup:** 
    - CRITICAL finding → Layer is CRITICAL.
    - HIGH finding → Layer is DEGRADED.
- **No Fixing:** Stop after producing the report. Do not offer to fix findings.


---

## Reference: layer-1-product.md

# Layer 1: Product Experience (HEART)

Evaluate the target against the HEART dimensions. Skip if not applicable.

## HEART Dimensions
- **Happiness:** Satisfaction signals, NPS/CSAT/SUS.
- **Engagement:** Interaction depth and frequency.
- **Adoption:** Onboarding velocity, time-to-first-value.
- **Retention:** Churn signals, cohort tracking.
- **Task Success:** Completion rates, time-on-task, error rates.

## Checks
- **Web-based Targets:** If CI is accessible, check Lighthouse/AXE. Note if accessibility testing is only automated (which is insufficient).
- **CI Inaccessible:** Record in "Measurement Gaps".

## Diagnostic Format
Per dimension: `[HEALTHY | DEGRADED | MISSING | N/A]`
- **Evidence:** What was observed.
- **Gap:** What is missing or broken.
- **Recommendation:** Actionable fix.


---

## Reference: layer-2-engineering.md

# Layer 2: Engineering Experience (SPACE / DX Core 4)

Evaluate the engineering experience based on system outcomes. Skip if not applicable.

## SPACE Dimensions
- **Satisfaction:** Sentiment, tool satisfaction.
- **Performance:** System outcomes (change failure rate, MTTR).
- **Activity:** CI/CD telemetry, build times.
- **Communication:** Review response time, ownership clarity.
- **Efficiency:** Flow preservation, onboarding time.

## Evaluation Rules
- **System Outcomes Only:** Do not measure individual output (lines of code, tickets).
- **Oppositional Check:** Speed metrics (deployment frequency) MUST be counterbalanced by Quality metrics (change failure rate, rollback frequency).

## Diagnostic Format
Per dimension: `[HEALTHY | DEGRADED | MISSING | N/A]`
- **Evidence:** What was observed.
- **Gap:** What is missing or broken.
- **Recommendation:** Actionable fix.


---

## Reference: layer-3-interface.md

# Layer 3: Interface Experience (CLI/API)

Evaluate the interface discoverability, conventions, and compliance. Skip if not applicable.

## 3A: CLI Heuristics
- **Discoverability:** `--help` to stdout, tab completion, documented subcommands.
- **Conventions:** POSIX flags, standard exit codes, signal handling.
- **Output:** TTY-aware formatting, `--plain`/`--json` modes, pipe-safe.
- **Errors:** Clear, actionable, contextual, not color-only.
- **Composability:** stdin/stdout pipeline behavior, structured output.

## 3B: API Governance
- **Errors:** RFC 9457 compliance, error codes, documentation URLs.
- **Consistency:** Naming conventions, parameter patterns, versioning.
- **Schema:** OpenAPI spec presence, linting (Spectral or equivalent).
- **Auth UX:** Clear 401/403 distinction, scoping, token lifecycle.
- **Rate limiting:** Documented limits, retry-after headers, graceful degradation.

## Diagnostic Format
Per criterion: `[COMPLIANT | VIOLATION | PARTIAL | N/A]`
- **Evidence:** What was observed.
- **Severity:** `[CRITICAL | HIGH | MEDIUM | LOW]`.
- **Recommendation:** Actionable fix.


---

## Reference: layer-4-ecosystem.md

# Layer 4: Ecosystem Health (CHAOSS + Governance)

Evaluate the health of the project's ecosystem. Skip if not applicable.

## Community Health (CHAOSS)
- **Time to First Response:** > 7 days median = fragile community.
- **Closure Ratio:** < 50% PR merge rate = maintenance risk.
- **Bus Factor:** Factor of 1 = critical risk.
- **Org Diversity:** Single-org dominance = funding/strategy risk.
- **Release Frequency:** 6+ months gap with open issues = abandonment risk.

## Supply Chain Governance
- **Backward Compatibility:** No compat tooling in CI = downstream risk.
- **License Compliance:** Non-compliant or missing licenses.

## Diagnostic Format
Per metric: `[HEALTHY | AT_RISK | CRITICAL | N/A]`
- **Value:** The observed value.
- **Risk:** What is at risk.
- **Recommendation:** Actionable fix.


---

## Reference: layer-5-documentation.md

# Layer 5: Documentation Quality (Diataxis)

Evaluate strict modality separation in documentation. Skip if not applicable.

## Modalities (Diataxis)
- **Tutorials:** Guided learning. Avoid theory injection or reference-style detail.
- **How-To Guides:** Goal-oriented steps. Avoid conceptual digressions or exhaustive parameter lists.
- **Explanations:** Background and rationale. Avoid step-by-step instructions or API signatures.
- **Reference:** Technical specifications. Avoid tutorial guidance or opinion/rationale.

## Checks
- **Prose Linting:** Is automated prose linting (Vale/alex) integrated?
- **Missing Modalities:** Flag absent modalities as critical onboarding gaps.

## Diagnostic Format
Per modality: `[PRESENT | ABSENT | CONTAMINATED]`
- **Boundary Violations:** Where modalities are mixed inappropriately.
- **Coverage:** How much of the topic is covered by this modality.
- **Recommendation:** Actionable fix.


---

## Reference: report-template.md

# UX/DX Evaluation Diagnostic Report Template

Use the following template for the final diagnostic report.

```markdown
# UX/DX Evaluation Report
## Target: [name]
## Scope: [layers evaluated]
## Date: [evaluation date]

## Layer Summary
| Layer | Framework | Status | Critical Findings |
|-------|-----------|--------|-------------------|
| Product | HEART | [HEALTHY|DEGRADED|CRITICAL] | [count] |
| Engineering | SPACE/DX Core 4 | ... | ... |
| Interface | CLI/API Heuristics | ... | ... |
| Ecosystem | CHAOSS | ... | ... |
| Documentation | Diataxis | ... | ... |

## Critical Findings (must-fix)
1. [Layer] [ID]: Description — Impact — Remediation

## High Findings (should-fix)
1. ...

## Cross-Layer Effects
[Cascading friction: e.g., doc gaps (L5) → CLI friction (L3) → dev dissatisfaction (L2)]

## Measurement Gaps
[What could not be evaluated; what data is needed]

## Verdict
Overall Health: [HEALTHY | DEGRADED | CRITICAL]
Highest-friction layer: [layer]
Start here: [which layer to fix first and why]
```


---