suggest-scc-fixes

name	suggest-scc-fixes
description	Analyzes the latest SCC compliance report and generates detailed Python code suggestions for fixing the most critical issue.

suggest-scc-fixes

What this skill does

Focused fix generation for SCC compliance issues:

1. Finds latest compliance report in ai_artifacts/compliance_checks/scc/
2. Identifies the MOST CRITICAL issue (highest priority)
3. Generates detailed fix with:
   • Exact Python code to implement
   • File locations and line numbers
   • Test cases for the fix
   • Implementation notes
4. Saves to ai_artifacts/compliance_checks/scc/suggested_scc_fixes.md

Key optimization: Focuses on ONE critical issue at a time to avoid context overflow.

Usage

/suggest-scc-fixes

Automatically finds latest report and generates fix for top priority issue.

---

Pre-flight: Read .claude/skills/gotchas.md

REQUIRED before generating fix suggestions. Pay special attention to gotchas #1 (no proprietary data tables in suggested code) and #2 (no proprietary source attributions).

Post-run: If you discover a new gotcha during fix generation (a regex pattern that silently misses IDs, a code pattern that looks correct but violates the spec, or a compliance report format change that breaks extraction), append it to .claude/skills/gotchas.md with the same numbered format.

---

Context Optimization Strategy

Why focus on one issue:

• Reading full compliance report: ~10K tokens
• Analyzing all issues: ~30K tokens
• Generating fixes for all: ~50K+ tokens
• Total naive approach: 90K+ tokens

Optimized approach:

• Extract issue list only: ~2K tokens
• Focus on #1 critical issue: ~5K tokens
• Generate one detailed fix: ~10K tokens
• Total optimized: ~20K tokens (78% reduction)

To fix multiple issues: Run skill multiple times (one issue per run)

---

Implementation

Run this script

import re
import os
import glob
import subprocess
from datetime import datetime

# ===== Step 1: Find Latest Report =====
reports = glob.glob("ai_artifacts/compliance_checks/scc/compliance_report_*.md")
if not reports:
    print("No compliance report found. Run /check-scc-compliance first.")
    exit(0)

latest_report = max(reports, key=os.path.getmtime)
print(f"Using: {latest_report}")

# ===== Step 2: Read Report and Extract Critical Issue =====
with open(latest_report) as _f:
    report_content = _f.read()

# Extract critical issues section
critical_match = re.search(r'### .*CRITICAL(.*?)(?=\n### |\n## |\Z)', report_content, re.DOTALL)
critical_section = critical_match.group(1) if critical_match else report_content

first_issue_match = re.search(
    r'1\.\s+\*\*\[?(RULE-[A-Z]+-\d{3}|IMPL-(?:[A-Z]+-)?\d{3}|CTRL-\d{3})\]?\*\*[:\s]+(.+?)(?:\n|$)',
    critical_section
)

if not first_issue_match:
    # Try validation gaps section
    val_section = re.search(r'## 1\. Validation Gaps.*?\n(.*?)(?=\n## |\Z)', report_content, re.DOTALL)
    if val_section:
        first_issue_match = re.search(
            r'### (RULE-[A-Z]+-\d{3}|IMPL-(?:[A-Z]+-)?\d{3}):\s+(.+?)(?:\n|$)',
            val_section.group(1)
        )

if not first_issue_match:
    print("No critical issues found in report!")
    print("   All MUST-level requirements are met.")
    exit(0)

issue_id = first_issue_match.group(1)
issue_title = first_issue_match.group(2).strip()

print(f"Focusing on: {issue_id} - {issue_title}")

# ===== Step 3: Extract Full Details for This Issue =====
def extract_field(text, field_name):
    match = re.search(f'\\*\\*{field_name}\\*\\*:?\\s*(.+?)(?=\\n\\*\\*|\\n\\n|$)',
                     text, re.DOTALL)
    return match.group(1).strip() if match else "Not specified"

# Find issue detail block in the report
issue_block_match = re.search(
    rf'###?\s*{re.escape(issue_id)}.*?(?=\n###?\s|\n## |\Z)',
    report_content, re.DOTALL
)
issue_details = issue_block_match.group(0) if issue_block_match else ""

issue_info = {
    'id': issue_id,
    'title': issue_title,
    'severity': extract_field(issue_details, 'Severity'),
    'file': extract_field(issue_details, 'File'),
    'current': extract_field(issue_details, 'Current'),
    'expected': extract_field(issue_details, 'Expected'),
    'impact': extract_field(issue_details, 'Impact'),
    'fix': extract_field(issue_details, 'Fix'),
}

