---
name: text-replay
description: Cross-stage replay orchestrator — map a user request to the correct replay profile, compute downstream invalidations, update pipeline state/history, and coordinate which stages must run next for one existing text.
allowed-tools: Bash(go:*), Bash(jq:*), Bash(find:*), Bash(ls:*), Bash(git:*), Read, Write, Edit, Grep, Glob
---

# Text Replay (Cross-Stage Orchestrator)

Plan and manage replay of one part of the canonical pipeline for one existing text.

This skill is the **cross-stage replay orchestrator**.
It should answer:
- what replay profile matches the request?
- which stages need to run now?
- which downstream stages become invalidated?
- what approved artifacts can be reused safely?
- what should the next skill invocations be?

It does **not** own:
- any one stage's artifact generation
- semantic evaluation of stage outputs
- final ship promotion

## Quick Status

Existing workspaces: !`find ${LYCEUM_TEXTS_DIR:-output/texts} -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l`
Replay histories: !`find ${LYCEUM_TEXTS_DIR:-output/texts} -path '*/replay/stage-history.json' 2>/dev/null | wc -l`
Profiles defined: !`grep -n "Profile[A-Z]" internal/textpipeline/textpipeline.go 2>/dev/null | wc -l`
Invalidation rules defined: !`grep -n "var invalidationRules" -A20 internal/textpipeline/textpipeline.go 2>/dev/null | wc -l`

## Commands

- `/text-replay plan [work] --profile <profile>` — Compute the replay scope and downstream invalidations
- `/text-replay run [work] --profile <profile>` — Update workspace state/history and produce an execution-ready replay plan
- `/text-replay invalidate [work] --from <stage>` — Explicitly mark downstream stages invalidated from a changed stage
- `/text-replay status [work]` — Summarize replay history, invalidated stages, and next required stage owners

Target: $ARGUMENTS

---

## Owned Responsibilities

### Owns
- mapping user intent to replay profile
- determining stage scope for a replay
- computing downstream invalidations
- recording replay events in state/history
- deciding what stage owners must run next

### Does not own
- creating source/interlinear/versification artifacts itself
- evaluator decisions for Stage 8 or Stage 9
- final promotion/import

---

## Replay Model

The replay profiles currently encoded in `internal/textpipeline/textpipeline.go` are:
- `source-upgrade`
- `cleaning`
- `segmentation`
- `witness-upgrade`
- `versification`
- `transliteration`
- `interlinear`
- `treebank-enrichment`
- `reliability`
- `full-rehab`

### Important rule
Any replayed stage must declare which downstream stages are invalidated.

Current invalidation examples encoded in code:
- source discovery invalidates acquisition through human review
- cleaning invalidates segmentation through human review
- witness ranking invalidates alignment, interlinear, and QA
- transliteration invalidates reader QA and review, but not alignment
- interlinear invalidates reader QA and review

---

## Workflows

## `/text-replay plan`

Use before touching an existing text.

### Determine
1. target workspace slug
2. requested replay profile
3. stages included by that profile
4. which of those stages are already done, blocked, or invalidated
5. what downstream stages must be rerun or reverified
6. what can be safely reused

### Useful checks
```bash
nix-shell -p jq --run "jq '.profile, .requested_stages' ${LYCEUM_TEXTS_DIR:-output/texts}/SLUG/manifest.json"
```

```bash
nix-shell -p jq --run "jq '.current_stage, .invalidated_stages, .stages' ${LYCEUM_TEXTS_DIR:-output/texts}/SLUG/state.json"
```

---

## `/text-replay run`

Create an execution-ready replay plan.

### Typical steps
1. load workspace manifest and current state
2. resolve profile to stage list
3. compare requested profile against current stage statuses
4. compute invalidations from the earliest changed stage
5. update `state.json`
6. append a replay event to `replay/stage-history.json`
7. report the ordered list of stage owners to run next

### Current implementation basis
- replay profile definitions in `internal/textpipeline/textpipeline.go`
- downstream invalidation rules in `internal/textpipeline/textpipeline.go`

### Current limitation
The repo has the bootstrap/state model, but not yet a full stage executor.

So this skill currently focuses on:
- planning accurately
- updating state/history accurately
- making the next step explicit

---

## `/text-replay invalidate`

Use when a stage changed and you need to mark downstream artifacts stale.

### Examples
- clean Greek source changed -> invalidate segmentation, versification, transliteration, interlinear, reader QA, human review
- witness selection changed -> invalidate versification, interlinear, reader QA, human review
- transliteration rules changed -> invalidate reader QA and human review only

### Goal
Make invalidations explicit and auditable rather than inferred from memory.

---

## `/text-replay status`

Summarize:
- current replay profile or last replayed profile
- invalidated stages
- stage-history tail
- current blocking stage
- next required stage owner(s)

---

## Outputs

### Canonical outputs
- replay plan
- updated `state.json`
- updated `replay/stage-history.json`
- notes on which downstream stages must rerun or reverify

### Target workspace files
```text
$LYCEUM_TEXTS_DIR/<slug>/
├── manifest.json
├── state.json
└── replay/stage-history.json
```

---

## Verification Contract

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

### Verify
- requested replay profile maps to the correct stages
- invalidated downstream stages are correct
- resume behavior respects reusable artifacts where valid
- stage history is appended correctly

### Minimum evidence
- replay plan
- updated `state.json`
- updated `replay/stage-history.json`

### Pass criteria
- selected stages match the replay profile definition
- invalidation set matches stage dependency rules
- replay notes explain why downstream stages were or were not invalidated
- history is appended, not overwritten

### Failure examples
- interlinear replay fails to invalidate reader QA
- transliteration replay incorrectly invalidates versification
- replay profile selection does not match the request
- stage history loses earlier events

### Required next steps
After replay planning:
- invoke the required stage owners in order
- rerun evaluators for any invalidated downstream stage
- do not treat replay planning as replay completion

---

## Key Files

| File | Purpose |
|---|---|
| `internal/textpipeline/textpipeline.go` | Profile definitions and invalidation rules |
| `internal/textpipeline/textpipeline_test.go` | Tests for requested stages/invalidation behavior |
| `scripts/init_text_pipeline_workspace.go` | Workspace bootstrap entrypoint |
| `docs/text-pipeline-bootstrap-2026-03-13.md` | Bootstrap and replay profile overview |
| `docs/text-pipeline-master-plan-2026-03-13.md` | Canonical replay matrix |
| `docs/text-pipeline-skill-architecture-2026-03-13.md` | Ownership and command surface |
| `docs/text-pipeline-skill-verification-2026-03-13.md` | Verification contract |