@demig0d2/skills 1.0.0

package/skills/overhaul/references/upgrade_checklist.md

@@ -0,0 +1,81 @@
+# Overhaul — Upgrade Quality Checklist
+
+Run this checklist before delivering any upgraded skill. Every item must pass.
+
+---
+
+## PRE-DELIVERY CHECKLIST
+
+### Frontmatter
+- [ ] Version number bumped (patch for minor fixes, minor for new sections, major for rebuild)
+- [ ] Description rewritten to reflect upgraded capabilities — not the old skill's description
+- [ ] Description includes at least 3 specific trigger phrases
+- [ ] Description is under 300 characters
+- [ ] Description is "pushy" — errs toward triggering rather than waiting
+
+### Structure
+- [ ] Every distinct behavior has a named `## SECTION` heading
+- [ ] Every multi-step process is numbered (not bulleted)
+- [ ] Every output has a concrete template (not just described)
+- [ ] Every module has a quality gate or verification checkpoint
+- [ ] Every identified conflict has an explicit protection rule BEFORE the general rule
+- [ ] Every missing dimension from Module 4 has a dedicated handler section
+
+### Content
+- [ ] All conflicts identified in Module 2 are resolved
+- [ ] All compressed items from Module 3 are fully expanded
+- [ ] All missing dimensions from Module 4 have handlers
+- [ ] Integration gaps from Module 5 are addressed
+- [ ] Output format is a concrete template
+
+### The Final Test
+- [ ] Would someone who used the original skill feel this is a **different generation** — not just a cleaner version?
+
+If the answer to the final test is NO → go back and find the missing dimension that was overlooked.
+
+---
+
+## VERSION BUMP GUIDE
+
+| Change Type | Version Bump | Example |
+|---|---|---|
+| Typo fix, minor wording | Patch (0.0.X) | 1.0.0 → 1.0.1 |
+| New section, expanded content, edge cases | Minor (0.X.0) | 1.0.0 → 1.1.0 |
+| Generational rebuild, new modules, overhaul | Major (X.0.0) | 1.0.0 → 2.0.0 |
+| No version in original | Assign 2.0.0 | — → 2.0.0 |
+
+---
+
+## UPGRADE SEVERITY GUIDE
+
+| Vectors Found | Severity | Expected Version Bump |
+|---|---|---|
+| 1–2 vectors | Minor upgrade | Minor (0.X.0) |
+| 3–4 vectors | Major upgrade | Major (X.0.0) |
+| 5–6 vectors | Generational | Major (X.0.0) |
+
+---
+
+## THE 6 DIAGNOSTIC MODULES — QUICK REFERENCE
+
+| Module | What It Finds | Why It Matters |
+|---|---|---|
+| 1. Intent Reconstruction | Gap between stated and actual behavior | First upgrade vector |
+| 2. Conflict Detection | Instructions that cancel each other | Silent failures at runtime |
+| 3. Compression Audit | Logic buried too thin in one line | Missing handling |
+| 4. Missing Dimension Scan | Categories not addressed at all | The highest-value module |
+| 5. Integration Analysis | Ecosystem awareness, triggering accuracy | Skills that never fire |
+| 6. Output Standard Check | Format precision, quality definition | Inconsistent output |
+
+---
+
+## COMMON MISSING DIMENSIONS (found repeatedly across skills)
+
+These are frequently missing — check for them in every upgrade:
+
+1. **What happens when input is too thin?** (Most skills have no "seed too vague" handler)
+2. **What happens when a required step is skipped?** (Most pipelines assume linear execution)
+3. **Is there a quality gate before the final output?** (Most skills just output without self-checking)
+4. **Are protected constructions defined?** (Skills that strip content often destroy intentional choices)
+5. **Is the output format a template or just described?** (Described outputs are inconsistent across runs)
+6. **What is the recovery path when a module fails?** (Most skills have no error → retry path)

