scenario-quality-gate — Claude Code skill: image quality checks

---
name: scenario-quality-gate
description: "Use when a generated Scenario image needs a quality check or a brand-brief compliance verdict before it ships: pass/warn/fail scoring, on-brand review against a configured brief, QA gating a batch, pricing or refreshing a stored verdict, or iterating a generation until it clears the gate. Keywords: quality gate, quality check, QA, verdict, brief compliance, on-brand, brand brief, pass fail, score, review, asset_quality_gate_run."
license: MIT
---

# Scenario Quality Gate

## Overview

One tool, `asset_quality_gate_run`, scores a finished image asset and returns a `pass`/`warn`/`fail`
verdict with 0 to 100 scores and per-dimension lists of `reasons` and `suggestions`: an AI-quality
check always, plus brand-brief compliance when the team or project has a brief configured. Image
assets only. Quality Gate is an Enterprise add-on: when it is not enabled for the team the call
fails cleanly, so detect that, fall back to an `asset_analyze` review (see
`scenario-asset-analysis`), and say so. Retrying never clears it.

The tool is catalog-only and write-class: get the schema with `scenario_tools_search`, then run it
through `scenario_tool_execute_write` with `{name: "asset_quality_gate_run", parameters: {...}}`,
scope ids inside `parameters` (the read executor rejects it by lane and names the right one). Or
reconnect with `?toolsets=full`. Connection and scope: see the `scenario` skill. If a sibling skill
named here is missing from your available skills, ask the user to install it
(`npx skills add scenario-labs/skills --skill <name>`); unattended, proceed from tool schemas and
flag the gap.

## Quick reference: what a call costs

| Call                              | What happens                                                             | Cost                                                                       |
| --------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| Plain call, usable verdict stored | Returns the stored verdict, `source: "stored"`                           | Free (the response carries no `creativeUnitsCost`)                         |
| Plain call, no usable verdict     | Runs a new analysis and stores the verdict, `source: "new_analysis"`     | Billed; the response carries `creativeUnitsCost` (1 CU as of this writing) |
| `rerun: true`                     | New analysis that replaces the stored verdict                            | Billed                                                                     |
| `dry_run: true`                   | Nothing runs; returns the price of a new analysis as `creativeUnitsCost` | Free                                                                       |

A plain call is a read only when a usable verdict already exists; otherwise the same call silently
escalates to the billed analysis. "No usable verdict" covers both never-scored and a stored `error`
result. When spend needs approval first, probe free: `dry_run: true`, or `asset_get`, whose
`qualityGate` field carries the verdict and scores when one is stored (summary only; the stored
`reasons` and `suggestions` come back through the tool, still free). `sensitivity` (`low`, `medium`,
`high`; default is the team or project setting) shapes new analyses only and is ignored on stored
reads. `rerun: true` is for after the brief or the sensitivity changed, nothing else: it re-bills
and overwrites.

## Reading the verdict

The response is `source` plus `quality_gate`: `verdict`, `overallScore`, `aiQualityScore`,
`briefComplianceScore`, `sensitivity`, `appliedBriefIds`, and `details`. With no brief configured
the compliance dimension is absent entirely (`appliedBriefIds: []`, `overallScore` equals
`aiQualityScore`); with one, `details.briefCompliance` sits beside `details.aiQuality`, each
carrying a `score` and lists of `reasons` and `suggestions`, usually several of each.

## Turning the verdict into a better image

A verdict alone only sorts assets. The gate earns its cost when the feedback drives the next
attempt:

