composition-quality-checker

Purpose

Run a focused per-row Pass/Warn/Fail check on the camera and framing setup against composition rules (rule of thirds, subject placement, headroom/lead-room, negative space, visual hierarchy, depth cues, and lens/FOV plausibility) — emitting per-row verdicts, a top-line status, and remediation hints only, without expanding into camera planning, aspect-ratio locking, material validation, or lighting validation.

Quick start

• read camera lens / FOV, position, and target description
• read framing intent and locked aspect ratio from the brief
• check rule of thirds, subject placement, and headroom/lead-room
• check negative space, visual hierarchy, depth cues, and lens/FOV plausibility
• emit per-row Pass/Warn/Fail verdicts, top-line status, and remediation hints (keep truth states separate and downgrade-only)

When to use

• before render
• after a camera change request
• as a sub-check during full quality review
• when a render "feels off" but lighting and materials check out

When not to use

• planning or editing camera framing → use ../camera-composition/SKILL.md (use camera-composition)
• locking aspect ratio or resolution → use ../resolution-aspect-decision/SKILL.md (use resolution-aspect-decision)
• material validation → use ../material-quality-checker/SKILL.md (use material-quality-checker)
• lighting validation → use ../lighting-quality-checker/SKILL.md (use lighting-quality-checker)
• broad scene Pass/Warn/Fail readiness review → use ../scene-readiness/SKILL.md (use scene-readiness)
• classifying render or export artifact evidence → use ../render-export-evidence/SKILL.md (use render-export-evidence)

Trigger phrases

• "is the framing okay"
• "check composition"
• "subject feels off-center"
• "too much negative space"

Prerequisites / readiness

• camera setup known (FOV / focal length / position / target / lens)
• framing intent known (from brief)
• subject identified

Input schema

Required inputs

Optional inputs

Assumptions to confirm

• Render aspect ratio is known and stable.
• "Subject" is unambiguous in the brief.
• Camera is locked (or animated path is documented).

Output schema

Primary output

A composition verdict table covering: rule of thirds, subject placement, headroom/lead-room, negative space, visual hierarchy, depth cues, and lens/FOV plausibility — each with a Pass | Warn | Fail verdict and notes.

Secondary output

• top-line validation status (Pass | Warn | Fail)
• worst-offender highlighting
• remediation hints only (never camera edits or execution commands)

Evidence / caveat output

Validation verdicts (Pass | Warn | Fail) are separate from runtime and artifact truth states. Truth states are downgrade-only (never upgrade), and Artifact status defaults to Not Produced unless concrete output evidence exists (classified via render-export-evidence).

Runtime status: Not Run | Attempted | Produced | Verified | Failed
Artifact status: Not Produced | Produced | Verified | Failed
Evidence used: <links, paths, logs, or "none">
Limitations: <known gaps>

Required laws

• ../../laws/evidence-before-done.md
• ../../laws/non-blender-user-language.md
• ../../laws/no-arbitrary-python-interface.md
• ../../laws/official-runtime-only.md

Official runtime boundary

This skill validates camera plans or measured scene snapshots only. It never moves the camera, never runs Blender, and never executes Python. Artifacts stay Not Produced unless concrete output evidence exists (classified by render-export-evidence), and truth states are strictly downgrade-only.

Operating procedure

1. Read camera setup, framing intent, subject identification, and upstream aspect lock (from resolution-aspect-decision).
2. Check rule of thirds alignment against framing intent.
3. Check subject placement per intent.
4. Check headroom and lead-room balance.
5. Check negative space balance and visual hierarchy.
6. Check depth cues (foreground/midground/background separation).
7. Check lens / FOV plausibility for distortion or flattening against the brief.
8. Assign per-row Pass | Warn | Fail verdicts and remediation hints.
9. Compute top-line status and highlight worst offenders; record downgrade-only Runtime and Artifact truth states separately (defaulting Artifact status to Not Produced).
10. Hand off to scene-readiness (broad review), camera-composition (camera re-plan), resolution-aspect-decision (aspect/resolution changes), or render-export-evidence (artifact evidence classification).

Decision tree

Subject dead-center in 16:9 hero card?
  → Pass for symmetric hero; Warn for documentary/editorial mood
Subject in dead corner?
  → Fail unless intentional asymmetry called out in brief
Headroom > 30% of frame for portrait?
  → Warn (too much empty space above)
