@flitzrrr/agent-skills 1.0.3 → 1.2.0

package/skills/product-description-seo/scripts/check_quality.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Quality-check product descriptions against SEO requirements.
+
+Usage:
+    python check_quality.py <updates.json> [--strict] [--min-words 200] [--max-words 350]
+
+Checks each description against 8 criteria:
+1. Word count within range
+2. 4-paragraph structure
+3. Focus keyword in first sentence
+4. No banned superlatives
+5. Cross-sell reference present
+6. Formal address (no informal pronouns)
+7. Meta-description-ready opening
+8. Plain text only (no HTML/Markdown)
+"""
+
+import json
+import sys
+import re
+import argparse
+
+DEFAULT_BANNED_WORDS = [
+    # English
+    "best-in-class", "unparalleled", "revolutionary", "sensational",
+    "unmatched", "world-leading", "game-changing",
+    # German
+    "erstklassig", "herausragend", "unschlagbar", "einzigartig",
+    "revolutionaer", "sensationell", "unvergleichlich",
+    "hoechstem niveau",
+]
+
+# Indicators that a cross-sell reference is present
+CROSS_SELL_INDICATORS = [
+    "combination with", "kombination mit", "in combination",
+    "pairs well", "complement", "together with", "zusammen mit",
+    "ergaenzend", "empfehlen wir", "passend dazu",
+]
+
+# Informal pronouns that indicate wrong tone (German du-form)
+INFORMAL_PRONOUNS = [
+    r'\bdu\b', r'\bdein\b', r'\bdeine\b', r'\bdeinem\b',
+    r'\bdeinen\b', r'\bdeiner\b', r'\bdir\b', r'\bdich\b',
+]
+
+
+def check_description(product: dict, min_words: int = 200, max_words: int = 350,
+                       strict: bool = False) -> dict:
+    sku = product.get("sku", "?")
+    name = product.get("name", "?")
+    text = product.get("beschreibung", product.get("description", ""))
+
+    results = {"sku": sku, "name": name, "checks": [], "passed": 0, "failed": 0, "warnings": 0}
+
+    # 1. Word count
+    words = len(text.split())
+    if min_words <= words <= max_words:
+        results["checks"].append(("PASS", f"Word count: {words} (target: {min_words}-{max_words})"))
+        results["passed"] += 1
+    elif words > max_words:
+        results["checks"].append(("WARN", f"Word count: {words} -- above {max_words}, consider trimming"))
+        results["warnings"] += 1
+    else:
+        results["checks"].append(("FAIL", f"Word count: {words} -- below {min_words} minimum"))
+        results["failed"] += 1
+
+    # 2. Paragraph structure
+    paragraphs = [p.strip() for p in text.split("\n\n") if p.strip()]
+    if len(paragraphs) == 4:
+        results["checks"].append(("PASS", f"4-paragraph structure: {len(paragraphs)} paragraphs"))
+        results["passed"] += 1
+    elif len(paragraphs) >= 3:
+        results["checks"].append(("WARN", f"Paragraph structure: {len(paragraphs)} paragraphs (target: 4)"))
+        results["warnings"] += 1
+    else:
+        results["checks"].append(("FAIL", f"Paragraph structure: only {len(paragraphs)} paragraphs (target: 4)"))
+        results["failed"] += 1
+
+    # 3. Focus keyword in first sentence
+    first_sentence = text.split(".")[0].lower() if text else ""
+    name_parts = name.lower().split()
+    main_word = max(name_parts, key=len) if name_parts else ""
+    if main_word and main_word in first_sentence:
+        results["checks"].append(("PASS", f"Focus keyword in first sentence: '{main_word}' found"))
+        results["passed"] += 1
+    else:
+        results["checks"].append(("FAIL", f"Focus keyword missing in first sentence (expected: '{main_word}')"))
+        results["failed"] += 1
+
+    # 4. Banned superlatives
+    text_lower = text.lower()
+    found_banned = [w for w in DEFAULT_BANNED_WORDS if w in text_lower]
+    if not found_banned:
+        results["checks"].append(("PASS", "Tone: no banned superlatives"))
+        results["passed"] += 1
+    else:
+        level = "FAIL" if strict else "WARN"
+        results["checks"].append((level, f"Banned superlatives found: {', '.join(found_banned)}"))
+        if strict:
+            results["failed"] += 1
+        else:
+            results["warnings"] += 1
+
+    # 5. Cross-sell reference (warning only — not all products have natural cross-sells)
+    has_cross_sell = any(ind in text_lower for ind in CROSS_SELL_INDICATORS)
+    if has_cross_sell:
+        results["checks"].append(("PASS", "Cross-sell reference present"))
+        results["passed"] += 1
+    else:
+        level = "FAIL" if strict else "WARN"
+        results["checks"].append((level, "No cross-sell reference found"))
+        if strict:
+            results["failed"] += 1
+        else:
+            results["warnings"] += 1
+
+    # 6. Formal address
+    informal_found = []
+    for pattern in INFORMAL_PRONOUNS:
+        matches = re.findall(pattern, text_lower)
+        informal_found.extend(matches)
+    if not informal_found:
+        results["checks"].append(("PASS", "Formal address maintained"))
+        results["passed"] += 1
+    else:
+        results["checks"].append(("FAIL", f"Informal pronouns found: {', '.join(set(informal_found))}"))
+        results["failed"] += 1
+
+    # 7. Meta description
+    first_155 = text[:155]
+    if len(first_155) >= 100 and "." in first_155:
+        results["checks"].append(("PASS", f"Meta description: {len(first_155)} chars, contains sentence end"))
+        results["passed"] += 1
+    else:
+        results["checks"].append(("WARN", "Meta description: first 155 chars may need adjustment"))
+        results["warnings"] += 1
+
+    # 8. No HTML/Markdown
+    if re.search(r'<[^>]+>|#{1,6}\s|\*\*|__|\[.*\]\(.*\)', text):
+        results["checks"].append(("FAIL", "HTML or Markdown detected -- plain text only"))
+        results["failed"] += 1
+    else:
+        results["checks"].append(("PASS", "Plain text format (no HTML/Markdown)"))
+        results["passed"] += 1
+
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Quality-check product descriptions")
+    parser.add_argument("updates_path", help="Path to updates JSON file")
+    parser.add_argument("--strict", action="store_true", help="Treat warnings as failures")
+    parser.add_argument("--min-words", type=int, default=200, help="Minimum word count (default: 200)")
+    parser.add_argument("--max-words", type=int, default=350, help="Maximum word count (default: 350)")
+    args = parser.parse_args()
+
+    with open(args.updates_path, "r", encoding="utf-8") as f:
+        updates = json.load(f)
+
+    print(f"{'=' * 70}")
+    print(f"QUALITY CHECK -- {len(updates)} descriptions")
+    print(f"{'=' * 70}")
+
+    total_pass = 0
+    total_fail = 0
+    total_warn = 0
+    failed_products = []
+
+    for product in updates:
+        result = check_description(product, args.min_words, args.max_words, args.strict)
+        total_pass += result["passed"]
+        total_fail += result["failed"]
+        total_warn += result["warnings"]
+
+        status = "OK" if result["failed"] == 0 else "FAIL"
+        print(f"\n[{status}] SKU {result['sku']}: {result['name']}"
+              f" ({result['passed']}P/{result['failed']}F/{result['warnings']}W)")
+
+        for check_type, msg in result["checks"]:
+            icon = {"PASS": "  [+]", "FAIL": "  [-]", "WARN": "  [!]"}[check_type]
+            print(f"  {icon} {msg}")
+
+        if result["failed"] > 0:
+            failed_products.append(f"SKU {result['sku']}: {result['name']}")
+
+    total_checks = total_pass + total_fail + total_warn
+    print(f"\n{'=' * 70}")
+    print(f"SUMMARY")
+    print(f"{'=' * 70}")
+    print(f"Products:  {len(updates)}")
+    print(f"Checks:    {total_checks} ({total_pass} passed, {total_fail} failed, {total_warn} warnings)")
+    if total_checks > 0:
+        print(f"Pass rate: {total_pass * 100 // total_checks}%")
+
+    if failed_products:
+        print(f"\nNeeds rework:")
+        for fp in failed_products:
+            print(f"  -> {fp}")
+
+    sys.exit(1 if total_fail > 0 else 0)
+
+
+if __name__ == "__main__":
+    main()

package/skills/product-description-seo/scripts/extract_category.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Extract products of a category as JSON for batch prompting.
+
+Usage:
+    python extract_category.py <catalog.json> <category-name> [--limit 8]
+
+Supports fuzzy category matching and pagination.
+"""
+
+import json
+import sys
+import argparse
+
+DESC_FIELD = "beschreibung"
+CAT_FIELD = "kategorieName"
+CAT_FIELD_ALT = "kategorie"
+SKU_FIELD = "sku"
+NAME_FIELD = "name"
+STATUS_FIELD = "status"
+STATUS_ACTIVE = "aktiv"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Extract category products for batch prompting")
+    parser.add_argument("catalog_path", help="Path to catalog JSON file")
+    parser.add_argument("category", help="Category name (fuzzy match)")
+    parser.add_argument("--limit", "-l", type=int, default=8,
+                        help="Max products per batch (default: 8)")
+    parser.add_argument("--offset", "-o", type=int, default=0,
+                        help="Skip first N products for pagination")
+    parser.add_argument("--thin-first", "-t", action="store_true",
+                        help="Sort thinnest descriptions first")
+    args = parser.parse_args()
+
+    with open(args.catalog_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    search = args.category.lower()
+    products = [
+        p for p in data.get("products", [])
+        if p.get(STATUS_FIELD, STATUS_ACTIVE) == STATUS_ACTIVE
+        and (search in p.get(CAT_FIELD_ALT, "").lower()
+             or search in p.get(CAT_FIELD, "").lower()
+             or p.get(CAT_FIELD_ALT, "").lower() == search
+             or p.get(CAT_FIELD, "").lower() == search)
+    ]
+
+    if not products:
+        all_cats = sorted(set(
+            p.get(CAT_FIELD, p.get(CAT_FIELD_ALT, "?"))
+            for p in data.get("products", [])
+        ))
+        print(f"No active products found for '{args.category}'.", file=sys.stderr)
+        print("Available categories:", file=sys.stderr)
+        for c in all_cats:
+            print(f"  - {c}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.thin_first:
+        products.sort(key=lambda p: len(p.get(DESC_FIELD, "").split()))
+
+    batch = products[args.offset:args.offset + args.limit]
+
+    output = []
+    for p in batch:
+        entry = {
+            SKU_FIELD: p.get(SKU_FIELD, ""),
+            NAME_FIELD: p.get(NAME_FIELD, ""),
+            DESC_FIELD: p.get(DESC_FIELD, ""),
+        }
+        # Include optional fields if present
+        for field in ["variante", "preis", "preisAufAnfrage", "einheit"]:
+            if field in p:
+                entry[field] = p[field]
+        output.append(entry)
+
+    total = len(products)
+    shown = len(batch)
+    remaining = total - args.offset - shown
+
+    print(json.dumps(output, ensure_ascii=False, indent=2))
+    print(f"\n// Category: {args.category} | Shown: {shown}/{total}"
+          f" | Offset: {args.offset} | Remaining: {max(0, remaining)}",
+          file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/skills/product-description-seo/scripts/track_progress.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Track progress of a product description update campaign.
+
+Usage:
+    python track_progress.py <catalog.json> [--config product-seo-config.json] [--min-words 200]
+
+Shows overall progress, per-priority breakdown, and a next-action queue.
+Priorities are loaded from config; without config all categories are equal.
+"""
+
+import json
+import sys
+import argparse
+from collections import defaultdict
+
+DESC_FIELD = "beschreibung"
+CAT_FIELD = "kategorieName"
+CAT_FIELD_ALT = "kategorie"
+SKU_FIELD = "sku"
+NAME_FIELD = "name"
+STATUS_FIELD = "status"
+STATUS_ACTIVE = "aktiv"
+
+
+def load_priorities(config_path: str | None) -> dict[str, int]:
+    """Load priority map from config. Returns {category_name: priority_level}."""
+    if not config_path:
+        return {}
+    try:
+        with open(config_path, "r", encoding="utf-8") as f:
+            config = json.load(f)
+        prio_map = {}
+        for level, cats in config.get("priorities", {}).items():
+            for cat in cats:
+                prio_map[cat] = int(level)
+        return prio_map
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
+
+def get_priority(cat_name: str, prio_map: dict[str, int]) -> int:
+    if not prio_map:
+        return 1  # No config = all equal priority
+    return prio_map.get(cat_name, 3)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Track description update progress")
+    parser.add_argument("catalog_path", help="Path to catalog JSON file")
+    parser.add_argument("--config", help="Path to product-seo-config.json")
+    parser.add_argument("--min-words", "-m", type=int, default=200,
+                        help="Word count threshold (default: 200)")
+    args = parser.parse_args()
+
+    with open(args.catalog_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    prio_map = load_priorities(args.config)
+    products = [p for p in data.get("products", [])
+                if p.get(STATUS_FIELD, STATUS_ACTIVE) == STATUS_ACTIVE]
+
+    categories = defaultdict(lambda: {"total": 0, "done": 0, "todo": 0, "products_todo": []})
+
+    for p in products:
+        cat = p.get(CAT_FIELD, p.get(CAT_FIELD_ALT, "Unknown"))
+        wc = len(p.get(DESC_FIELD, "").split())
+        categories[cat]["total"] += 1
+        if wc >= args.min_words:
+            categories[cat]["done"] += 1
+        else:
+            categories[cat]["todo"] += 1
+            categories[cat]["products_todo"].append({
+                SKU_FIELD: p.get(SKU_FIELD, ""),
+                NAME_FIELD: p.get(NAME_FIELD, ""),
+                "words": wc,
+            })
+
+    total_products = len(products)
+    total_done = sum(c["done"] for c in categories.values())
+    total_todo = total_products - total_done
+    pct = total_done * 100 // total_products if total_products > 0 else 0
+
+    bar_len = 40
+    filled = bar_len * total_done // total_products if total_products > 0 else 0
+    bar = "#" * filled + "-" * (bar_len - filled)
+
+    print(f"{'=' * 70}")
+    print(f"PRODUCT DESCRIPTION PROGRESS")
+    print(f"{'=' * 70}")
+    print(f"\n  [{bar}] {pct}%")
+    print(f"  {total_done}/{total_products} products with >={args.min_words} words")
+    print(f"  {total_todo} remaining")
+    print(f"\n  Estimated effort: ~{total_todo // 6 + 1} batch runs at 5-8 products each")
+
+    # Determine which priority levels exist
+    prio_levels = sorted(set(get_priority(name, prio_map) for name in categories))
+
+    for prio in prio_levels:
+        prio_cats = [(name, stats) for name, stats in categories.items()
+                     if get_priority(name, prio_map) == prio]
+        if not prio_cats:
+            continue
+
+        prio_total = sum(s["total"] for _, s in prio_cats)
+        prio_done = sum(s["done"] for _, s in prio_cats)
+        prio_pct = prio_done * 100 // prio_total if prio_total > 0 else 0
+
+        label = f"PRIORITY {prio}" if prio_map else "ALL CATEGORIES"
+        print(f"\n{'-' * 70}")
+        print(f"{label} -- {prio_done}/{prio_total} done ({prio_pct}%)")
+        print(f"{'-' * 70}")
+        print(f"{'Category':<45} {'Done':>10} {'Open':>7}")
+
+        for name, stats in sorted(prio_cats, key=lambda x: x[1]["todo"], reverse=True):
+            done_str = f"{stats['done']}/{stats['total']}"
+            check = " done" if stats["todo"] == 0 else ""
+            print(f"  {name:<43} {done_str:>10} {stats['todo']:>5}  {check}")
+
+    # Next action queue
+    print(f"\n{'=' * 70}")
+    print(f"NEXT ACTIONS")
+    print(f"{'=' * 70}")
+
+    shown = 0
+    for name, stats in sorted(categories.items(),
+                               key=lambda x: (get_priority(x[0], prio_map), -x[1]["todo"])):
+        if stats["todo"] == 0:
+            continue
+        prio = get_priority(name, prio_map)
+        label = f"Prio {prio}" if prio_map else ""
+        print(f"\n  -> {name} ({label + ', ' if label else ''}{stats['todo']} open):")
+        for p in sorted(stats["products_todo"], key=lambda x: x["words"])[:5]:
+            print(f"     SKU {p[SKU_FIELD]}: {p[NAME_FIELD]} ({p['words']} words)")
+        shown += 1
+        if shown >= 5:
+            break
+
+
+if __name__ == "__main__":
+    main()

package/skills/product-description-seo/scripts/update_catalog.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Write updated product descriptions back to a catalog JSON file.
+
+Usage:
+    python update_catalog.py <catalog.json> <updates.json>
+
+updates.json format:
+[
+  {"sku": "401", "beschreibung": "New description text..."},
+  {"sku": "402", "beschreibung": "Another description..."}
+]
+
+Creates an automatic backup before writing.
+"""
+
+import json
+import sys
+import argparse
+import shutil
+from datetime import datetime
+
+DESC_FIELD = "beschreibung"
+SKU_FIELD = "sku"
+NAME_FIELD = "name"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Write updated descriptions back to catalog JSON")
+    parser.add_argument("catalog_path", help="Path to catalog JSON file")
+    parser.add_argument("updates_path", help="Path to updates JSON file")
+    args = parser.parse_args()
+
+    catalog_path = args.catalog_path
+    updates_path = args.updates_path
+
+    with open(catalog_path, "r", encoding="utf-8") as f:
+        catalog = json.load(f)
+
+    with open(updates_path, "r", encoding="utf-8") as f:
+        updates = json.load(f)
+
+    # Support both "beschreibung" and "description" field names in updates
+    update_map = {}
+    for u in updates:
+        desc = u.get(DESC_FIELD, u.get("description", ""))
+        update_map[u[SKU_FIELD]] = desc
+
+    # Create backup
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    backup_path = f"{catalog_path}.backup_{timestamp}"
+    shutil.copy2(catalog_path, backup_path)
+    print(f"Backup created: {backup_path}")
+
+    updated = 0
+    not_found = []
+
+    for product in catalog.get("products", []):
+        sku = product.get(SKU_FIELD, "")
+        if sku in update_map:
+            old_wc = len(product.get(DESC_FIELD, "").split())
+            product[DESC_FIELD] = update_map[sku]
+            new_wc = len(update_map[sku].split())
+            print(f"  [+] SKU {sku}: {product.get(NAME_FIELD, '?')} ({old_wc} -> {new_wc} words)")
+            updated += 1
+            del update_map[sku]
+
+    for sku in update_map:
+        not_found.append(sku)
+        print(f"  [-] SKU {sku}: Not found in catalog")
+
+    with open(catalog_path, "w", encoding="utf-8") as f:
+        json.dump(catalog, f, ensure_ascii=False, indent="\t")
+
+    print(f"\n{updated} descriptions updated.")
+    if not_found:
+        print(f"{len(not_found)} SKUs not found: {', '.join(not_found)}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/product-description-seo/scripts/validate_json.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Validate catalog JSON structure after description updates.
+
+Usage:
+    python validate_json.py <catalog.json>
+
+Checks: valid JSON, required fields, no duplicate SKUs,
+no HTML in descriptions, valid slug format.
+"""
+
+import json
+import sys
+import re
+from collections import Counter
+
+REQUIRED_FIELDS = ["sku", "name", "slug"]
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python validate_json.py <catalog.json>")
+        sys.exit(1)
+
+    path = sys.argv[1]
+    errors = []
+    warnings = []
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        print(f"[-] FATAL: Invalid JSON: {e}")
+        sys.exit(1)
+
+    products = data.get("products", [])
+    print(f"Validating {len(products)} products in {path}...")
+
+    # Required fields
+    for i, p in enumerate(products):
+        for field in REQUIRED_FIELDS:
+            if field not in p:
+                errors.append(f"Product #{i} (SKU {p.get('sku', '?')}): missing field '{field}'")
+
+    # Duplicate SKUs
+    skus = [p.get("sku", "") for p in products]
+    dupes = [sku for sku, count in Counter(skus).items() if count > 1]
+    if dupes:
+        errors.append(f"Duplicate SKUs: {', '.join(dupes)}")
+
+    # Empty descriptions
+    desc_field = "beschreibung" if any("beschreibung" in p for p in products[:5]) else "description"
+    for p in products:
+        if not p.get(desc_field, "").strip():
+            warnings.append(f"SKU {p.get('sku', '?')}: empty description")
+
+    # HTML in descriptions
+    for p in products:
+        desc = p.get(desc_field, "")
+        if re.search(r'<[^>]+>', desc):
+            errors.append(f"SKU {p.get('sku', '?')}: HTML tags found in description")
+
+    # Slug format
+    for p in products:
+        slug = p.get("slug", "")
+        if slug and not re.match(r'^[a-z0-9\-_\.]+$', slug):
+            warnings.append(f"SKU {p.get('sku', '?')}: slug '{slug}' contains invalid characters")
+
+    # Report
+    print(f"\n{'=' * 50}")
+    if errors:
+        print(f"[-] {len(errors)} errors found:")
+        for e in errors:
+            print(f"  [-] {e}")
+    if warnings:
+        print(f"[!] {len(warnings)} warnings:")
+        for w in warnings:
+            print(f"  [!] {w}")
+    if not errors and not warnings:
+        print("[+] All validations passed!")
+    elif not errors:
+        print(f"\n[+] No critical errors. {len(warnings)} warnings.")
+
+    sys.exit(1 if errors else 0)
+
+
+if __name__ == "__main__":
+    main()

package/skills/systematic-debugging/skill.md

@@ -0,0 +1,87 @@
+---
+name: systematic-debugging
+description: Investigate bugs, test failures, and unexpected behavior through root-cause analysis before proposing fixes. Use when encountering any technical issue.
+license: MIT
+compatibility:
+  opencode: ">=0.1"
+metadata:
+  category: debugging
+  phase: investigation
+---
+
+# Skill: Systematic Debugging
+
+This skill enforces root-cause investigation before any fix attempt. Random fixes waste time and create new bugs.
+
+---
+
+## When to Use
+
+Use for any technical issue:
+
+- Test failures
+- Bugs in production or development
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+Do **not** skip this skill when:
+
+- The issue seems simple (simple bugs have root causes too)
+- You are under time pressure (systematic debugging is faster than thrashing)
+- A fix seems obvious (obvious fixes often mask the real problem)
+
+---
+
+## Execution Model
+
+- **Primary agent** runs this skill directly.
+- **Rationale**: Debugging requires iterative investigation in the same context. Delegating to a subagent loses the accumulated understanding.
+- **Exception**: For multi-component issues spanning independent subsystems, delegate per-subsystem investigation to separate agents via the `dispatch-parallel-agents` skill.
+
+---
+
+## Workflow
+
+### Phase 1: Root Cause Investigation
+
+**No fixes are allowed until this phase is complete.**
+
+1. **Read error messages carefully** -- stack traces, line numbers, error codes. Do not skip past them.
+2. **Reproduce consistently** -- determine the exact steps. If not reproducible, gather more data instead of guessing.
+3. **Check recent changes** -- `git diff`, recent commits, new dependencies, config changes, environmental differences.
+4. **Gather evidence at component boundaries** -- for multi-layer systems (CI -> build -> deploy, API -> service -> database), add diagnostic logging at each boundary to identify where the failure occurs.
+5. **Trace data flow** -- follow the bad value backward through the call stack to its origin. Fix at the source, not at the symptom.
+
+### Phase 2: Pattern Analysis
+
+1. **Find working examples** -- locate similar working code in the same codebase.
+2. **Compare against references** -- if implementing a pattern, read the reference implementation completely. Do not skim.
+3. **Identify differences** -- list every difference between working and broken code, however small.
+4. **Understand dependencies** -- what components, settings, config, and environment does this code need?
+
+### Phase 3: Hypothesis and Testing
+
+1. **Form a single hypothesis** -- state clearly: "I think X is the root cause because Y."
+2. **Test minimally** -- make the smallest possible change to test the hypothesis. One variable at a time.
+3. **Verify before continuing** -- if the hypothesis is wrong, form a new one. Do not stack fixes.
+4. **Acknowledge unknowns** -- if you do not understand something, say so. Do not pretend.
+
+### Phase 4: Implementation
+
+1. **Fix the root cause, not the symptom.**
+2. **One change at a time** -- no "while I'm here" improvements, no bundled refactoring.
+3. **Verify the fix** -- run the relevant tests, confirm the issue is resolved, confirm no regressions.
+4. **If 3+ fixes have failed** -- stop. The issue is likely architectural, not a bug. Discuss with the user before attempting more fixes.
+
+---
+
+## Rules
+
+1. **No fixes without investigation**: Phase 1 must be complete before proposing any fix.
+2. **One hypothesis at a time**: Do not apply multiple changes simultaneously.
+3. **Evidence over intuition**: Every fix must be justified by evidence from the investigation, not by "it might work."
+4. **Escalate after 3 failed attempts**: Three failed fixes indicate an architectural problem. Stop fixing and discuss with the user.
+5. **Do not increase timeouts as a fix**: Find the real timing issue instead.
+6. **Read error messages completely**: Stack traces contain the answer more often than not.