explainer-audio-guide

Files (1)

• SKILL.md

SKILL.md (first lines)

# Coordinate one audio guide

Own orchestration only. Resolve the requested terminal Artifact, reconcile exact
inputs and existing outputs, compute the smallest dependency closure, and invoke
the audio phase owners. Do not select content, write dialogue, review it, convert
kana, or synthesize audio inside this skill.

Apply [[explainer-content-workflow-base]] and read its coordination and Artifact
contracts when a profile coordinator delegates a planned audio slice. For an
unrelated exact Markdown source or report, use the standalone contracts of the
same phase owners. If source extraction, report generation, Content modeling,
site generation, or cross-medium consistency is required, route the request to
[[book-explainer]] or [[paper-explainer]] instead of expanding this coordinator.

## Resolve the invocation

Accept one exact starting point:

- a standalone Markdown source or report;
- a Guide plan and its exact source;
- a readable dialogue with its Guide plan and source;
- a dialogue review with all inputs it identifies;
- a validated VOICEVOX dialogue; or
- a workflow run request, Content brief, and Run Manifest delegated by a profile
  coordinator.

Resolve the desired terminal state from the request: Guide plan, reviewed
readable dialogue, validated VOICEVOX dialogue, or narrated audio. Ask only when
that terminal state, content policy, output replacement, or optional human
review is materially ambiguous. Never ask the user to select internal phases.

For standalone creation from Markdown, resolve the Guide policy once, including
guide kind, listener destination, coverage, depth, audience, supporting detail,
pacing, segmentation, duration treatment, and cast pair. Pass those exact
choices forward; later owners must not reconstruct them from conversation.

## Reconcile and plan

Inventory the starting Artifact and every conventional or Manifest-planned
downstream path. Validate recorded provenance and SHA-256 digests. Classify each
relevant output as `reuse`, `create`, `replace`, or `untouched`, then compute the
prerequisite closure from the earliest missing, invalid, or intentionally
changed Artifact.

In workflow mode, treat the immutable Run Manifest as execution authority. Ask
[[explainer-run-plan]] for a new Manifest when the terminal set, policy, input
digest, or replacement closure changes. Accept an existing Manifest only for an
explicit exact-run resume. In standalone mode, do not silently overwrite any
existing output; obtain one explicit replacement decision covering the named
affected paths.

Never reuse a downstream Artifact when any recorded upstream digest differs.
Show the compact `reuse` / `create` / `replace` / `untouched` slice before a
destructive replacement or when the valid starting point is ambiguous.

## Execute the dependency closure

Invoke only the owners required for the resolved terminal Artifact, in order:

1. [[explainer-audio-guide-plan]] creates or replaces the Guide plan.
2. [[explainer-audio-dialogue]] writes the human-readable dialogue.
3. [[explainer-audio-dialogue-review]] independently reviews that exact digest.
4. After `result: pass` and any selected human gate, [[explainer-audio-voicevox]]
   writes and validates the propositionally paired synthesis script.
5. [[explainer-audio-narrate]] synthesizes audio when audio is the terminal.

Pass exact paths and digests returned by one owner to the next. A request for a
readable dialogue includes independent review; do not present an unreviewed
draft as a successful terminal Artifact. A request for VOICEVOX or audio always
includes the same review prerequisite.

## Route review and runtime failures

On `result: revise`, stop forward execution and obey the review's `return_to`:

- `guide-plan` for a defective destination, coverage assignment, required
  facets, Guide structure selection, or explanatory spine;
- `dialogue` when the Guide plan is sound but its realization, fidelity,
  conversational moves, or spoken orientation fails.

In workflow mode, create a new Manifest that replaces the returned-to Artifact
and every requested dependent output. In standalone mode, show those exact
replacement paths and obtain replacement authorization before rerunning. Never
patch the review into `pass`, reuse it for another dialogue digest, or continue
to VOICEVOX while revision is unresolved.

Keep conversion and synthesis failures local when upstream digests remain
valid: kana or pairing failures return to [[explainer-audio-voicevox]]; engine,
encoding, or output failures return to [[explainer-audio-narrate]].

For a selected workflow `dialogue-pilot` gate, present the exact passing
readable dialogue and review, persist the user's decision through the shared
checkpoint contract, and continue only from `approved`. For standalone human
inspection, use the reviewed dialogue as the current terminal and resume later
from its exact paths and digests.

## Finish

Report the starting inputs, resolved terminal, produced and reused Artifacts
with digests, review and validation results, checkpoint decisions, replacements,
and unresolved blockers. Do not claim success beyond the last validated
Artifact.

## Success criteria

- [ ] One exact starting point and terminal Artifact determine the execution.
- [ ] Only the smallest valid dependency closure ran.
- [ ] Every owner received exact paths, digests, policy, and output authority.
- [ ] Reviewed dialogue is the minimum successful content terminal.
- [ ] No `revise` result or stale digest flowed into VOICEVOX or narration.
- [ ] Failures returned to their owning phase without rerunning valid upstream
  work.
- [ ] The final handoff distinguishes produced, reused, replaced, and blocked
  Artifacts.

From choplin/explainer-studio, MIT.

More from choplin/explainer-studio