Headroom 0% (subject's head touching top)?
  → Fail
Lead room missing for moving subject?
  → Fail (subject "pressed against" frame)
Negative space carrying intentional weight?
  → Pass; verify with brief
FOV < 18mm equivalent on a hero close-up?
  → Warn (likely distortion); verify intent

Playbooks

Playbook A: Product hero card 16:9

Subject ~60% width, centered horizontally or on right third; clear negative space on the opposite side for headline / CTA; soft horizon line; FOV 50–85mm equivalent.

Playbook B: Square 1:1 social

Subject centered; negative space minimal; tight crop OK if not cropping silhouette.

Playbook C: Portrait 9:16 mobile

Subject in upper third; lower third reserved for text overlay; full silhouette visible.

Playbook D: Cinematic 2.39:1

Wide negative space allowed; subject often off-center using rule of thirds; horizon at upper or lower third.

Mode handling

Text-only mode

Per-row Pass | Warn | Fail verdicts are based on the written camera plan/brief only. Runtime status stays Not Run and Artifact status stays Not Produced.

Runtime-ready mode

Per-row verdicts cross-check the measured scene snapshot or preview. Truth states remain separate from row verdicts, are downgrade-only, and require render-export-evidence before any artifact state above Not Produced is recorded.

Blocked runtime mode

Skip preview-dependent verification, flag limitations explicitly, keep Artifact status: Not Produced, and downgrade truth states accordingly.

Validation checklist

• Camera setup stated
• Framing intent stated
• Aspect ratio lock confirmed (from resolution-aspect-decision)
• Rule of thirds verdict
• Subject placement verdict
• Headroom / lead-room verdict
• Negative space verdict
• Visual hierarchy verdict
• Depth cues verdict
• Lens / FOV plausibility verdict
• Top-line status derived from rows (kept separate from Runtime/Artifact truth states)

Pass / Warn / Fail rubric

Failure handling

• Camera path animated → flag every keyframe individually if possible, or mark as Warn for static-rule scope.
• "Negative space minimal" intent vs measured negative space wide → Fail, not Warn.
• Aspect ratio missing → Fail until provided.

Troubleshooting

Best practices

• Confirm the upstream aspect-ratio lock from resolution-aspect-decision before judging framing margins.
• Apply composition checks relative to framing intent, not as rigid universal formulas.
• Treat negative space and depth cues as intentional design elements anchored to the brief.
• Provide remediation hints only — leave camera edits to camera-composition and broad scene sign-off to scene-readiness.

Good examples

• "16:9 hero card; subject right-third 60% width; headroom 18%; lead room not applicable (static); negative space left for CTA; FOV 50mm equivalent. Verdict: Pass."

Bad examples

• "Composition looks fine." — no per-row analysis.
• "Verified" without preview cross-check.

User-facing response template

Aspect ratio lock: <from resolution-aspect-decision>
Framing intent: <hero card / portrait / wide / cinematic>

| Check | Verdict | Notes / Remediation Hint |
|---|---|---|
| Rule of thirds | Pass/Warn/Fail | |
| Subject placement | Pass/Warn/Fail | |
| Headroom / lead-room | Pass/Warn/Fail | |
| Negative space | Pass/Warn/Fail | |
| Visual hierarchy | Pass/Warn/Fail | |
| Depth cues | Pass/Warn/Fail | |
| Lens / FOV plausibility | Pass/Warn/Fail | |

Top-line verdict: <Pass / Warn / Fail>
Worst offenders: <list or "none">
Remediation hints: <hints only — no camera edits>

Runtime status: Not Run | Attempted | Produced | Verified | Failed
Artifact status: Not Produced | Produced | Verified | Failed (default: Not Produced)
Evidence used: <links, paths, logs, or "none">
Limitations: <gaps>
Next: scene-readiness | camera-composition | resolution-aspect-decision | render-export-evidence

Anti-patterns

• Editing the camera inside this skill.
• Inventing values.
• Marking Verified without preview.
• Mixing material / lighting checks here.

Cross-skill handoff

• [progression] Broad scene readiness review (consumes these rows) → ../scene-readiness/SKILL.md
• [retry] Camera & framing re-plan → ../camera-composition/SKILL.md
• [retry] Aspect ratio & resolution locks → ../resolution-aspect-decision/SKILL.md
• [progression] Artifact evidence classification → ../render-export-evidence/SKILL.md
• [upstream_reference] Material validation → ../material-quality-checker/SKILL.md
• [upstream_reference] Lighting validation → ../lighting-quality-checker/SKILL.md

Non-goals

• Move or edit the camera (owned by camera-composition).
• Lock aspect ratio or resolution (owned by resolution-aspect-decision).
• Validate materials (material-quality-checker) or lighting (lighting-quality-checker).
• Replace broad scene review (scene-readiness).
• Classify render or export artifact evidence (render-export-evidence).
• Run Blender or execute Python.

References

• references/composition-rules.md
• references/headroom-leadroom-rules.md
• references/aspect-ratio-rules.md
• ../../laws/evidence-before-done.md
• ../../docs/skill-system.md