if issue_info['severity'] == 'Not specified':
    # Try Status/Note fields
    status = extract_field(issue_details, 'Status')
    note = extract_field(issue_details, 'Note')
    issue_info['severity'] = 'UNKNOWN'
    if note != 'Not specified':
        issue_info['current'] = note

# ===== Step 4: Read Relevant Source Code =====
file_path = "pycaption/scc/__init__.py"
line_num = None

if issue_info['file'] != 'Not specified':
    file_match = re.match(r'(.+?):(\d+)', issue_info['file'])
    if file_match:
        file_path = file_match.group(1)
        line_num = int(file_match.group(2))

search_terms = [issue_info['id']]
if 'RU4' in issue_info.get('title', '') or '94a7' in str(issue_info):
    search_terms.extend(['94a7', '9427', 'RU4'])
elif 'header' in issue_info.get('title', '').lower():
    search_terms.extend(['Scenarist_SCC', 'def read', 'def detect'])
elif 'parity' in issue_info.get('title', '').lower():
    search_terms.extend(['parity', '& 0x7f'])
else:
    keywords = [w for w in issue_info['title'].split() if len(w) > 3 and w[0].isupper()]
    search_terms.extend(keywords[:3])

scc_files = ['pycaption/scc/__init__.py', 'pycaption/scc/constants.py',
             'pycaption/scc/specialized_collections.py', 'pycaption/scc/state_machines.py']
grep_results = []
for term in search_terms:
    for sf in scc_files:
        try:
            result = subprocess.run(['grep', '-n', term, sf], capture_output=True, text=True)
            if result.stdout.strip():
                for line in result.stdout.strip().split('\n'):
                    grep_results.append(f"{sf}:{line}")
        except Exception:
            pass

if grep_results and line_num is None:
    first_hit = grep_results[0]
    parts = first_hit.split(':')
    if len(parts) >= 2:
        file_path = parts[0]
        try:
            line_num = int(parts[1])
        except ValueError:
            pass

if line_num:
    with open(file_path) as f:
        lines = f.readlines()
    start = max(0, line_num - 10)
    context = ''.join(lines[start:start + 30])
    print(f"Found code at {file_path}:{line_num}")
else:
    with open(file_path) as f:
        context = ''.join(f.readlines()[:50])
    print(f"Reading {file_path} (no line match found)")

print(f"   Grep hits: {len(grep_results)}")


# ===== Helper Functions =====

def extract_spec_reference(spec_content, search_term):
    if not spec_content:
        return search_term
    rule_match = re.search(r'\[(RULE-[A-Z]+-\d{3})\]', spec_content)
    if rule_match:
        rule_id_found = rule_match.group(1)
        cea_match = re.search(r'CEA-608[^,\n]*', spec_content)
        if cea_match:
            return f"{rule_id_found} (per {cea_match.group(0)})"
        return rule_id_found
    return search_term


def generate_code_fix(_issue_info, _context):
    spec_path = "ai_artifacts/specs/scc/scc_specs_summary.md"
    spec_content = None
    try:
        rule_id_local = _issue_info['id']
        result = subprocess.run(['grep', '-A', '15', f'\\[{rule_id_local}\\]', spec_path],
                                capture_output=True, text=True)
        spec_content = result.stdout.strip() if result.stdout.strip() else None
    except Exception:
        spec_content = None

    if 'RU4' in _issue_info['title'] or '94a7' in str(_issue_info):
        spec_ref = extract_spec_reference(spec_content, 'RU4') if spec_content else \
                   "CEA-608 Section 6.4.2 (Roll-Up Captions)"
        return f'''
#### No Change Required

The current RU4 hex code `94a7` in `pycaption/scc/__init__.py` is **correct**.

Per **{spec_ref}**, CEA-608 uses odd-parity encoding. The RU4 (Roll-Up 4 rows)
control code with odd parity is `0x94a7`, not `0x9427`.

**Spec Reference**: See `ai_artifacts/specs/scc/scc_specs_summary.md` -> Search for `[CTRL-RU4]`
or `[RULE-ROLLUP-001]` for complete control code table.
'''

    elif 'header' in _issue_info['title'].lower() or 'RULE-FMT-001' in _issue_info['id']:
        spec_ref = extract_spec_reference(spec_content, 'RULE-FMT-001') if spec_content else \
                   "RULE-FMT-001 and IMPL-FMT-001"
        return f'''
#### Code to Add

```python
# File: pycaption/scc/__init__.py
# Location: At start of SCCReader.read() method

def read(self, content, lang="en-US", simulate_roll_up=False, offset=0):
    lines = content.splitlines()

    # Validate SCC header (RULE-FMT-001)
    if not lines or lines[0].strip() != "Scenarist_SCC V1.0":
        raise CaptionReadNoCaptions(
            "Invalid SCC file: Header must be exactly 'Scenarist_SCC V1.0'"
        )

    # Continue with existing parsing logic...
    self.caption_stash = CaptionStash()

What: Add 4-line header validation at the start of read() method.

Why: This is required by {spec_ref} in the SCC specification.

Spec Reference: See ai_artifacts/specs/scc/scc_specs_summary.md -> Section 1.1 "File Header" -> [RULE-FMT-001] and [IMPL-FMT-001] for complete validation requirements. '''