- `reasons` name concrete flaws ("elongated finger anatomy on the left hand", "background gradient
  off the brief's palette"). Use them to pick the fix path per flaw: a local defect on an otherwise
  approved image is a masked inpainting pass (`scenario-image`); a global one is a regeneration.
- `suggestions` are written as edit instructions, often worded for manual retouching. Apply all that
  fit, not just the first: translate them into the next `model_run` prompt or parameters, or into
  the edit instruction.
- A regenerated image is a new asset, so a plain call scores it. `rerun` is never part of the loop.
  It may even come back pre-scored for free: teams with auto-detect enabled
  (`qualityGateAutoDetect: true` on their `teams_list` row) score new generations automatically.
- When a round repeats the same flaw classes at an unmoved score, rewording will not fix them:
  switch models (`recommend` again) or repair the flaw with a masked edit before spending another
  round.
- Fix the exit bar and a round cap up front: `verdict: "pass"` by default, or a score target the
  user names (`overallScore` at or above 90, say; the named bar then outranks a bare `pass`), and
  three rounds unless told otherwise, since every round bills a generation plus an analysis. At the
  cap, or when a round stops moving the scores, stop: report the best asset with its remaining flaws
  and ask before spending more rounds; unattended, deliver that best asset and flag the miss.

`scenario-refine-loop` carries the loop discipline beyond the gate: one variable per round,
regeneration from the approved baseline, and fix routing when the criteria go past the brief.

## What the verdict does not cover

The gate is an artifact detector. Measured on real assets, three limits to design around:

- **Artifacts, not plausibility.** A panel whose car carried two different wheels, a whitewall on
  one only, and no wheel arch above the rear tire scored 92 and `pass` at `sensitivity: "high"`,
  with `reasons` praising the chrome rims that were the defect. What is impossible rather than ugly
  needs a structural check of your own: counts and attachment (hands, fingers per hand, limbs,
  wheels, each attached to one body), part to whole (a wheel sits inside an arch, a guard sits on
  its own blade, a reflection sits under what casts it), and what carries the weight.
- **It has never seen your reference.** `briefCompliance` needs a configured brief, and a brief is
  text, so no call can tell you this is not the same car or costume as the plate it was generated
  from. Compare the asset against its reference yourself, item by item.
- **A composite averages its parts.** A 12-panel storyboard scored 88 and `pass` while one of its
  panels was physically impossible. Score the unit you are willing to reject: split a composite with
  `model_scenario-image-slicer`, score each part, repair only the failures, and recompose with
  `model_scenario-compose-image`.

The score is also a weak signal that a structural repair landed: a broken panel and its corrected
replacement both scored 92, and only the `reasons` changed. Re-read the flaw list, do not watch the
number.

## Worked example: iterate a hero prop to pass

1. Generate per `scenario-image`: `model_run`, `jobs_wait`, collect the asset id.
2. `scenario_tools_search` with `query="quality gate"` once for the schema, then `dry_run: true` on
   the first asset to surface the per-analysis price.
3. Score: `scenario_tool_execute_write` with
   `{name: "asset_quality_gate_run", parameters: {asset_id, team_id, project_id}}`. It returns
   `source: "new_analysis"` and a `quality_gate` carrying `verdict: "warn"`,
   `briefComplianceScore: 58`, and `details.briefCompliance.suggestions` asking for the logo at the
   top left and a flatter background.
4. Fold both suggestions into the prompt, regenerate, and score the new asset with a plain call (no
   `rerun`).
5. `verdict: "pass"`: deliver, and file it (collections and tags per `scenario-asset-analysis`).
   Later reads of any scored asset are free stored reads.
6. The brief changes next sprint: only then `rerun: true` on the assets that must be re-judged.

## Common mistakes

- Treating a plain call as a free read: without a usable stored verdict it silently runs and bills
  the analysis. Probe with `dry_run` or `asset_get` first when the spend matters.
- Passing `rerun: true` out of habit: it re-bills verdicts that were free to read. Its one job is
  refreshing after the brief or sensitivity changed.
- Expecting `briefComplianceScore` with no brief configured: `quality_gate` carries it and
  `details.briefCompliance` only when `appliedBriefIds` is non-empty.
- Applying one suggestion and rescoring each time: the lists usually carry several fixes, and one
  regeneration can absorb them all.
- Running it through `scenario_tool_execute_read`: write-class, rejected by lane.
- Scoring a video, 3D, or audio asset: image assets only.
- Assuming a fresh upload has no verdict: uploads deduplicate by content, so identical bytes return
  the same long-lived asset id whatever the filename, and a re-upload of a file the team scored
  before carries its stored verdict.
- Setting `sensitivity` on a call that returns a stored verdict: it applies to new analyses only;
  stricter scoring of an already-scored asset requires `rerun: true`.
- Retrying the entitlement failure: Quality Gate is an Enterprise add-on. Degrade to the
  `asset_analyze` review in `scenario-asset-analysis` and tell the user why.