---
name: reader-reliability
description: Stage 9 reader QA skill — audit whether a text actually works in the product, classify silent blanks and support gaps, generate support-matrix evidence, and verify reader behavior across supported modes.
allowed-tools: Bash(go:*), Bash(npm:*), Bash(npx:*), Bash(jq:*), Bash(find:*), Bash(ls:*), Bash(git:*), Read, Write, Edit, Grep, Glob
---

# Reader Reliability (Stage 9 Reader QA)

Verify that a text actually works in the Lyceum reader.

This skill is the **Stage 9 owner** for reader reliability and product QA.
It should answer:
- does the reader visibly break for this text?
- are supported display modes free of silent blanks in sampled passages?
- is a problem caused by missing source data, import issues, renderer issues, or client-state issues?
- what support state should the UI disclose for this edition?

It does **not** own:
- Stage 6 semantic alignment correctness
- Stage 8 semantic gloss correctness
- screenshot/E2E mechanics by itself
- final ship promotion

## Quick Status

Interlinear audit harness: !`ls cmd/server/interlinear_audit_test.go 2>/dev/null | wc -l`
Inflection audit harness: !`ls cmd/server/inflection_audit_test.go 2>/dev/null | wc -l`
Deck reliability harness: !`ls tests/e2e/deck-reliability.spec.ts 2>/dev/null | wc -l`
Support matrix generator: !`ls *(inline matrix generation)* 2>/dev/null | wc -l`

## Commands

- `/reader-reliability audit [work]` — Audit sampled reader behavior and classify visible failures
- `/reader-reliability verify [work]` — Run the reader-level verification path and produce a reliability decision
- `/reader-reliability matrix [work]` — Generate or refresh support-matrix evidence for the target edition/work
- `/reader-reliability status [work]` — Summarize reliability findings, support state, and blocking issues

Target: $ARGUMENTS

---

## ⚠️ PRECONDITION: gloss-review must pass first

**Before running Stage 9, verify that Stage 8b (gloss-review) has completed.**

Check for:
- `qa/gloss-review-report.md` exists with PASS verdict, OR
- explicit user override to proceed without formal evaluation

If gloss-review hasn't run, stop and say:
> "Stage 8b (gloss-review) not complete. Run `/skill:gloss-review evaluate [work]` first."

This prevents skipping the mandatory evaluation gate between build and QA.

---

## Owned Responsibilities

### Owns
- sampled text-level reader verification
- no-silent-blanks auditing
- failure classification: source/import/render/client-state/support-gap
- support-matrix/report generation
- reliability recommendation: ready / blocked / partial

### Does not own
- upstream semantic correctness evaluation
- Playwright implementation details on its own
- final import/build promotion

---

## Core Scope

Audit and verify:
- display-option completeness
- inflection-coloring completeness
- interlinear completeness
- popup completeness
- add-to-deck and in-deck state consistency
- section-selection / companion panel consistency
- per-text feature support inventory

### Hard rule
A text is not done until it works in the actual reader.

---

## Workflows

## `/reader-reliability audit`

Audit sampled passages and classify failures.

### Distinguish between
- missing source data
- import bugs
- rendering/template bugs
- client-side state bugs
- unsupported-text/support-policy gaps

### Existing repo evidence
- `cmd/server/interlinear_audit_test.go`
- `cmd/server/inflection_audit_test.go`
- `tests/e2e/deck-reliability.spec.ts`
- `docs/interlinear-featured-text-audit-2026-03-13.md`
- `docs/plutarch-inflection-audit-2026-03-13.md`
- `docs/add-to-deck-reliability-audit-2026-03-13.md`

---

## `/reader-reliability verify`

Run the verification path and produce a recommendation.

### Verify for sampled supported passages
- row/classic reader modes render correctly
- supported interlinear displays have 0 silent blanks
- popup data appears where support is claimed
- toggles behave deterministically
- deck/add-to-deck flows update reader state consistently

### Important note
Use `ui-test` as a helper for Playwright/screenshot execution when browser verification is required.

---

## `/reader-reliability matrix`

Generate or refresh support-matrix evidence.

### Current repo path
- *(support matrix generated inline by pipeline)*
- `data/reader-support-matrix.json`
- `docs/reader-support-matrix-implementation-plan-2026-03-13.md`

### Typical matrix dimensions
- interlinear support
- morphology / inflection support
- layout support
- deck-state support
- versification status
- notes and last-audited timestamp

### Important rule
The UI should not imply a feature is fully supported when the backing data is partial.

---

## `/reader-reliability status`

Summarize:
- sampled audit findings
- support classification
- blocked vs partial vs ready recommendation
- whether the next step is upstream repair or `new-text-ship`

---

## Outputs

### Canonical outputs
```text
$LYCEUM_TEXTS_DIR/<slug>/
├── qa/reliability-report.md
├── state.json
└── replay/stage-history.json
```

### Related repo outputs
- `data/reader-support-matrix.json`
- sampled screenshots / browser evidence
- test output from audit/verification harnesses

---

## Verification Contract

This skill follows the Stage 9 contract from `docs/text-pipeline-skill-verification-2026-03-13.md`.

### Verify
- supported reader modes render without silent blanks for sampled passages
- popup/toggle/state flows behave deterministically
- data gaps are separated from rendering/import/state bugs
- support matrix/report is produced

### Minimum evidence
- `qa/reliability-report.md`
- sampled screenshots and/or test output
- per-text support matrix evidence

### Pass criteria
- sampled supported passages show 0 silent blanks in claimed-supported modes
- popup data appears where support is claimed
- toggle behavior is deterministic
- report distinguishes source-data failures from product-layer failures

### Failure examples
- blanks observed but not classified
- row/classic readers disagree for unexplained reasons
- unsupported states are hidden without recording support policy

### Required next steps
After Stage 9 passes:
- proceed to `new-text-ship` if upstream stages are already approved
- rerun Stage 9 after any promoted Stage 6, 7, or 8 change

---

## Verification

After completing this stage, run the automated verification script:

```bash
bash scripts/verify_stage_9.sh "${SLUG}"
```

Exit codes: 0=PASS (advance), 1=FAIL (block), 2=WARN (advance with notes).
The orchestrator runs this automatically; when executing manually, check the output for [FAIL] or [WARN] lines.

---

## Key Files

| File | Purpose |
|---|---|
| `cmd/server/interlinear_audit_test.go` | Interlinear audit harness |
| `cmd/server/inflection_audit_test.go` | Inflection audit harness |
| `tests/e2e/deck-reliability.spec.ts` | Deck reliability harness |
| *(support matrix generated inline by pipeline)* | Support matrix generator |
| `data/reader-support-matrix.json` | Support matrix artifact |
| `docs/interlinear-featured-text-audit-2026-03-13.md` | Interlinear audit findings |
| `docs/plutarch-inflection-audit-2026-03-13.md` | Inflection audit findings |
| `docs/add-to-deck-reliability-audit-2026-03-13.md` | Deck audit findings |
| `docs/reader-support-matrix-implementation-plan-2026-03-13.md` | Support-matrix plan |
| `.pi/skills/ui-test/SKILL.md` | Browser-verification helper |
| `docs/text-pipeline-skill-architecture-2026-03-13.md` | Ownership and command surface |
| `docs/text-pipeline-skill-verification-2026-03-13.md` | Verification contract |