else:
    rule_id_local = _issue_info['id']
    spec_ref = extract_spec_reference(spec_content, rule_id_local) if spec_content else rule_id_local

    code_locations = ""
    if grep_results:
        code_locations = "\n".join(f"  - `{hit}`" for hit in grep_results[:5])
    else:
        code_locations = f"  - `{_issue_info.get('file', 'pycaption/scc/__init__.py')}` (search for related code)"

    return f'''

Fix Required

Relevant code locations (from grep): {code_locations}

Current behavior: {_issue_info["current"]} Expected behavior: {_issue_info["expected"]}

Approach:

1. Open the file(s) listed above at the indicated lines
2. Identify the code handling this feature
3. Modify to match the expected behavior per {spec_ref}
4. Add validation if the issue is about missing checks

Why: This is required by {spec_ref} in the SCC specification.

• Severity: {_issue_info.get("severity", "UNKNOWN")} (per spec compliance level)
• Impact: {_issue_info.get("impact", "May cause interoperability issues or incorrect caption rendering")}

Spec Reference: See ai_artifacts/specs/scc/scc_specs_summary.md -> Search for [{rule_id_local}] for complete specification details, validation criteria, and test patterns. '''

def generate_test_cases(_issue_info): if 'RU4' in _issue_info['title'] or '94a7' in str(_issue_info): return '''

# File: tests/test_scc.py

def test_ru4_control_code_correct_hex():
    from pycaption.scc import SCCReader

    scc_content = """Scenarist_SCC V1.0

00:00:00:00\t9427 9427 94ad 94ad

"""

    reader = SCCReader()
    caption_set = reader.read(scc_content)
    assert caption_set is not None

'''

elif 'header' in _issue_info['title'].lower():
    return '''

# File: tests/test_scc.py

def test_header_validation_rejects_invalid():
    from pycaption.scc import SCCReader
    from pycaption.exceptions import CaptionReadNoCaptions
    import pytest

    reader = SCCReader()

    invalid_scc = """scenarist_scc v1.0

00:00:00:00\t9420 9420
"""

    with pytest.raises(CaptionReadNoCaptions, match="Invalid SCC file"):
        reader.read(invalid_scc)

    valid_scc = """Scenarist_SCC V1.0

00:00:00:00\t9420 9420
"""

    result = reader.read(valid_scc)
    assert result is not None

'''

else:
    return f'''

# File: tests/test_scc.py

def test_{_issue_info["id"].lower().replace("-", "_")}():
    from pycaption.scc import SCCReader

    scc_content = """Scenarist_SCC V1.0

00:00:00:00\t9420 9420

"""

    reader = SCCReader()
    result = reader.read(scc_content)
    assert result is not None

'''

def generate_implementation_notes(_issue_info): notes = [] rule_id_local = _issue_info['id']

if _issue_info['severity'] == 'MUST':
    notes.append(f"**MUST-level requirement**: This is mandatory per **{rule_id_local}** in the CEA-608/SCC specification.")
elif _issue_info['severity'] == 'SHOULD':
    notes.append(f"**SHOULD-level requirement**: Recommended by **{rule_id_local}** for best practices and compatibility.")

if 'interoperability' in _issue_info.get('impact', '').lower():
    notes.append("**Interoperability impact**: Required for compatibility with industry-standard tools.")

