lighting-quality-checker

name	lighting-quality-checker
description	Validate lighting intensity ranges, shadow softness, color temperature, and HDRI use against the scene brief before render.

lighting-quality-checker

Purpose

Run a focused pass/warn/fail check on the scene's lighting setup against intensity sanity, shadow plausibility, color temperature, and HDRI / explicit-light balance — without expanding into material or composition concerns.

Quick start

• enumerate every light and HDRI in the scene plan or measured scene
• check intensity (watts / lumens, sun strength, area light power)
• check shadow softness consistency
• check color temperature consistency
• check HDRI presence + balance with explicit lights
• emit per-light verdicts + a top-line status

When to use

• before render
• after a lighting change request
• as a sub-check during full quality review
• when the rendered preview looks "off" but the issue is unclear

When not to use

• material validation (use material-quality-checker)
• composition / camera validation (use composition-quality-checker)
• broad pass/warn/fail readiness (use blender-scene-quality-checker)
• to fix lights (this skill validates, it does not edit)

Trigger phrases

• "is the lighting okay"
• "check shadow softness"
• "lighting feels off"
• "is the HDRI balanced"

Prerequisites / readiness

• light list known (from scene plan or measured scene)
• consumer target known (Cycles render / Eevee preview / GLB → web)
• mood / look brief known (from intent-to-3d-brief-writer)

Input schema

Required inputs

Input	Why it is required
Light list (type, position, strength, color, soft size)	Scope of the check
Mood / look brief	Determines whether the lighting matches intent
Consumer target	Cycles vs Eevee vs glTF affects allowed light types

Optional inputs

Input	Use
HDRI file path or name	Identifies environment lighting
Reference image	Allows intensity / mood cross-check

Assumptions to confirm

• Intensity units (Watts / Lumens / Sun strength) are consistent across the scene.
• Color temperature is in Kelvin where applicable; mixed Kelvin and RGB color modes need explicit annotation.
• HDRI is real-world calibrated (typical 0.5–2.0 strength), not arbitrarily boosted.

Output schema

Primary output

A per-light verdict table: name, type (sun / area / point / spot / HDRI), intensity, color (Kelvin or RGB), soft size or angle, verdict (Pass / Warn / Fail), notes.

Secondary output

• top-line status (Pass / Warn / Fail) computed from rows
• mood / look match: Yes / No / Unknown
• worst-offender highlighting

Evidence / caveat output

Runtime status: Not Run | Attempted | Produced | Verified | Failed | Blocked / Not Run
Artifact status: Not Run | 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 plans or measured scene snapshots only. It never modifies lights, runs Blender, or renders. Use measured scene description (plan output, runtime tool snapshot) — never invent values.

For runtime path attribution, see ../../docs/runtime-stack-strategy.md.

Operating procedure

1. Read the light list from scene plan or measured scene.
2. For each light, evaluate intensity range (see references/intensity-ranges.md).
3. Evaluate shadow softness consistency (see references/shadow-softness-rules.md).
4. Evaluate color temperature consistency.
5. Evaluate HDRI strength + explicit-light balance (see references/hdri-balance-rules.md).
6. Cross-check with mood brief.
7. Assign per-light verdict; collect notes.
8. Compute top-line status; highlight worst offenders.
9. Hand off to blender-scene-quality-checker (broader review) or back to blender-lighting-material-planner (re-plan).

Decision tree

Scene has only HDRI, no explicit light?
  → Warn for product hero (HDRI alone often lacks key-light snap)
HDRI strength > 2.0?
  → Warn (likely overpowering); verify intent
Sun + 3 explicit area lights all at max strength?
  → Warn (likely too bright; check exposure)
Shadows hard but mood is "soft"?
  → Fail (mismatch with brief)
Mixed Kelvin + RGB color modes without annotation?
  → Warn
Light type unsupported for chosen export (e.g. some volumetrics in glTF)?
  → Fail

Playbooks

Playbook A: Product hero with HDRI + 3-point lighting

