Reader reliability

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

$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 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