package/skills/overhaul/scripts/changelog_gen.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+changelog_gen.py — Generate a changelog by diffing two SKILL.md versions
+
+Compares old and new skill files. Detects added sections, removed sections,
+expanded content, and version changes.
+
+Usage:
+    python changelog_gen.py <old_SKILL.md> <new_SKILL.md>
+    python changelog_gen.py <old_SKILL.md> <new_SKILL.md> --json
+    python changelog_gen.py <old_SKILL.md> <new_SKILL.md> --markdown
+"""
+
+import sys
+import re
+import json
+from pathlib import Path
+
+
+def extract_sections(text: str) -> dict:
+    """Return dict of {section_title: content}."""
+    sections = {}
+    current_title = "__preamble__"
+    current_lines = []
+
+    for line in text.splitlines():
+        heading = re.match(r"^(#{1,3})\s+(.+)", line)
+        if heading:
+            sections[current_title] = "\n".join(current_lines).strip()
+            current_title = heading.group(2).strip()
+            current_lines = []
+        else:
+            current_lines.append(line)
+
+    sections[current_title] = "\n".join(current_lines).strip()
+    return sections
+
+
+def get_version(text: str) -> str:
+    match = re.search(r"^version:\s*(.+)$", text, re.MULTILINE)
+    return match.group(1).strip() if match else "unknown"
+
+
+def get_description(text: str) -> str:
+    match = re.search(r"^description:\s*\|?\s*(.+?)(?=\n\w+:|---)", text, re.DOTALL | re.MULTILINE)
+    return match.group(1).strip()[:200] if match else ""
+
+
+def diff_skills(old_path: str, new_path: str) -> dict:
+    old_text = Path(old_path).read_text(encoding="utf-8")
+    new_text = Path(new_path).read_text(encoding="utf-8")
+
+    old_sections = extract_sections(old_text)
+    new_sections = extract_sections(new_text)
+
+    old_keys = set(old_sections.keys())
+    new_keys = set(new_sections.keys())
+
+    added = sorted(new_keys - old_keys - {"__preamble__"})
+    removed = sorted(old_keys - new_keys - {"__preamble__"})
+    common = old_keys & new_keys
+
+    expanded = []
+    modified = []
+    unchanged = []
+
+    for key in sorted(common):
+        if key == "__preamble__":
+            continue
+        old_wc = len(old_sections[key].split())
+        new_wc = len(new_sections[key].split())
+        if old_wc == 0 and new_wc == 0:
+            unchanged.append(key)
+        elif new_wc > old_wc * 1.3:
+            expanded.append({"section": key, "old_words": old_wc, "new_words": new_wc})
+        elif old_sections[key] != new_sections[key]:
+            modified.append({"section": key, "old_words": old_wc, "new_words": new_wc})
+        else:
+            unchanged.append(key)
+
+    old_version = get_version(old_text)
+    new_version = get_version(new_text)
+    old_wc = len(old_text.split())
+    new_wc = len(new_text.split())
+
+    return {
+        "old_file": old_path,
+        "new_file": new_path,
+        "version_change": f"{old_version} → {new_version}",
+        "word_count_change": f"{old_wc:,} → {new_wc:,} words ({new_wc - old_wc:+,})",
+        "added": added,
+        "removed": removed,
+        "expanded": expanded,
+        "modified": modified,
+        "unchanged_count": len(unchanged),
+    }
+
+
+def print_changelog(diff: dict):
+    print(f"\n{'═' * 60}")
+    print(f"  CHANGELOG")
+    print(f"  Version: {diff['version_change']}")
+    print(f"  Size: {diff['word_count_change']}")
+    print(f"{'═' * 60}\n")
+
+    if diff["added"]:
+        print(f"  ADDED ({len(diff['added'])} new sections):")
+        for s in diff["added"]:
+            print(f"    + {s}")
+        print()
+
+    if diff["expanded"]:
+        print(f"  EXPANDED ({len(diff['expanded'])} sections grown significantly):")
+        for s in diff["expanded"]:
+            print(f"    ↑ {s['section']}  ({s['old_words']} → {s['new_words']} words)")
+        print()
+
+    if diff["modified"]:
+        print(f"  MODIFIED ({len(diff['modified'])} sections changed):")
+        for s in diff["modified"]:
+            print(f"    ~ {s['section']}  ({s['old_words']} → {s['new_words']} words)")
+        print()
+
+    if diff["removed"]:
+        print(f"  REMOVED ({len(diff['removed'])} sections):")
+        for s in diff["removed"]:
+            print(f"    - {s}")
+        print()
+
+    print(f"  Unchanged sections: {diff['unchanged_count']}")
+    print(f"\n{'═' * 60}\n")
+
+
+def print_markdown_changelog(diff: dict):
+    print(f"## Changelog — {diff['version_change']}\n")
+    print(f"**Size**: {diff['word_count_change']}\n")
+
+    if diff["added"]:
+        print("### Added")
+        for s in diff["added"]:
+            print(f"- {s}")
+        print()
+
+    if diff["expanded"]:
+        print("### Expanded")
+        for s in diff["expanded"]:
+            print(f"- {s['section']} ({s['old_words']} → {s['new_words']} words)")
+        print()
+
+    if diff["modified"]:
+        print("### Modified")
+        for s in diff["modified"]:
+            print(f"- {s['section']}")
+        print()
+
+    if diff["removed"]:
+        print("### Removed")
+        for s in diff["removed"]:
+            print(f"- {s}")
+        print()
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        print("Usage: python changelog_gen.py <old_SKILL.md> <new_SKILL.md> [--json|--markdown]")
+        sys.exit(1)
+
+    old_path, new_path = sys.argv[1], sys.argv[2]
+    mode = sys.argv[3] if len(sys.argv) > 3 else "--report"
+
+    for p in [old_path, new_path]:
+        if not Path(p).exists():
+            print(f"Error: File not found: {p}", file=sys.stderr)
+            sys.exit(1)
+
+    diff = diff_skills(old_path, new_path)
+
+    if mode == "--json":
+        print(json.dumps(diff, indent=2))
+    elif mode == "--markdown":
+        print_markdown_changelog(diff)
+    else:
+        print_changelog(diff)

package/skills/overhaul/scripts/skill_parser.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""
+skill_parser.py — Parse and analyze a SKILL.md file
+
+Extracts frontmatter, sections, version, word count, and structural
+metrics. Used by the overhaul skill as the first diagnostic step.
+
+Usage:
+    python skill_parser.py <SKILL.md>
+    python skill_parser.py <SKILL.md> --json
+    python skill_parser.py <SKILL.md> --sections
+"""
+
+import sys
+import re
+import json
+from pathlib import Path
+
+# ─── Parser ───────────────────────────────────────────────────────────────────
+
+def parse_frontmatter(text: str) -> tuple[dict, str]:
+    """Extract YAML frontmatter and return (meta, body)."""
+    if not text.startswith("---"):
+        return {}, text
+
+    end = text.find("---", 3)
+    if end == -1:
+        return {}, text
+
+    yaml_block = text[3:end].strip()
+    body = text[end + 3:].strip()
+
+    meta = {}
+    for line in yaml_block.splitlines():
+        if ":" in line:
+            key, _, value = line.partition(":")
+            key = key.strip()
+            value = value.strip().strip('"').strip("'")
+            if key == "description":
+                # multiline description — grab until next key
+                meta[key] = value
+            else:
+                meta[key] = value
+
+    # Handle multiline description
+    desc_match = re.search(r"description:\s*\|(.+?)(?=\n\w+:|$)", yaml_block, re.DOTALL)
+    if desc_match:
+        meta["description"] = desc_match.group(1).strip()
+
+    return meta, body
+
+
+def extract_sections(body: str) -> list:
+    """Extract all ## and ### sections with their content."""
+    sections = []
+    lines = body.splitlines()
+    current = None
+
+    for line in lines:
+        h2 = re.match(r"^## (.+)", line)
+        h3 = re.match(r"^### (.+)", line)
+
+        if h2:
+            if current:
+                sections.append(current)
+            current = {
+                "level": 2,
+                "title": h2.group(1).strip(),
+                "content": "",
+                "word_count": 0,
+                "subsections": [],
+            }
+        elif h3 and current:
+            # Count words in current section before starting subsection
+            sub = {
+                "level": 3,
+                "title": h3.group(1).strip(),
+                "content": "",
+                "word_count": 0,
+            }
+            current["subsections"].append(sub)
+        elif current:
+            if current["subsections"]:
+                current["subsections"][-1]["content"] += line + "\n"
+            else:
+                current["content"] += line + "\n"
+
+    if current:
+        sections.append(current)
+
+    # Calculate word counts
+    for sec in sections:
+        sec["word_count"] = len(sec["content"].split())
+        for sub in sec.get("subsections", []):
+            sub["word_count"] = len(sub["content"].split())
+
+    return sections
+
+
+def detect_issues(meta: dict, body: str, sections: list) -> list:
+    """Detect potential skill quality issues."""
+    issues = []
+
+    # No version
+    if "version" not in meta:
+        issues.append({
+            "severity": "low",
+            "issue": "No version number in frontmatter",
+            "fix": "Add `version: 1.0.0` to frontmatter",
+        })
+
+    # Description too short
+    desc = meta.get("description", "")
+    if len(desc) < 50:
+        issues.append({
+            "severity": "medium",
+            "issue": f"Description too short ({len(desc)} chars) — won't trigger reliably",
+            "fix": "Expand description to include trigger phrases and use cases",
+        })
+
+    if len(desc) > 400:
+        issues.append({
+            "severity": "low",
+            "issue": f"Description very long ({len(desc)} chars) — may be truncated",
+            "fix": "Trim to under 300 chars while keeping key trigger phrases",
+        })
+
+    # No output format defined
+    output_keywords = ["output", "format", "deliver", "result", "produce"]
+    has_output_section = any(
+        any(kw in sec["title"].lower() for kw in output_keywords)
+        for sec in sections
+    )
+    body_lower = body.lower()
+    has_output_mention = any(kw in body_lower for kw in output_keywords)
+
+    if not has_output_section and not has_output_mention:
+        issues.append({
+            "severity": "high",
+            "issue": "No output format defined",
+            "fix": "Add an OUTPUT section with a concrete template",
+        })
+
+    # No error handling
+    error_keywords = ["error", "fail", "if not", "missing", "invalid", "edge case"]
+    has_error_handling = any(kw in body_lower for kw in error_keywords)
+    if not has_error_handling:
+        issues.append({
+            "severity": "medium",
+            "issue": "No error handling or edge case coverage",
+            "fix": "Add an ERROR HANDLING section for common failure modes",
+        })
+
+    # No quality gate / verification
+    quality_keywords = ["verify", "check", "validate", "quality", "review", "audit", "pass"]
+    has_quality = any(kw in body_lower for kw in quality_keywords)
+    if not has_quality:
+        issues.append({
+            "severity": "medium",
+            "issue": "No quality gate or self-verification step",
+            "fix": "Add a verification checklist before final output",
+        })
+
+    # Sections with very little content (compressed)
+    for sec in sections:
+        if sec["word_count"] < 20 and sec["title"] not in ("", "Quick Reference"):
+            issues.append({
+                "severity": "medium",
+                "issue": f'Section "{sec["title"]}" is very thin ({sec["word_count"]} words) — likely over-compressed',
+                "fix": f'Expand "{sec["title"]}" with concrete instructions, examples, or rules',
+            })
+
+    # No examples
+    example_keywords = ["example", "before:", "after:", "e.g.", "for instance", "sample"]
+    has_examples = any(kw in body_lower for kw in example_keywords)
+    if not has_examples:
+        issues.append({
+            "severity": "low",
+            "issue": "No examples in skill body",
+            "fix": "Add at least one before/after example or sample output",
+        })
+
+    return issues
+
+
+def analyze_skill(filepath: str) -> dict:
+    path = Path(filepath)
+    if not path.exists():
+        print(f"Error: File not found: {filepath}", file=sys.stderr)
+        sys.exit(1)
+
+    text = path.read_text(encoding="utf-8")
+    meta, body = parse_frontmatter(text)
+    sections = extract_sections(body)
+
+    total_words = len(text.split())
+    total_lines = len(text.splitlines())
+    issues = detect_issues(meta, body, sections)
+
+    return {
+        "file": str(path),
+        "name": meta.get("name", "unknown"),
+        "version": meta.get("version", "unversioned"),
+        "description": meta.get("description", ""),
+        "description_length": len(meta.get("description", "")),
+        "total_words": total_words,
+        "total_lines": total_lines,
+        "section_count": len(sections),
+        "sections": [
+            {
+                "title": s["title"],
+                "level": s["level"],
+                "word_count": s["word_count"],
+                "subsection_count": len(s.get("subsections", [])),
+            }
+            for s in sections
+        ],
+        "issues": issues,
+        "issue_count": len(issues),
+        "meta": meta,
+    }
+
+
+def print_analysis(result: dict):
+    print(f"\n{'═' * 60}")
+    print(f"  SKILL ANALYSIS: {result['name']} v{result['version']}")
+    print(f"  File: {result['file']}")
+    print(f"{'═' * 60}")
+    print(f"  Words: {result['total_words']:,} | Lines: {result['total_lines']:,} | Sections: {result['section_count']}")
+    print(f"  Description: {result['description_length']} chars")
+
+    print(f"\n  SECTIONS:")
+    for sec in result["sections"]:
+        indent = "  " if sec["level"] == 2 else "    "
+        print(f"  {indent}{'##' if sec['level'] == 2 else '###'} {sec['title']:<40} {sec['word_count']:>5} words")
+
+    if result["issues"]:
+        print(f"\n  ISSUES DETECTED ({result['issue_count']}):")
+        for issue in sorted(result["issues"], key=lambda x: {"high": 0, "medium": 1, "low": 2}[x["severity"]]):
+            icon = "✗" if issue["severity"] == "high" else "⚠" if issue["severity"] == "medium" else "○"
+            print(f"\n  {icon} [{issue['severity'].upper()}] {issue['issue']}")
+            print(f"      Fix: {issue['fix']}")
+    else:
+        print(f"\n  ✓ No structural issues detected.")
+
+    print(f"\n{'═' * 60}\n")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python skill_parser.py <SKILL.md> [--json|--sections]")
+        sys.exit(1)
+
+    filepath = sys.argv[1]
+    mode = sys.argv[2] if len(sys.argv) > 2 else "--report"
+
+    result = analyze_skill(filepath)
+
+    if mode == "--json":
+        print(json.dumps(result, indent=2))
+    elif mode == "--sections":
+        for sec in result["sections"]:
+            print(f"{'  ' * (sec['level'] - 1)}{'#' * sec['level']} {sec['title']} ({sec['word_count']} words)")
+    else:
+        print_analysis(result)

