{
  "version": "1.0",
  "shot_id": "shot_01",
  "brand_lock_ref": "brand-lock.snapshot.md",
  "image_ref": "frames/round-1/shot_01.png",
  "verdict": "ACCEPT",
  "confidence": "HIGH",
  "working": [
    "Framing matches the shot spec: MCU, eye level, subject anchored frame-left with negative space right.",
    "Character matches the series_lock anchor verbatim: salt-and-pepper hair, navy crewneck.",
    "Palette and color grade sit inside the brand-lock; nothing from the never-list appears.",
    "Hands, eyes, and skin texture are clean; no AI artifacts."
  ],
  "issues": [
    {
      "layer": "Technical",
      "severity": "minor",
      "note": "Color grade reads a touch cool versus the warm-afternoon spec.",
      "fix_type": "post-level",
      "fix": "Push warmth +5 in the grade. No re-generation needed."
    }
  ]
}

{
  "version": "1.0",
  "shot_id": "shot_03",
  "brand_lock_ref": "brand-lock.snapshot.md",
  "image_ref": "frames/round-1/shot_03.png",
  "verdict": "REVISE",
  "confidence": "HIGH",
  "working": [
    "Composition reserves the right two-thirds of the frame for the text overlay, matching the shot_03 rationale.",
    "Lighting direction matches series_lock: window-left, warm afternoon.",
    "Mood reads as calm and considered, on-brand."
  ],
  "issues": [
    {
      "layer": "Series Lock",
      "severity": "major",
      "note": "Character has brown hair; series_lock specifies salt-and-pepper. Verbatim-anchor failure with a clear fix, so this caps the verdict at REVISE rather than forcing REJECT.",
      "fix_type": "prompt-level",
      "fix": "Add 'salt-and-pepper hair' to the character anchor in the prompt; it is currently missing. Re-roll."
    },
    {
      "layer": "Technical",
      "severity": "major",
      "note": "Left hand on the laptop has six fingers (known Flux failure mode).",
      "fix_type": "re-roll",
      "fix": "Re-roll 2-3 times with the same prompt and pick a clean sample."
    },
    {
      "layer": "Shot Spec",
      "severity": "minor",
      "note": "Generated as MS but the spec called for MCU; subject is slightly small in frame.",
      "fix_type": "prompt-level",
      "fix": "Change 'medium shot' to 'medium close-up' in the prompt. Re-roll."
    }
  ]
}

# Critique Rubric

The structured layer-by-layer pass. Use this as the checklist when reviewing a generated image.

## Layer 1. Brand Lock check

| Check | Pass | Soft fail | Hard fail |
|---|---|---|---|
| Palette | Image colors come from brand-lock palette | Colors close but slightly off | Colors not in palette at all |
| Mood adjectives | Image reads as the brand mood | Mood reads as adjacent (e.g. "calm" vs "neutral") | Image reads as a different mood (e.g. "energetic" when brief was "calm") |
| "Never" list | None of the items in the never list are present | One item in the never list shows softly | Multiple never-list violations |
| Aspect ratio | Matches `project.aspect` | Within a crop of the spec | Wrong aspect |

Hard fail on Brand Lock = REJECT or REVISE depending on whether prompt fix exists.

## Layer 2. Series Lock check

| Check | Pass | Soft fail | Hard fail |
|---|---|---|---|
| Character anchor | All described features visible | One minor feature off (e.g. wrong shirt color) | Wrong person (different age/race/build than anchor) |
| Environment | Matches series_lock | Slight environment drift | Different environment entirely |
| Lighting direction | Matches series_lock | Lighting is right but slightly different angle | Lighting from wrong direction (continuity break) |
| Color grade | Matches series_lock | Slight tonal drift | Different color grade |

Hard fail on Series Lock = REJECT (continuity break) or REVISE if specific fix available.

## Layer 3. Shot Spec check

| Check | Pass | Soft fail | Hard fail |
|---|---|---|---|
| Framing | Matches spec (ECU/CU/MS/etc.) | One step off (e.g. MS instead of MCU) | Two+ steps off |
| Angle | Matches spec | Slight angle variation | Wrong angle (low when spec was eye-level) |
| Subject action | Matches `subject` description | Subject doing similar but slightly different action | Subject doing wrong action |
| Depth of field | Matches if specified | Slight DOF variation | Deep when shallow was specified |

Soft fail = post-level fix or accept. Hard fail = revise.

## Layer 4. Composition check

| Check | Pass | Soft fail | Hard fail |
|---|---|---|---|
| Negative space for text | Reserved per spec | Reserved but tight | No reserved space, overlay won't fit |
| Subject placement | Matches rationale | Slightly off (subject in left-third vs right-third) | Subject blocks where text was meant to go |
| Eye-line | Looks where intended | Slight gaze direction off | Looking the wrong way |
| Headroom | Appropriate | Slightly tight or loose | Cropped at hairline / huge headroom |

