# Refine Pet Animation

> Refine or replace one animation in an existing Codex v2 pet while preserving all approved identity and unrelated rows. Use for hover, idle, walking, waving, failure, waiting, working, review, FPS or smoothness complaints, unnatural motion, snapping loops, clipping, size inconsistency, or look-direction repairs in spritesheet.webp or PNG atlases.

- Skill: `chadxgpt/refine-pet-animation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add chadxgpt/refine-pet-animation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chadxgpt/refine-pet-animation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: chadxgpt (https://skillmd.com/u/chadxgpt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chadxgpt/refine-pet-animation

---


# Refine Pet Animation

Use `$imagegen` for replacement visuals and the shared deterministic toolkit at `../../scripts` for extraction, preview, row replacement, and validation.

Before acting, read:

- `../../references/animation-rows.md`
- `../../references/codex-pet-contract.md`
- `../../references/qa-rubric.md`

## 1. Diagnose before regenerating

Inspect `pet.json`, the atlas, the current contact sheet or animation preview, and all available source photos.

Map the request to the smallest valid scope:

| User request | State | Row |
| --- | --- | ---: |
| idle, resting, breathing | `idle` | 0 |
| moving screen-right | `running-right` | 1 |
| moving screen-left | `running-left` | 2 |
| greeting or wave | `waving` | 3 |
| hover or pointer reaction | `jumping` | 4 |
| failure or error reaction | `failed` | 5 |
| waiting for input | `waiting` | 6 |
| active work or processing | `running` | 7 |
| reviewing or inspecting | `review` | 8 |
| pointer look directions | complete look row | 9 or 10 |

Separate timing problems from drawing problems. The Codex app owns the durations in `animation-rows.md`; adding more atlas cells does not raise the runtime frame rate. Improve perceived smoothness through even pose spacing, stable registration, clear anticipation and recovery, and a seamless first-to-last transition.

## 2. Lock approved identity

Create a compact repair brief from the current pet and photos:

- traits that must remain unchanged
- target row and exact frame count
- starting and ending pose
- action beats per frame
- stable body anchor and baseline
- specific defect being corrected
- properties from the current row that already pass

Back up `spritesheet.webp` and `pet.json` before replacement. Do not modify unrelated rows.

## 3. Generate one replacement row

Use `$imagegen` with the source photos, canonical reference, current contact sheet, and target-row guide. Request one complete coherent strip on the run's chroma background.

Require:

- exact frame count
- the same individual pet
- complete separated poses
- stable scale and baseline
- natural anatomy and weight transfer
- no crop, overlap, scenery, shadow, labels, or detached effects
- a final pose that returns naturally to the first

If the same defect occurs twice, change the pose design or motion plan instead of repeatedly rewording the same prompt.

## 4. Extract and preview before merging

Place the selected strip at `repair/decoded/<state>.png`, then run:

```bash
python3 ../../scripts/extract_strip_frames.py \
  --decoded-dir /absolute/path/to/repair/decoded \
  --output-dir /absolute/path/to/repair/frames \
  --states "<state>" \
  --method auto \
  --chroma-key "<source chroma key>"

python3 ../../scripts/inspect_frames.py \
  --frames-root /absolute/path/to/repair/frames \
  --json-out /absolute/path/to/repair/review.json \
  --states "<state>" \
  --require-components

python3 ../../scripts/render_animation_previews.py \
  --frames-root /absolute/path/to/repair/frames \
  --output-dir /absolute/path/to/repair/previews \
  --states "<state>"
```

Review the timing-accurate GIF before touching the installed atlas. Compare it with the original at normal pet size. Reject snapping, scale pops, baseline movement, reversed cadence, duplicated poses, unnatural limb motion, or identity drift.

## 5. Replace and validate

For rows 0–8, replace the whole row:

```bash
python3 ../../scripts/replace_atlas_row.py \
  --atlas /absolute/path/to/original/spritesheet.webp \
  --state "<state>" \
  --frames-dir /absolute/path/to/repair/frames/<state> \
  --output /absolute/path/to/repair/spritesheet.png \
  --webp-output /absolute/path/to/repair/spritesheet.webp
```

Then run:

```bash
python3 ../../scripts/despill_atlas_rows.py \
  /absolute/path/to/repair/spritesheet.png \
  --output /absolute/path/to/repair/spritesheet.png \
  --webp-output /absolute/path/to/repair/spritesheet.webp \
  --chroma-key "<source chroma key>" \
  --rows "<row number>" \
  --json-out /absolute/path/to/repair/chroma-despill.json

python3 ../../scripts/validate_atlas.py \
  /absolute/path/to/repair/spritesheet.webp \
  --json-out /absolute/path/to/repair/validation.json \
  --chroma-key "<source chroma key>" \
  --require-v2

python3 ../../scripts/make_contact_sheet.py \
  /absolute/path/to/repair/spritesheet.webp \
  --output /absolute/path/to/repair/contact-sheet.png

python3 ../../scripts/verify_atlas_row_change.py \
  --before /absolute/path/to/original/spritesheet.webp \
  --after /absolute/path/to/repair/spritesheet.webp \
  --allowed-rows "<row number>" \
  --json-out /absolute/path/to/repair/change-scope.json
```

Confirm the changed row passes and `change-scope.json` reports no changes outside the allowed row. Install both `pet.json` and `spritesheet.webp` only after validation.

## Look-direction repairs

Rows 9 and 10 are coherent eight-pose families. Regenerate the complete containing row, preserve the opposite row as continuity evidence, and use the extended-atlas assembly plus direction QA tools from `create-codex-pet`.

Never patch one final look cell. Re-run cardinal semantics, normal-size direction review, continuity measurement, full atlas validation, and the final contact sheet.

## Completion criteria

- The intended action is obvious at normal pet size.
- The motion uses the exact contract frame count and timing.
- Anatomy, markings, scale, and baseline match the approved pet.
- The loop has no visible first-to-last snap.
- Unchanged rows are preserved.
- The v2 atlas and package validate.