---
name: story-repair
description: Use when Alex asks Hermes to repair specific scenes or shots in a video-story project, usually by referencing director's cut labels like scene 2 shot 4 and providing creative repair instructions.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [story, repair, video-story, directors-cut]
    related_skills: [story, story-yolo, systematic-debugging]
---

# /story-repair — Scene/Shot Repair Director

## Overview

Use this when Alex gives repair notes for an existing `video-story` project. The director's cut overlays `SCENE N · SHOT M`, so Alex can say things like “repair scene 2 shot 4: make the dog face camera and keep the red jacket.”

## Inputs to Extract

- Project ID or URL. If missing, use the most recent video-story project if unambiguous; otherwise ask for the project link/ID.
- Target scene numbers.
- Target shot numbers or scene+shot tuples.
- Repair instruction: visual, continuity, motion, dialogue, pacing, style, safety/NSFW workaround.
- Whether to regenerate frames, video, lipsync, final clean cut, and/or director's cut.

## API

Base:

```bash
BASE=http://localhost:4015
TOKEN="$HERMES_AUTOMATION_TOKEN"
```

Session-specific implementation notes and examples are kept in `references/social-creative-telegram-repair.md`. Consult it when working on Telegram-driven repair loops, review-video overlays, or frame-specific repairs.

Production map:

```bash
curl -sS "$BASE/api/hermes/projects/$PROJECT_ID/production-map" \
  -H "Authorization: Bearer $TOKEN"
```

Repair:

```bash
curl -sS -X POST "$BASE/api/hermes/projects/$PROJECT_ID/repair" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "instructions": "...",
    "shots": [{"scene_number": 2, "shot_number": 4}],
    "regenerate_frames": true,
    "regenerate_video": true,
    "lipsync": true,
    "directors_cut": true
  }'
```

Status:

```bash
curl -sS "$BASE/api/hermes/projects/$PROJECT_ID/repair-status" \
  -H "Authorization: Bearer $TOKEN"
```

Director's cut / review video:

```bash
# Legacy director's cut
curl -sS -X POST "$BASE/api/hermes/projects/$PROJECT_ID/assemble-directors-cut" \
  -H "Authorization: Bearer $TOKEN"

# Preferred labeled review export: writes final_video_review.mp4 and overlays SCENE N · SHOT M + timing.
curl -sS -X POST "$BASE/api/hermes/projects/$PROJECT_ID/assemble-review-video" \
  -H "Authorization: Bearer $TOKEN"

curl -sS "$BASE/api/hermes/projects/$PROJECT_ID/review-video" \
  -H "Authorization: Bearer $TOKEN"
```

Single-frame repair for precise notes:

```bash
# Use when Alex asks for only a first/last frame, e.g. “last frame of the last shot”.
# 1) Resolve scene/shot from the production map or DB.
# 2) Set only the relevant *_frame_prompt_addition and clear only that frame URL + that shot video.
# 3) Generate only that frame.
curl -sS -X POST "$BASE/api/shots/$SHOT_ID/generate-single-frame" \
  -H 'Content-Type: application/json' \
  -d '{"frame_type":"last"}'

# 4) Regenerate only that shot video, then rebuild review/clean exports.
curl -sS -X POST "$BASE/api/shots/$SHOT_ID/generate-video"
curl -sS -X POST "$BASE/api/projects/$PROJECT_ID/assemble"
```

## Repair Strategy

- Fetch the production map first so the repair is anchored in current scenes, shots, characters, sets, props, and references.
- For review workflows, prefer the `assemble-review-video` export over the legacy director's cut: it creates a dedicated labeled review MP4 (`final_video_review.mp4`) with `SCENE N · SHOT M` overlays while preserving the clean `final_video.mp4`.
- If Alex asks for “the last frame of the last shot/scene” or another frame-specific edit, do **not** use the broad `/repair` endpoint first. Resolve the target shot, set only `first_frame_prompt_addition` or `last_frame_prompt_addition`, clear only that frame URL and that shot’s video URL/status, then run `generate-single-frame` and `generate-video` for that shot.
- After a single-frame edit, rebuild both the labeled review video and clean final export so Alex can compare the change in context.
- **Verify the export tail actually changed**: Video Story’s Frames/Assets UI can show the regenerated frame while the exported MP4 still uses a stale local clip cache. Extract/inspect the affected exported frame or clip after assembly before telling Alex the repair landed.
- If Alex names only a scene, repair all shots in that scene.
- If Alex names a shot without scene and shot numbers repeat, ask or infer from context.
- Preserve canon: character identity, wardrobe, environment, prop continuity.
- Prefer precise prompt additions over broad style changes.
- For bad motion, simplify action and camera movement rather than overprompting.
- For lip sync failures, regenerate video and lipsync only dialogue shots.
- After repair, produce a new director's cut unless Alex asks for clean final only.

## Response Format

- Repair started: project + target scene/shot list + directive summary.
- While pending: percent/message from repair status.
- Complete: review video or director's cut URL/path + ask for next notes by scene/shot label. If the repair was frame-specific, also mention the clean final export path.

## Pitfalls

- Telegram repair loops need an explicit pending edit context keyed by chat/thread/user or by the review item; callback data should stay compact (`vsedit:<verb>:<review_id>`) and larger state should live in durable app/gateway state.
- Exact scene/shot references are reliable now. Semantic notes like “the part where Jupiter appears” should fetch the production map, infer likely targets, and ask for confirmation if confidence is low.
- Provider-side video generation can fail transiently (for example remote CUDA OOM). Treat this as retryable for the same single-shot generation; the durable lesson is to retry the shot, not to broaden the repair scope.
- Export assembly may reuse stale local shot clips from `uploads/<project>/export/temp` even after a frame/shot is regenerated, especially when the remote object key/URL is overwritten in place. Cache validation must consider the shot’s current source clip/version, and manual verification should delete the affected `shot_<start_time>*`, normalized clip, and `video_only.mp4` temp artifacts before rebuilding if needed.
- Avoid overwriting the original Creative-approved output silently. Repair iterations should produce review/final variants with provenance whenever the output is being handed back into Hermes Creative.

## Verification Checklist

- [ ] Project/targets resolved.
- [ ] Production map checked.
- [ ] Repair API accepted request.
- [ ] Status polled to completion or reported actionable failure.
- [ ] Director's cut updated when requested.
- [ ] Clean export rebuilt when requested.
- [ ] A frame/clip from the rebuilt MP4 was extracted or visually inspected to prove the changed asset is actually present in the export, not only in the timeline/asset views.