Composition fails are usually prompt-level fixable. Re-roll with explicit composition language.

## Layer 5. Technical check

| Check | Pass | Soft fail | Hard fail |
|---|---|---|---|
| Hands | Anatomically correct | Slight finger weirdness | Six fingers, fused fingers, wrong joints |
| Eyes | Symmetrical, focused | Slight asymmetry | Wonky eyes, wrong reflections |
| Skin texture | Natural | Slightly plastic | Heavy AI plastic |
| Anatomy | Correct | Minor weirdness | Major anatomy errors |
| Background artifacts | Clean | Minor weirdness | Distorted text, melted objects, impossible geometry |

Technical hard fails are almost always **re-roll required**. The prompt was probably fine; the generator just produced a bad sample. Budget 2–3 re-rolls.

## Layer 6. Continuity check (if previous shots available)

| Check | Pass | Soft fail | Hard fail |
|---|---|---|---|
| Character match | Same person, same look | Slight drift | Clearly different person |
| Lighting continuity | Same direction, time of day | Subtle shift | Direction reversed, time of day jumped |
| Environment continuity | Same space | Slight environment drift | Different space |
| Color grade match | Identical | Subtle shift | Visibly different |

Continuity hard fails break the storyboard. REVISE with verbatim-anchor checks on the prompt.

## From pass/fail to severity

The tables above grade each check as pass, soft fail, or hard fail. The JSON critique
records a severity instead, and the verdict is derived from those severities. Map them
this way, and only this way:

| Rubric result | Severity | Why |
|---|---|---|
| Soft fail on any layer | `minor` | Post can absorb it. `fix_type` is usually `post-level` |
| Hard fail **with** a clear fix path | `major` | A prompt change or a re-roll resolves it |
| Hard fail on Brand Lock or Series Lock **with no** fix path | `blocking` | Nothing downstream recovers this |
| Any defect that makes the asset unusable | `blocking` | Same, regardless of layer |

## Aggregating verdict

The verdict follows from the severities. It is not a separate judgement:

| Severities present | Verdict |
|---|---|
| any `blocking` | REJECT |
| three or more `major` | REJECT |
| one or two `major` | REVISE |
| only `minor`, or none | ACCEPT (with post notes) |

`tools/validate_critique.py` enforces exactly this table, so a critique that disagrees with
it fails rather than shipping. Earlier versions of this file counted hard fails and called
3+ a REJECT while the skill said "escalate at your discretion." Those two rules disagreed,
and the disagreement is the reason the threshold is now a number.

Soft fails are noted but don't change the verdict on their own. If you have three or more of
them, look again: a cluster of soft fails usually means one of them is really a hard fail
you talked yourself out of.

## Speed bumps to remember