HDRI ~0.7–1.2; key area light ~50–500W; fill ~10–20% of key; rim for separation. Verdicts per light + balance check.

Playbook B: Cinematic moody scene

Single key + practical lights; HDRI ~0.2 (mostly ambient fill); shadows hard or soft per brief; verify mood match.

Playbook C: Outdoor sunlight

Sun strength ~1–5; HDRI environment map for ambient; verify shadow direction matches sun direction; verify color temperature (~5500–6500K daylight).

Mode handling

Text-only mode

Verdicts based on plan / spec only; mark Artifact status: Not Run.

Runtime-ready mode

Verdicts based on measured scene snapshot; cite tool used. Never upgrade to Verified without recorded measurement + reference image diff if possible.

Blocked runtime mode

Skip rows that depend on measurement; mark explicitly.

Validation checklist

• Every light listed
• Intensity column filled
• Color column filled (Kelvin or RGB)
• Shadow softness column filled
• HDRI presence noted (or "none")
• Per-light verdict assigned
• Mood match assessed
• Top-line status derived from rows
• Honest evidence label

Pass / Warn / Fail rubric

Verdict	Criteria
Pass	All lights pass intensity / shadow / color sanity; HDRI balanced; mood match Yes.
Warn	Plausibility flags (HDRI alone, mixed color modes, intensity at edges of range) but no hard violations.
Fail	Mood mismatch (e.g. soft brief but hard shadows); unsupported light type for chosen export; intensity clearly off (factor of 10+); shadow direction inconsistent.

Failure handling

• Missing light data → Fail with note.
• Mood unclear → mark Mood match Unknown; do not Pass.
• User pushes for "Pass" without checks → restate requirement.

Troubleshooting

Problem	Response
Render too dark	Check sun + HDRI strength; check exposure; verify camera ISO / aperture.
Render too bright	Check sum of all light intensities; check HDRI strength; check denoiser clamping.
Shadows missing	Check shadow flag per light; check fill light ratio (not 100% of key).
Color cast unintended	Check HDRI tint; check Kelvin vs RGB mismatch on key.

Best practices

• Pair every Fail with the rule that triggered it.
• Cross-check intensity sums against the scene's overall exposure target.
• Always evaluate HDRI + explicit lights as a system, not separately.
• Keep this skill narrow — do not creep into material or composition.

Good examples

• "HDRI: studio.exr @ 1.0; Key area light 250W (5500K, 0.4m soft); Fill area 50W (5500K, 0.6m soft); Rim spot 100W (4500K, hard). Mood: soft hero. Verdict: Pass."

Bad examples

• "Lighting looks fine." — no per-light rows.
• "Verified" without reference image diff.

User-facing response template

Consumer target: <Cycles / Eevee / glTF>
Mood / look: <one-line summary>

| Light | Type | Intensity | Color | Soft / angle | Verdict | Notes |
|---|---|---|---|---|---|---|

HDRI: <name + strength or "none">
Mood match: Yes / No / Unknown
Top-line: <Pass / Warn / Fail>
Worst offenders: <list>
Limitations: <gaps>
Next: blender-scene-quality-checker / blender-lighting-material-planner

Anti-patterns

• Editing lights inside this skill.
• Inventing intensity values.
• Marking Verified without measurement.
• Mixing material / composition checks here.

Cross-skill handoff

• Broad readiness review → ../blender-scene-quality-checker/SKILL.md
• Material validation → ../material-quality-checker/SKILL.md
• Composition validation → ../composition-quality-checker/SKILL.md
• Lighting re-plan → ../blender-lighting-material-planner/SKILL.md
• Render evidence → ../render-export-evidence/SKILL.md

Non-goals

• Edit lights.
• Generate light setup recipes.
• Replace blender-scene-quality-checker.
• Run Blender.

References

• references/intensity-ranges.md
• references/shadow-softness-rules.md
• references/hdri-balance-rules.md
• ../../laws/evidence-before-done.md
• ../../docs/skill-system.md