notes.append(f"**Specification reference**:")
notes.append(f"   - Primary: `ai_artifacts/specs/scc/scc_specs_summary.md` -> Search for `[{rule_id_local}]`")

return '\n'.join(f'- {note}' if not note.startswith('   ') else note for note in notes)

def estimate_complexity(_issue_info): if any(word in _issue_info.get('fix', '').lower() for word in ['change', 'character', 'single']): return "Low (simple change)" elif any(word in _issue_info.get('fix', '').lower() for word in ['add', 'line', 'validation']): return "Medium (add code)" else: return "High (complex implementation)"

def estimate_time(_issue_info): fix_text = _issue_info.get('fix', '').lower() if 'character' in fix_text or '30 second' in fix_text: return "< 1 minute" elif 'line' in fix_text or '5 minute' in fix_text: return "5-10 minutes" else: return "15-30 minutes"

===== Step 5: Generate Report =====

fix_content = f"""# SCC Compliance Fix Suggestions

Generated: {datetime.now().strftime("%Y-%m-%d")} Source Report: {latest_report} Focus: Most Critical Issue Only

---

Issue Being Fixed

Issue ID: {issue_info['id']} Title: {issue_info['title']} Severity: {issue_info['severity']} Priority: CRITICAL (Issue #1)

Current State: {issue_info['current']} Required: {issue_info['expected']} Impact: {issue_info['impact']}

Specification Context: This issue violates {issue_info['id']} in the SCC/CEA-608 specification. See ai_artifacts/specs/scc/scc_specs_summary.md for complete specification text.

---

Proposed Fix

Location

File: {file_path} Line: {line_num if line_num else 'N/A'}

Implementation

{generate_code_fix(issue_info, context)}

---

Testing

Test Cases Required

{generate_test_cases(issue_info)}

---

Verification Steps

1. Apply the fix above
2. Run tests: pytest tests/test_scc.py -v
3. Verify against spec:
   • Open ai_artifacts/specs/scc/scc_specs_summary.md
   • Search for [{issue_info['id']}]
   • Confirm fix meets all requirements
4. Test with real SCC file (if applicable)
5. Check interoperability: Verify output works with standard tools

---

Specification Details

Rule: {issue_info['id']} Level: {issue_info['severity']} (mandatory compliance) Location in Spec: ai_artifacts/specs/scc/scc_specs_summary.md

---

Additional Notes

{generate_implementation_notes(issue_info)}

---

Next Steps

After fixing this issue:

1. Mark {issue_info['id']} as resolved
2. Run /suggest-scc-fixes again for next critical issue
3. Re-run /check-scc-compliance to verify fix and get updated report
4. Review full spec section in ai_artifacts/specs/scc/scc_specs_summary.md if needed

---

Generated by: suggest-scc-fixes skill Fix complexity: {estimate_complexity(issue_info)} Estimated time: {estimate_time(issue_info)} Spec-backed: All fixes reference specification requirements """

os.makedirs("ai_artifacts/compliance_checks/scc", exist_ok=True) with open("ai_artifacts/compliance_checks/scc/suggested_scc_fixes.md", 'w') as _f: _f.write(fix_content)

print(f""" Fix suggestion generated!

Issue: {issue_info['id']} - {issue_info['title']} Saved to: ai_artifacts/compliance_checks/scc/suggested_scc_fixes.md

Summary: Severity: {issue_info['severity']} File: {file_path} Complexity: {estimate_complexity(issue_info)} Time: {estimate_time(issue_info)}

Next Steps:

1. Review the suggested fix in the report
2. Apply the code changes
3. Run the test cases
4. Run /suggest-scc-fixes again for next issue """)

---

## Success Criteria

- **Context-efficient** - Uses ~20K tokens (vs 90K+ for all issues)
- **Focused** - One issue at a time with complete fix
- **Actionable** - Exact code, not generic advice
- **Testable** - Includes test cases
- **Iterative** - Run multiple times for multiple issues
- **Fast** - Completes in ~1-2 minutes

---

## Important Notes

**Why one issue at a time:**
- Keeps context window manageable
- Allows detailed, specific fixes
- User can review and apply incrementally
- Can re-run for next issue after first is fixed

**Priority order:**
1. First run: Fix issue #1 (most critical)
2. Second run: Fix issue #2 (next critical)
3. Continue until all critical issues resolved

**Error handling:**
- No report found -> Tell user to run check-scc-compliance
- No issues found -> Celebrate! All compliant
- Can't parse issue -> Use generic template