- **Don't critique what wasn't asked**, if the spec didn't call for cinematic mood, don't say "could be more cinematic"
- **Don't pile-on once verdict is set**, if you're rejecting, list the issues that drive the rejection; don't list every cosmetic concern
- **Be specific, always**, "lighting is off" is not a critique; "key light is camera-right but series_lock says camera-left" is
- **Cite the layer**, every issue gets tagged with which layer it falls under. This makes the fix path obvious
- **Distinguish prompt failure from generator failure**, if the prompt was fine and the generator produced garbage hands, that's "re-roll required", not "fix the prompt"

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://whystrohm.com/schemas/shotkit/critique.schema.json",
  "title": "Critique",
  "description": "Machine-readable verdict for one generated frame reviewed against its shot spec and brand-lock. The structured sibling of the markdown critique. Version 1.1 adds run provenance: the frame, prompt, and brand-lock are identified by content hash as well as by path, so a verdict can be proven to describe the bytes that were actually reviewed. Every provenance field is required at 1.1 and explicitly nullable, so an absent input is a recorded decision rather than an omission.",
  "type": "object",
  "required": ["version", "verdict", "confidence", "issues"],
  "additionalProperties": false,
  "properties": {
    "version": {
      "type": "string",
      "enum": ["1.0", "1.1"],
      "description": "1.1 adds run_id, round, created_at, the *_sha256 hashes, prompt_ref, generator, model_version, seed, and the meta passthrough. 1.0 documents remain valid and are treated as legacy: they carry a verdict with no proof of what it reviewed."
    },
    "meta": {
      "type": "object",
      "description": "Forward-compat passthrough for tooling that needs to annotate a critique without a schema bump. Ignored by core skills.",
      "additionalProperties": true
    },
    "run_id": {
      "oneOf": [
        { "type": "null" },
        { "type": "string", "pattern": "^[0-9]{8}T[0-9]{6}Z-[0-9a-f]{8}$" }
      ],
      "description": "The run this critique belongs to. Matches run.json:run_id. Format: UTC compact timestamp, a dash, then 8 hex characters."
    },
    "round": {
      "oneOf": [
        { "type": "null" },
        { "type": "integer", "minimum": 1 }
      ],
      "description": "Revision round, 1-indexed. Round 1 is the first generation pass."
    },
    "created_at": {
      "oneOf": [
        { "type": "null" },
        {
          "type": "string",
          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
        }
      ],
      "description": "UTC ISO-8601 instant the critique was written. Second precision, trailing Z required."
    },
    "shot_id": {
      "oneOf": [
        { "type": "null" },
        { "type": "string", "pattern": "^shot_[0-9]{2,3}$" }
      ],
      "description": "Shot this frame was generated for. Null when critiquing a standalone image with no storyboard."
    },
    "brand_lock_ref": {
      "oneOf": [
        { "type": "null" },
        { "type": "string", "minLength": 1 }
      ],
      "description": "Path to the brand-lock.snapshot.md the frame was judged against, relative to the output directory root. Null when no brand-lock was available, which caps confidence at MEDIUM."
    },
    "brand_lock_sha256": {
      "oneOf": [
        { "type": "null" },
        { "type": "string", "pattern": "^[0-9a-f]{64}$" }
      ],
      "description": "SHA-256 of the brand-lock file as read. Null only when brand_lock_ref is null."
    },
    "image_ref": {
      "oneOf": [
        { "type": "null" },
        { "type": "string", "minLength": 1 }
      ],
      "description": "Path to the frame that was critiqued, relative to the output directory root."
    },
    "image_sha256": {
      "oneOf": [
        { "type": "null" },
        { "type": "string", "pattern": "^[0-9a-f]{64}$" }
      ],
      "description": "SHA-256 of the frame bytes as reviewed. This is what makes the verdict falsifiable: if the file at image_ref no longer hashes to this value, the verdict does not describe it."
    },
    "prompt_ref": {
      "oneOf": [
        { "type": "null" },
        { "type": "string", "minLength": 1 }
      ],
      "description": "Path to the prompt file the frame was generated from, relative to the output directory root. Null when the prompt is unknown, which caps confidence at MEDIUM."
    },
    "prompt_sha256": {
      "oneOf": [
        { "type": "null" },
        { "type": "string", "pattern": "^[0-9a-f]{64}$" }
      ],
      "description": "SHA-256 of the prompt file. Null only when prompt_ref is null."
    },
    "generator": {
      "oneOf": [
        { "type": "null" },
        { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }
      ],
      "description": "Generator id that produced the frame. Must match an id in visual-prompt-forge/adapters/_capabilities.json. Null when unknown."
    },
    "model_version": {
      "oneOf": [
        { "type": "null" },
        { "type": "string", "minLength": 1 }
      ],
      "description": "Model version string as of generation, copied from the capability matrix entry. The matrix records what is current; this records what ran."
    },
    "seed": {
      "oneOf": [
        { "type": "null" },
        { "type": "integer" },
        { "type": "string", "minLength": 1 }
      ],
      "description": "Generation seed if the generator exposes one. Null when it does not."
    },
    "verdict": {
      "type": "string",
      "enum": ["ACCEPT", "REVISE", "REJECT"]
    },
    "confidence": {
      "type": "string",
      "enum": ["HIGH", "MEDIUM", "LOW"]
    },
    "working": {
      "type": "array",
      "description": "Concrete positives. Observations, not flattery.",
      "items": { "type": "string", "minLength": 1 }
    },
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["layer", "severity", "note", "fix_type", "fix"],
        "additionalProperties": false,
        "properties": {
          "layer": {
            "type": "string",
            "enum": ["Brand Lock", "Series Lock", "Shot Spec", "Composition", "Technical", "Continuity"]
          },
          "severity": {
            "type": "string",
            "enum": ["minor", "major", "blocking"],
            "description": "Any blocking issue forces REJECT. One or two major issues cap the verdict at REVISE. Three or more major issues force REJECT. Enforced by tools/validate_critique.py, not by this schema."
          },
          "note": { "type": "string", "minLength": 1 },
          "fix_type": {
            "type": "string",
            "enum": ["prompt-level", "post-level", "re-roll"]
          },
          "fix": { "type": "string", "minLength": 1 }
        }
      }
    }
  },
  "allOf": [
    {
      "if": {
        "properties": { "version": { "const": "1.1" } },
        "required": ["version"]
      },
      "then": {
        "required": [
          "version",
          "run_id",
          "round",
          "created_at",
          "shot_id",
          "brand_lock_ref",
          "brand_lock_sha256",
          "image_ref",
          "image_sha256",
          "prompt_ref",
          "prompt_sha256",
          "generator",
          "model_version",
          "seed",
          "verdict",
          "confidence",
          "issues"
        ]
      }
    }
  ]
}