// Analyzes and validates comprehensive SCC specification coverage, ensuring all rules, formats, and best practices are documented with automated verification.
| name | analyze-scc-docs |
| description | Analyzes and validates comprehensive SCC specification coverage, ensuring all rules, formats, and best practices are documented with automated verification. |
Generates unified, code-verifiable SCC specification (scc_specs_summary.md) as single source of truth for compliance checking.
Outputs:
Key: Ensures NO requirements missed (parity, frame rates, character limits, protocol sequences, etc.)
.claude/skills/gotchas.mdREQUIRED before generating any spec content. Pay special attention to gotchas #1 (no proprietary data tables), #2 (no proprietary source attributions), and #9 (gitignore covers all formats).
Post-run: If you discover a new gotcha during spec generation (a copyright/licensing trap, a source attribution pattern that should be avoided, a web source that returns misleading data, or a spec structure issue that could cause downstream compliance check failures), append it to .claude/skills/gotchas.md with the same numbered format.
Always read:
ai_artifacts/specs/scc/scc_specs_summary.md (existing rule framework)ai_artifacts/specs/scc/scc_web_summary.md (web docs)ai_artifacts/specs/scc/scc_web_sources.md (checked URLs)Check for local standards file (NOT in the repo — user provides separately):
ai_artifacts/specs/scc/standards_summary.md exists locallyThis file is not committed to the repo because it contains proprietary CEA-608 standard text. Contributors who have a licensed copy can place it at the path above to get more comprehensive analysis.
CRITICAL: Verify ALL these areas covered (check scc_specs_summary.md + standards_summary.md if available, otherwise web sources):
File Format:
Byte Encoding (IMPORTANT - was missed):
Control Codes:
Caption Modes:
Layout Limits (IMPORTANT - was missed):
Timing:
Validation:
Identify gaps - anything missing from above.
Determine search scope based on available sources:
If ai_artifacts/specs/scc/standards_summary.md was found in Step 1:
scc_web_sources.md to cross-reference and confirmscc_web_sources.md from new searchesIf ai_artifacts/specs/scc/standards_summary.md was NOT found:
scc_web_sources.md and extract relevant informationscc_web_sources.md from new searchesCreate ai_artifacts/specs/scc/scc_specs_summary.md with:
Structure:
# SCC Specification - Complete Reference
## Part 1: File Format (RULE-FMT-###)
Header, timecode, hex encoding
## Part 2: Byte Encoding (RULE-ENC-###)
Parity (mark N/A for SCC), bit 7, structure
## Part 3: Control Codes (CTRL-###)
All 300+ with hex values, tables
## Part 4: Caption Modes (RULE-MODE-###)
Pop-on, roll-up, paint-on protocols, base row validation
## Part 5: Character Sets (RULE-CHAR-###)
Basic, special, extended, destructive behavior
## Part 6: Timing & Frames (RULE-TIME-###)
All frame rates, limits, monotonic requirement, drop-frame
## Part 7: Layout (RULE-LAY-###)
32 chars/row, 15 rows, positioning
## Part 8: Protocols (RULE-PROTO-###)
Mode sequences, state transitions
## Part 9: Implementation Requirements (IMPL-###)
Generic requirements mapping to code
## Part 10: Validation Summary
Rules count, self-validation report
## Appendices
Quick reference, sources
Rule Format:
**[RULE-XXX-###]** Brief requirement
- **Requirement:** What must be true
- **Level:** MUST | SHOULD | MAY | MUST NOT
- **Validation:** How to check
- **Test Pattern:** Regex or algorithm
- **Sources:** [Attribution]
Implementation Rule Format (GENERIC - no pycaption references):
**[IMPL-XXX-###]** Component MUST do X
- **Spec Rule:** RULE-XXX-###
- **Component:** Parser | Writer | Validator
- **Implementation Requirement:** What ANY compliant implementation must do
- **Expected Behavior:** Input → Output examples
- **Validation Criteria:** What to verify
- **Common Patterns:** Correct vs incorrect (generic)
- **Test Coverage:** Required test scenarios
Critical Requirements to Include:
Parity (CEA-608 requirement):
**[RULE-ENC-001]** Bytes MUST have odd parity
- **Applicability:** N/A for SCC text format (parity pre-encoded in hex)
- **Note:** Relevant for raw transmission, not SCC files
**[IMPL-ENC-001]** Parser MAY skip parity for SCC
- Parity already encoded in hex values
Character/Row Limits (CEA-608 requirement):
**[RULE-LAY-001]** MUST NOT exceed 32 characters per row
**[RULE-LAY-002]** MUST NOT exceed 15 rows total
**[RULE-MODE-001]** Roll-up MUST have valid base row (≥ roll-up depth)
Frame Rates:
**[RULE-TIME-001]** Frame numbers MUST be valid for rate
- 23.976 fps: 0-23
- 24 fps: 0-23
- 25 fps: 0-24
- 29.97 fps DF/NDF: 0-29
- 30 fps: 0-29
Protocols:
**[RULE-PROTO-001]** Pop-on: RCL → text → EOC
**[RULE-PROTO-002]** Roll-up: RU2/3/4 → text → CR
**[RULE-PROTO-003]** Paint-on: RDC → text
Structure checks:
Content checks:
Generate validation report:
## Validation Report
- Total RULE-###: X
- Total IMPL-###: Y
- Total CTRL-###: 300+
- Parity documented: ✅
- Frame rates documented: ✅
- Character limits documented: ✅
- Status: ✅ PASS | ❌ FAIL
If FAIL, fix and re-validate.
Track sources for each rule:
Document conflicts and resolutions.
Append new URLs to ai_artifacts/specs/scc/scc_web_sources.md.
CRITICAL: After generating the spec, run this validation script. If it reports FAIL, fix the spec and re-run until PASS.
import re
print("=" * 60)
print("POST-GENERATION VALIDATION: SCC")
print("Checking scc_specs_summary.md against master_checklist.md")
print("=" * 60)
with open('ai_artifacts/specs/scc/master_checklist.md') as _f: checklist = _f.read()
with open('ai_artifacts/specs/scc/scc_specs_summary.md') as _f: spec = _f.read()
failures = []
warnings = []
# 1. Check all required rule IDs
rule_ids = re.findall(r'^- ((?:RULE|IMPL)-[A-Z]+-\d{3})', checklist, re.M)
for rid in rule_ids:
if rid not in spec:
failures.append(f"MISSING RULE: {rid}")
print(f"[1/5] Rule IDs: {len(rule_ids) - len([f for f in failures if 'RULE' in f])}/{len(rule_ids)}")
# 2. Check required control code hex values
hex_codes = re.findall(r'^- ([0-9a-f]{4})\s+#', checklist, re.M)
for code in hex_codes:
if code not in spec.lower():
failures.append(f"MISSING CONTROL CODE: {code}")
print(f"[2/5] Control codes: {len(hex_codes) - len([f for f in failures if 'CONTROL' in f])}/{len(hex_codes)}")
# 3. Check required enum values
enum_sections = re.findall(r'### (.+?)\n((?:- .+\n)+)', checklist)
for section_name, values_block in enum_sections:
values = re.findall(r'^- (.+)$', values_block, re.M)
for val in values:
val_clean = val.strip()
if val_clean not in spec:
# Try case-insensitive for colors/modes
if not re.search(re.escape(val_clean), spec, re.I):
warnings.append(f"MISSING ENUM [{section_name}]: {val_clean}")
print(f"[3/5] Enum values: checked {sum(len(re.findall(r'^- .+$', vb, re.M)) for _, vb in enum_sections)} values")
# 4. Check severity distribution
severity_section = re.search(r'## Required Severity Distribution\n((?:.*\n)*)', checklist)
if severity_section:
for match in re.finditer(r'- (MUST|SHOULD|MAY|MUST NOT): (\d+)', severity_section.group(1)):
level, minimum = match.group(1), int(match.group(2))
actual = len(re.findall(rf'Level:\*\*\s*{re.escape(level)}\b', spec))
if actual < minimum:
failures.append(f"SEVERITY {level}: found {actual}, need >= {minimum}")
print(f"[4/5] {level}: {actual} (min {minimum}) {'PASS' if actual >= minimum else 'FAIL'}")
# 5. Check control code category coverage
for category in ['PAC', 'Mid-row', 'Special character', 'Extended character', 'XDS']:
if not re.search(category.replace('-', '.'), spec, re.I):
warnings.append(f"MISSING CATEGORY: {category}")
print(f"[5/5] Control code categories checked")
# Report
print("\n" + "=" * 60)
if failures:
print(f"FAIL: {len(failures)} failures, {len(warnings)} warnings\n")
for f in failures:
print(f" FAIL: {f}")
for w in warnings:
print(f" WARN: {w}")
print("\nFix the spec and re-run this validation.")
else:
print(f"PASS: All checks passed ({len(warnings)} warnings)")
for w in warnings:
print(f" WARN: {w}")
print("=" * 60)
If FAIL: Fix the missing items in the spec, then re-run the validation script. Repeat until PASS.
ai_artifacts/specs/scc/scc_specs_summary.md - Complete specificationai_artifacts/specs/scc/scc_web_sources.md - Updated URL listMaster Checklist Validation (CRITICAL - must PASS):
master_checklist.md present in generated specCompleteness:
Quality:
Usability:
Generic Implementation Rules:
Missed Requirements Prevention:
Thoroughness:
Generates EXHAUSTIVE DFXP/TTML specification summary from web sources with complete rule coverage, all elements/attributes/styling, and self-validation.
Generates EXHAUSTIVE WebVTT specification summary from web sources with complete rule coverage, all tags/settings/entities, and self-validation.
Generates EXHAUSTIVE DFXP/TTML compliance report checking all 115 rules individually + styling/timing/element coverage with deep validation analysis to identify ALL issues in pycaption code.
Comprehensive PR analysis for merge decisions - compliance, code review, regressions, and test coverage
Generates EXHAUSTIVE compliance report checking all 44 SCC rules (34 RULE + 10 IMPL) individually + 704 control codes with 12 deep validations (cross-mode EDM, zero-value truthiness, silent error suppression, read-only styling, position fallback) to identify ALL issues in pycaption code.
Generates EXHAUSTIVE WebVTT compliance report checking all 76 rules individually + tag/setting/entity coverage with deep validation analysis to identify ALL issues in pycaption code.