package/skills/overhaul/scripts/version_bump.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""
+version_bump.py — Bump version number in a SKILL.md file
+
+Usage:
+    python version_bump.py <SKILL.md>                  # auto-bump patch
+    python version_bump.py <SKILL.md> --minor          # bump minor
+    python version_bump.py <SKILL.md> --major          # bump major
+    python version_bump.py <SKILL.md> --set 2.1.0      # set specific version
+    python version_bump.py <SKILL.md> --dry-run        # preview only
+"""
+
+import sys
+import re
+from pathlib import Path
+
+
+def parse_version(v: str) -> tuple:
+    parts = v.strip().split(".")
+    if len(parts) != 3:
+        raise ValueError(f"Invalid version format: {v}")
+    return tuple(int(p) for p in parts)
+
+
+def format_version(major: int, minor: int, patch: int) -> str:
+    return f"{major}.{minor}.{patch}"
+
+
+def bump_version(current: str, bump_type: str) -> str:
+    major, minor, patch = parse_version(current)
+    if bump_type == "major":
+        return format_version(major + 1, 0, 0)
+    elif bump_type == "minor":
+        return format_version(major, minor + 1, 0)
+    else:  # patch
+        return format_version(major, minor, patch + 1)
+
+
+def update_skill_version(filepath: str, new_version: str, dry_run: bool = False) -> dict:
+    path = Path(filepath)
+    if not path.exists():
+        print(f"Error: File not found: {filepath}", file=sys.stderr)
+        sys.exit(1)
+
+    text = path.read_text(encoding="utf-8")
+
+    # Find existing version
+    version_match = re.search(r"^version:\s*(.+)$", text, re.MULTILINE)
+    old_version = version_match.group(1).strip() if version_match else None
+
+    if version_match:
+        new_text = re.sub(
+            r"^(version:\s*)(.+)$",
+            f"\\g<1>{new_version}",
+            text,
+            count=1,
+            flags=re.MULTILINE,
+        )
+    else:
+        # Insert version after name line
+        new_text = re.sub(
+            r"^(name:\s*.+)$",
+            f"\\g<1>\nversion: {new_version}",
+            text,
+            count=1,
+            flags=re.MULTILINE,
+        )
+
+    result = {
+        "file": str(path),
+        "old_version": old_version or "none",
+        "new_version": new_version,
+        "dry_run": dry_run,
+    }
+
+    if not dry_run:
+        path.write_text(new_text, encoding="utf-8")
+        result["written"] = True
+    else:
+        result["written"] = False
+
+    return result
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python version_bump.py <SKILL.md> [--major|--minor|--patch|--set X.Y.Z] [--dry-run]")
+        sys.exit(1)
+
+    filepath = sys.argv[1]
+    args = sys.argv[2:]
+
+    bump_type = "patch"
+    set_version = None
+    dry_run = "--dry-run" in args
+
+    if "--major" in args:
+        bump_type = "major"
+    elif "--minor" in args:
+        bump_type = "minor"
+    elif "--set" in args:
+        idx = args.index("--set")
+        if idx + 1 < len(args):
+            set_version = args[idx + 1]
+
+    # Read current version
+    path = Path(filepath)
+    text = path.read_text(encoding="utf-8")
+    version_match = re.search(r"^version:\s*(.+)$", text, re.MULTILINE)
+    current = version_match.group(1).strip() if version_match else "1.0.0"
+
+    if set_version:
+        new_version = set_version
+    else:
+        try:
+            new_version = bump_version(current, bump_type)
+        except ValueError:
+            new_version = "2.0.0"
+
+    result = update_skill_version(filepath, new_version, dry_run)
+
+    action = "Would update" if dry_run else "Updated"
+    print(f"\n  {action}: {result['file']}")
+    print(f"  Version: {result['old_version']} → {result['new_version']}")
+    if dry_run:
+        print(f"  (dry run — no changes written)\n")
+    else:
+        print(f"  ✓ Written\n")