Skip to content

hashgraph-online/awesome-codex-plugins / plugins/aklofas/kicad-happy/skills/kicad

Analyze KiCad projects and PDF schematics: schematics, PCB layouts, Gerbers, footprints, symbols, netlists, and design rules. Reviews designs for bugs, traces nets, cross-references schematic to PCB, extracts BOM data, checks DRC/ERC, DFM, power trees, and regulator circuits. Every finding carries a confidence label and evidence source with trust_summary rollup. Analyzes PDF schematics from dev boards, reference designs, eval kits, and datasheets. Supports KiCad 5–10. Use whenever the user mentions .kicad_sch, .kicad_pcb, .kicad_pro, PCB design review, schematic analysis, PDF schematics, reference designs, Gerber files, DRC/ERC, netlist issues, BOM extraction, signal tracing, power budget, DFM, or wants to understand, debug, compare, or review any hardware design. Also for "check my board", "review before fab", "what's wrong with my schematic", "is this ready to order", "check my power supply", "verify this circuit", OSHWA certification readiness, or any electronics/PCB design question.

FileKindSize
SKILL.mdskill md79.1 KB
references/config-reference.mdmarkdown19.1 KB
references/datasheet-verification.mdmarkdown16.5 KB
references/deep-review.mdmarkdown9.7 KB
references/design-intent.mdmarkdown5.6 KB
references/diff-analysis.mdmarkdown17.6 KB
references/file-formats.mdmarkdown15.1 KB
references/gerber-parsing.mdmarkdown33.5 KB
references/manual-gerber-parsing.mdmarkdown24.5 KB
references/manual-pcb-parsing.mdmarkdown17.2 KB
references/manual-schematic-parsing.mdmarkdown12.8 KB
references/net-tracing.mdmarkdown12.0 KB
references/oshwa-certification.mdmarkdown4.5 KB
references/output-schema.mdmarkdown33.4 KB
references/pcb-layout-analysis.mdmarkdown27.3 KB
references/pdf-schematic-extraction.mdmarkdown15.2 KB
references/report-generation.mdmarkdown56.3 KB
references/schematic-analysis.mdmarkdown63.9 KB
references/standards-compliance.mdmarkdown33.5 KB
references/supplementary-data-sources.mdmarkdown12.5 KB
references/what-if.mdmarkdown19.5 KB
review/README.mdmarkdown4.1 KB
review/fixtures/deep_review.example.jsonconfig1.2 KB
review/fixtures/design_context.example.jsonconfig388 B
review/fixtures/review_annotations.example.jsonconfig707 B
review/prompts/design_context.mdmarkdown4.9 KB
review/schemas/deep_review.schema.jsonconfig3.3 KB
review/schemas/design_context.schema.jsonconfig2.2 KB
review/schemas/review_annotations.schema.jsonconfig1.9 KB
review/scripts/_mini_jsonschema.pyscript6.6 KB
review/scripts/build_review_plan.pyscript2.3 KB
review/scripts/deep_review_gate.pyscript27.3 KB
review/scripts/merge_annotations.pyscript7.0 KB
review/scripts/validate_review.pyscript2.6 KB
scripts/.gitignoreother13 B
scripts/README.mdmarkdown23.4 KB
scripts/analysis_cache.pyscript42.1 KB
scripts/analyze_gerbers.pyscript90.9 KB
scripts/analyze_pcb.pyscript7.4 KB
scripts/analyze_schematic.pyscript6.7 KB
scripts/analyze_thermal.pyscript48.5 KB
scripts/analyzer_envelope.pyscript15.5 KB
scripts/capability_mode.pyscript10.2 KB
scripts/check_report_sections.pyscript10.6 KB
scripts/cross_analysis.pyscript69.4 KB
scripts/cross_verify.pyscript23.1 KB
scripts/design_intent.pyscript13.5 KB
scripts/detection_schema.pyscript26.0 KB
scripts/detector_helpers.pyscript15.2 KB
scripts/diff_analysis.pyscript23.5 KB
scripts/diff_engine.pyscript47.2 KB
scripts/domain_detectors.pyscript260.5 KB
scripts/envelopes/__init__.pyscript0 B
scripts/envelopes/cross_analysis.pyscript5.9 KB
scripts/envelopes/gerber.pyscript16.1 KB
scripts/envelopes/pcb.pyscript25.9 KB
scripts/envelopes/schematic.pyscript23.1 KB
scripts/envelopes/thermal.pyscript7.4 KB
scripts/export_issues.pyscript27.6 KB
scripts/fab_release_gate.pyscript29.8 KB
scripts/finding_schema.pyscript25.7 KB
scripts/gen_output_schema_md.pyscript9.2 KB
scripts/inputs_builder.pyscript4.0 KB
scripts/kicad_core/__init__.pyscript0 B
scripts/kicad_core/classify.pyscript32.5 KB
scripts/kicad_core/cli.pyscript4.2 KB
scripts/kicad_core/coords.pyscript2.0 KB
scripts/kicad_core/diagnostics.pyscript1.9 KB
scripts/kicad_core/executables.pyscript1.0 KB
scripts/kicad_core/fields.pyscript5.9 KB
scripts/kicad_core/fileio.pyscript5.4 KB
scripts/kicad_core/hotloop.pyscript3.1 KB
scripts/kicad_core/instances.pyscript5.7 KB
scripts/kicad_core/model.pyscript4.8 KB
scripts/kicad_core/netnames.pyscript19.1 KB
scripts/kicad_core/netquery.pyscript6.7 KB
scripts/kicad_core/pairing.pyscript1.9 KB
scripts/kicad_core/parts.pyscript28.9 KB
scripts/kicad_core/passives.pyscript10.0 KB
scripts/kicad_core/pdn.pyscript1011 B
scripts/kicad_core/project.pyscript43.2 KB
scripts/kicad_core/render.pyscript2.7 KB
scripts/kicad_core/sexp.pyscript12.6 KB
scripts/kicad_core/textvars.pyscript5.4 KB
scripts/kicad_core/token_cache.pyscript2.2 KB
scripts/kicad_core/values.pyscript14.1 KB
scripts/kicad_types.pyscript15.1 KB
scripts/lifecycle_audit.pyscript6.7 KB
scripts/lifecycle_engine.pyscript52.8 KB
scripts/lookup_detectors.pyscript29.9 KB
scripts/lookup_helpers.pyscript3.0 KB
scripts/methodology_gerbers.mdmarkdown23.1 KB
scripts/methodology_pcb.mdmarkdown22.2 KB
scripts/methodology_schematic.mdmarkdown43.1 KB
scripts/netlist_queries.pyscript4.2 KB
scripts/output_filters.pyscript16.8 KB
scripts/output_io.pyscript5.3 KB
scripts/pcb/__init__.pyscript0 B
scripts/pcb/assembly.pyscript58.3 KB
scripts/pcb/connectivity.pyscript27.7 KB
scripts/pcb/copper.pyscript61.0 KB
scripts/pcb/dfm.pyscript56.9 KB
scripts/pcb/geometry.pyscript59.5 KB
scripts/pcb/pipeline.pyscript30.3 KB
scripts/pcb/presentation.pyscript24.3 KB
scripts/pcb/reader.pyscript87.1 KB
scripts/pcb/routing.pyscript53.5 KB
scripts/project_config.pyscript23.1 KB
scripts/risk_summary.pyscript3.1 KB
scripts/run_id.pyscript1.7 KB
scripts/schema_codec.pyscript5.0 KB
scripts/schematic/__init__.pyscript0 B
scripts/schematic/audits.pyscript56.0 KB
scripts/schematic/bom_stats.pyscript6.1 KB
scripts/schematic/connectivity.pyscript62.9 KB
scripts/schematic/erc_pins.pyscript8.4 KB
scripts/schematic/hierarchy.pyscript21.5 KB
scripts/schematic/ic_analysis.pyscript21.4 KB
scripts/schematic/legacy_reader.pyscript49.4 KB
scripts/schematic/net_analysis.pyscript75.5 KB
scripts/schematic/pipeline.pyscript72.2 KB
scripts/schematic/presentation.pyscript20.9 KB
scripts/schematic/reader.pyscript64.7 KB
scripts/schematic/system_analyses.pyscript126.9 KB
scripts/signal_detectors.pyscript248.0 KB
scripts/summarize_findings.pyexecutablescript17.4 KB
scripts/validation_detectors.pyscript75.3 KB
scripts/what_if.pyscript68.4 KB

scripts/what_if.py

View on GitHub
#!/usr/bin/env python3
"""
Interactive "What-If" parameter sweep for KiCad designs.

Patches component values in analyzer JSON, re-runs affected subcircuit
calculations (and optionally SPICE simulations), and shows before/after
impact on circuit behavior.

Usage:
    python3 what_if.py analysis.json R5=4.7k
    python3 what_if.py analysis.json R5=4.7k C3=22n
    python3 what_if.py analysis.json R5=4.7k --spice
    python3 what_if.py analysis.json R5=4.7k --output patched.json
    python3 what_if.py analysis.json R5=4.7k --text

Zero dependencies — Python 3.10+ stdlib only.
"""

import argparse
import copy
import json
import math
import os
import sys
from dataclasses import dataclass

# Allow imports from same directory and spice scripts
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)),
                                "..", "..", "spice", "scripts"))

from kicad_core.values import parse_value
from kicad_core.render import fmt_g4, fmt_signed, severity_bucket
from kicad_core.fileio import atomic_write_text, json_load
from kicad_core.cli import add_only_deterministic_arg, add_output_arg, add_text_arg, utf8_text_stdout
from analysis_cache import reviewed_overlay
from finding_schema import group_findings_by_detection_type, is_old_schema


@dataclass
class Change:
    ref: str
    value: float
    value_str: str
    tolerance: float  # None = no tolerance specified


@dataclass
class SweepSpec:
    ref: str
    values: list
    value_strs: list
    tolerance: float  # None = no tolerance


# ---------------------------------------------------------------------------
# Parse change specifications
# ---------------------------------------------------------------------------

_SI_PREFIXES = ((1e9, "G"), (1e6, "M"), (1e3, "k"), (1.0, ""), (1e-3, "m"),
                (1e-6, "u"), (1e-9, "n"), (1e-12, "p"))


def _sweep_label(v: float) -> str:
    """Format a swept value with four significant figures and an SI prefix (12.92k, 3.162n)."""
    for scale, prefix in _SI_PREFIXES:
        if abs(v) >= scale * 0.9995:
            return f"{v / scale:.4g}{prefix}"
    return f"{v / 1e-12:.4g}p"


def _parse_changes(change_args: list) -> tuple:
    """Parse REF=VALUE pairs, detecting sweep syntax.

    Returns (changes_dict, sweep_or_none).
    Sweep: R5=1k,2.2k,4.7k (comma) or R5=1k..100k:10 (log range).
    Only one component may use sweep syntax.
    """
    changes = {}
    sweep = None

    for arg in change_args:
        if "=" not in arg:
            print(f"Error: invalid change '{arg}' — expected REF=VALUE", file=sys.stderr)
            sys.exit(1)
        ref, val_str = arg.split("=", 1)
        ref = ref.strip()
        val_str = val_str.strip()

        # Component type hint
        prefix = ref.rstrip("0123456789")
        ctype = None
        if prefix in ("C", "VC"):
            ctype = "capacitor"
        elif prefix in ("L",):
            ctype = "inductor"

        # Extract tolerance suffix before checking sweep syntax
        tolerance = None
        for tol_sep in ("\u00b1", "+-"):
            if tol_sep in val_str:
                main_part, tol_part = val_str.rsplit(tol_sep, 1)
                tol_str = tol_part.strip().rstrip("%")
                try:
                    tolerance = float(tol_str) / 100.0
                except ValueError:
                    tolerance = None
                    break
                val_str = main_part.strip()
                break

        if ".." in val_str and ":" in val_str:
            # Log sweep: R5=1k..100k:10
            if sweep is not None:
                print("Error: only one component may use sweep syntax", file=sys.stderr)
                sys.exit(1)
            range_part, n_str = val_str.rsplit(":", 1)
            start_str, stop_str = range_part.split("..", 1)
            start = parse_value(start_str, component_type=ctype)
            stop = parse_value(stop_str, component_type=ctype)
            try:
                n = int(n_str)
            except ValueError:
                print(f"Error: invalid step count '{n_str}'", file=sys.stderr)
                sys.exit(1)
            if start is None or stop is None or n < 2:
                print(f"Error: invalid sweep '{val_str}'", file=sys.stderr)
                sys.exit(1)
            if start <= 0 or stop <= 0:
                print(f"Error: invalid sweep '{val_str}': a log sweep needs both bounds above zero",
                      file=sys.stderr)
                sys.exit(2)
            n = min(n, 50)
            values = [start * (stop / start) ** (i / (n - 1)) for i in range(n)]
            strs = [start_str] + [_sweep_label(v) for v in values[1:-1]] + [stop_str]
            sweep = SweepSpec(ref=ref, values=values, value_strs=strs, tolerance=tolerance)

        elif "," in val_str:
            # Comma list: R5=1k,2.2k,4.7k
            if sweep is not None:
                print("Error: only one component may use sweep syntax", file=sys.stderr)
                sys.exit(1)
            parts = [p.strip() for p in val_str.split(",")]
            values = []
            for p in parts:
                v = parse_value(p, component_type=ctype)
                if v is None:
                    print(f"Error: cannot parse '{p}' in sweep for {ref}", file=sys.stderr)
                    sys.exit(1)
                values.append(v)
            sweep = SweepSpec(ref=ref, values=values, value_strs=parts, tolerance=tolerance)

        else:
            # Single value
            parsed = parse_value(val_str, component_type=ctype)
            if parsed is None:
                print(f"Error: cannot parse value '{val_str}' for {ref}", file=sys.stderr)
                sys.exit(1)
            changes[ref] = Change(ref=ref, value=parsed, value_str=val_str, tolerance=tolerance)

    return changes, sweep


# ---------------------------------------------------------------------------
# Find affected detections
# ---------------------------------------------------------------------------

def _find_refs_in_det(det: dict) -> dict:
    """Walk a detection dict and find all component refs with their value paths.

    Returns {ref: [(key_path_to_value, value_key), ...]}
    where key_path_to_value is like ["resistor"] and value_key is "ohms".
    Every member of a parallel group (``parallel_refs``) and every link of a
    series chain (``chain_resistors``) maps to the part dict that holds the
    combined value.
    """
    refs = {}

    def _check(sub, path):
        if not isinstance(sub, dict) or "ref" not in sub:
            return
        for vkey in ("ohms", "farads", "henries"):
            if vkey in sub and isinstance(sub[vkey], (int, float)):
                for ref in _part_member_refs(sub):
                    refs.setdefault(ref, []).append((path, vkey))

    for key, val in det.items():
        if isinstance(val, dict):
            _check(val, [key])
            for subkey, subval in val.items():
                if isinstance(subval, dict):
                    _check(subval, [key, subkey])
        elif isinstance(val, list):
            for idx, item in enumerate(val):
                if isinstance(item, dict):
                    _check(item, [key, idx])

    return refs


def _part_member_refs(part: dict) -> list:
    """Refs whose values make up *part*'s value: its chain links and parallel members."""
    links = part.get("chain_resistors") or [part]
    out = []
    for link in links:
        for ref in link.get("parallel_refs") or [link.get("ref")]:
            if ref and ref not in out:
                out.append(ref)
    return out


def _part_values(analysis: dict) -> dict:
    """``{ref: parsed value}`` for the analysis's components."""
    values = {}
    for comp in analysis.get("components", []):
        ref = comp.get("reference")
        if ref:
            v = parse_value(comp.get("value", ""), component_type=comp.get("type"))
            if v is not None:
                values[ref] = v
    return values


def _combine(values: list, vkey: str) -> float:
    """Parallel parts as one: capacitors add, resistors and inductors as 1/sum(1/x)."""
    if len(values) == 1:
        return values[0]
    if vkey == "farads":
        return sum(values)
    if any(v <= 0 for v in values):
        return 0.0
    return 1.0 / sum(1.0 / v for v in values)


def _patched_value(part: dict, vkey: str, changes: dict, part_values: dict):
    """*part*'s value with *changes* applied to its members, or None when an
    unchanged member's value is unknown."""
    def link_value(link):
        members = link.get("parallel_refs") or [link.get("ref")]
        if not any(m in changes for m in members):
            return link.get(vkey)
        vals = []
        for m in members:
            v = changes[m][0] if m in changes else (part_values or {}).get(m)
            if v is None:
                return None
            vals.append(v)
        return _combine(vals, vkey)

    links = part.get("chain_resistors")
    if not links:
        return link_value(part)
    vals = [link_value(link) for link in links]
    return None if any(v is None for v in vals) else sum(vals)


def _find_affected(signal_analysis: dict, changes: dict) -> list:
    """Find all detections referencing any changed component.

    Returns list of (det_type, index, det_dict, matched_refs_with_paths).
    """
    affected = []
    change_refs = set(changes.keys())

    for det_type, detections in signal_analysis.items():
        if not isinstance(detections, list):
            continue
        for idx, det in enumerate(detections):
            if not isinstance(det, dict):
                continue
            refs = _find_refs_in_det(det)
            matched = {r: paths for r, paths in refs.items() if r in change_refs}
            if matched:
                affected.append((det_type, idx, det, matched))

    return affected


# ---------------------------------------------------------------------------
# Apply changes and recalculate
# ---------------------------------------------------------------------------

def _apply_changes(det: dict, changes: dict, matched_refs: dict,
                   det_type: str, part_values: dict = None) -> dict:
    """Deep-copy detection, apply value changes, recalculate derived fields.

    A change to one member of a parallel group or a series chain recomputes the
    combined value from the changed member and the others' values in
    *part_values* (``_part_values(analysis)``).
    """
    from detection_schema import recalc_derived

    patched = copy.deepcopy(det)

    for ref, paths in matched_refs.items():
        new_val, new_str = changes[ref]
        for path, vkey in paths:
            # Navigate to the component sub-dict
            obj = patched
            for key in path:
                obj = obj[key]
            orig = det
            for key in path:
                orig = orig[key]
            if orig.get("parallel_refs") or orig.get("chain_resistors"):
                combined = _patched_value(orig, vkey, changes, part_values)
                if combined is None:
                    print(f"Warning: {'/'.join(map(str, path))} combines several parts and one "
                          f"of their values is unknown; {ref}'s change is not applied there",
                          file=sys.stderr)
                    continue
                obj[vkey] = combined
                if "value" in obj:
                    obj["value"] = _format_value(combined, vkey)
                continue
            obj[vkey] = new_val
            # Update the value string too
            if "value" in obj:
                obj["value"] = new_str

    recalc_derived(patched, det_type)
    return patched


# ---------------------------------------------------------------------------
# Before/after comparison
# ---------------------------------------------------------------------------

def _compare(original: dict, patched: dict, det_type: str) -> list:
    """Compare derived fields between original and patched detection.

    Returns list of {field, before, after, delta_pct} for changed fields.
    """
    from detection_schema import get_derived_field_names
    fields = get_derived_field_names(det_type)
    # Also check common fields not in the registry
    for extra in ("cutoff_hz", "ratio", "resonant_hz", "gain", "gain_dB",
                  "impedance_ohms", "effective_load_pF", "estimated_vout",
                  "max_current_50mV_A", "max_current_100mV_A"):
        if extra not in fields and extra in original:
            fields = list(fields) + [extra]

    deltas = []
    for field in fields:
        bv = original.get(field)
        av = patched.get(field)
        if bv is None or av is None:
            continue
        if not isinstance(bv, (int, float)) or not isinstance(av, (int, float)):
            if bv != av:
                deltas.append({"field": field, "before": bv, "after": av})
            continue
        if bv == av:
            continue
        pct = ((av - bv) / abs(bv) * 100) if bv != 0 else None
        entry = {"field": field, "before": round(bv, 6), "after": round(av, 6)}
        if pct is not None:
            entry["delta_pct"] = round(pct, 1)
        deltas.append(entry)

    return deltas


def _get_det_label(det: dict, det_type: str) -> str:
    """Build a human-readable label for a detection."""
    refs = []
    for key in ("resistor", "r_top", "inductor", "shunt"):
        if key in det and isinstance(det[key], dict) and "ref" in det[key]:
            refs.append(det[key]["ref"])
    for key in ("capacitor", "r_bottom"):
        if key in det and isinstance(det[key], dict) and "ref" in det[key]:
            refs.append(det[key]["ref"])
    if "reference" in det:
        refs.append(det["reference"])
    if det_type == "power_regulators" and det.get("ref"):
        refs.append(det["ref"])
    for key in ("feedback_resistor", "input_resistor"):
        if key in det and isinstance(det[key], dict) and "ref" in det[key]:
            refs.append(det[key]["ref"])

    type_label = det_type.replace("_", " ").rstrip("s")
    ref_str = "/".join(refs) if refs else f"#{det_type}"
    return f"{type_label} {ref_str}"


# ---------------------------------------------------------------------------
# Optional SPICE re-simulation
# ---------------------------------------------------------------------------

def _run_spice_comparison(affected: list, patched_dets: list,
                          analysis_json: dict, offline: bool = False) -> dict:
    """Run SPICE on original and patched detections, return simulated deltas.

    Returns {(det_type, idx): {metric: {before, after, delta_pct}}}
    """
    try:
        from simulate_subcircuits import simulate_subcircuits
        from spice_simulator import detect_simulator
    except ImportError:
        print("Warning: SPICE scripts not found, skipping --spice",
              file=sys.stderr)
        return {}

    backend = detect_simulator("auto")
    if not backend:
        print("Warning: no SPICE simulator found, skipping --spice",
              file=sys.stderr)
        return {}

    model_options = None
    if offline:
        from spice_model_cache import ModelOptions
        model_options = ModelOptions(offline=True)

    results = {}

    for (det_type, idx, original_det, _matched), patched_det in zip(affected, patched_dets):
        # One detection per run, so the first result is that detection's
        def _run_one(det):
            mini_json = copy.deepcopy(analysis_json)
            mini_json["findings"] = [det]
            report = simulate_subcircuits(
                mini_json, timeout=5, types=[det_type],
                simulator_backend=backend, model_options=model_options)
            sim_results = report.get("simulation_results", [])
            if sim_results and sim_results[0].get("status") != "skip":
                return sim_results[0].get("simulated", {})
            return {}

        sim_before = _run_one(original_det)
        sim_after = _run_one(patched_det)

        spice_deltas = {}
        all_keys = set(list(sim_before.keys()) + list(sim_after.keys()))
        for key in sorted(all_keys):
            bv = sim_before.get(key)
            av = sim_after.get(key)
            if bv is None or av is None:
                continue
            if not isinstance(bv, (int, float)) or not isinstance(av, (int, float)):
                continue
            if bv == av:
                continue
            pct = ((av - bv) / abs(bv) * 100) if bv != 0 else None
            entry = {"before": round(bv, 6), "after": round(av, 6)}
            if pct is not None:
                entry["delta_pct"] = round(pct, 1)
            spice_deltas[key] = entry

        if spice_deltas:
            results[(det_type, idx)] = spice_deltas

    return results


# ---------------------------------------------------------------------------
# Sweep execution
# ---------------------------------------------------------------------------

def _run_sweep(analysis: dict, sweep: SweepSpec, fixed_changes: dict) -> dict:
    """Run the what-if pipeline for each sweep value, collect tabular results."""
    signal = group_findings_by_detection_type(analysis)
    part_values = _part_values(analysis)
    results_per_step = []

    for val, val_str in zip(sweep.values, sweep.value_strs):
        # Build changes dict for this step (legacy format for existing functions)
        step_changes = {ref: (c.value, c.value_str) for ref, c in fixed_changes.items()}
        step_changes[sweep.ref] = (val, val_str)

        affected = _find_affected(signal, step_changes)
        step_subcircuits = []
        for det_type, idx, det, matched in affected:
            patched = _apply_changes(det, step_changes, matched, det_type=det_type,
                                     part_values=part_values)
            deltas = _compare(det, patched, det_type)
            label = _get_det_label(det, det_type)
            step_subcircuits.append({
                "type": det_type, "label": label,
                "delta": deltas,
                "after": {d["field"]: d["after"] for d in deltas},
            })
        results_per_step.append({
            "value": val, "value_str": val_str,
            "affected_subcircuits": step_subcircuits,
        })

    return {
        "ref": sweep.ref,
        "values": sweep.values,
        "value_strs": sweep.value_strs,
        "results": results_per_step,
    }


# ---------------------------------------------------------------------------
# Tolerance corner-case engine
# ---------------------------------------------------------------------------

def _run_tolerance(analysis: dict, changes: dict) -> list:
    """Compute worst-case tolerance bounds for each derived field.

    Evaluates all 2^N corner combinations (each component at +tol and -tol).
    Capped at 6 components (64 corners).
    """
    signal = group_findings_by_detection_type(analysis)

    # Resolve tolerances (use defaults for components without explicit tolerance)
    _DEFAULT_TOL = {"C": 0.10, "VC": 0.10, "L": 0.20}  # everything else = 0.05

    tol_info = {}  # ref -> (value, value_str, tolerance)
    for ref, c in changes.items():
        tol = c.tolerance
        if tol is None:
            prefix = ref.rstrip("0123456789")
            tol = _DEFAULT_TOL.get(prefix, 0.05)
        tol_info[ref] = (c.value, c.value_str, tol)

    changes_legacy = {ref: (c.value, c.value_str) for ref, c in changes.items()}
    affected = _find_affected(signal, changes_legacy)
    if not affected:
        return []
    part_values = _part_values(analysis)

    results = []
    for det_type, idx, det, matched in affected:
        # Nominal
        patched_nom = _apply_changes(det, changes_legacy, matched, det_type=det_type,
                                     part_values=part_values)
        nominal_deltas = _compare(det, patched_nom, det_type)
        label = _get_det_label(det, det_type)

        # Identify toleranced refs in this detection
        tol_refs = [(ref, tol_info[ref]) for ref in matched if ref in tol_info]
        # Generate 2^N corners (cap at 6 components = 64 corners)
        n = min(len(tol_refs), 6)
        corners = []
        for bits in range(1 << n):
            corner_changes = dict(changes_legacy)
            for i in range(n):
                ref, (val, vstr, tol) = tol_refs[i]
                factor = (1 + tol) if (bits >> i) & 1 else (1 - tol)
                corner_changes[ref] = (val * factor, vstr)
            corner_patched = _apply_changes(det, corner_changes, matched, det_type=det_type,
                                            part_values=part_values)
            corners.append(corner_patched)

        # For each derived field, find worst-case bounds; a field whose nominal did not
        # move is listed when the corners spread it
        from detection_schema import get_derived_field_names
        tol_results = []
        fields = [d["field"] for d in nominal_deltas]
        moved = set(fields)
        fields += [f for f in get_derived_field_names(det_type) if f not in moved]
        for field in fields:
            nom_val = patched_nom.get(field)
            if not isinstance(nom_val, (int, float)):
                continue
            corner_vals = [c.get(field) for c in corners
                          if isinstance(c.get(field), (int, float))]
            if not corner_vals:
                continue
            worst_low = min(corner_vals)
            worst_high = max(corner_vals)
            spread = worst_high - worst_low
            if not spread and field not in moved:
                continue
            spread_pct = (spread / abs(nom_val) * 100) if nom_val != 0 else 0
            tol_results.append({
                "field": field,
                "nominal": round(nom_val, 6),
                "worst_low": round(worst_low, 6),
                "worst_high": round(worst_high, 6),
                "spread_pct": round(spread_pct, 1),
            })

        results.append({"type": det_type, "label": label,
                       "delta": nominal_deltas, "tolerance": tol_results})

    return results


# ---------------------------------------------------------------------------
# Patch full JSON for export
# ---------------------------------------------------------------------------

def _patch_full_json(analysis_json: dict, affected: list,
                     patched_dets: list, changes: dict) -> dict:
    """Create a patched copy of the full analysis JSON."""
    patched = copy.deepcopy(analysis_json)

    # The affected detections are the input's own finding objects, so each one is replaced
    # at its own position: several findings can share a detection_id or a finding_id stem.
    findings = patched.get("findings", [])
    position = {id(f): fi for fi, f in enumerate(analysis_json.get("findings", []))}
    for (_det_type, _idx, orig_det, _matched), new_det in zip(affected, patched_dets):
        fi = position.get(id(orig_det))
        if fi is not None:
            findings[fi] = new_det

    for comp in patched.get("components", []):
        ref = comp.get("reference", "")
        if ref in changes:
            new_val, new_str = changes[ref]
            comp["value"] = new_str
            if isinstance(comp.get("parsed_value"), dict):
                comp["parsed_value"]["value"] = new_val
            else:
                comp["parsed_value"] = new_val

    return patched


def _change_info(analysis: dict, changes: dict) -> dict:
    """{ref: before/after values and strings} for the changed components."""
    info = {}
    for ref, (new_val, new_str) in changes.items():
        old_val = None
        old_str = ""
        for comp in analysis.get("components", []):
            if comp.get("reference") == ref:
                old_str = comp.get("value", "")
                pv = comp.get("parsed_value")
                if isinstance(pv, dict):
                    old_val = pv.get("value")
                elif isinstance(pv, (int, float)):
                    old_val = pv
                break
        info[ref] = {
            "before": old_val,
            "after": new_val,
            "before_str": old_str,
            "after_str": new_str,
            "unit": "ohms" if ref.startswith("R") else
                    "farads" if ref.startswith("C") else
                    "henries" if ref.startswith("L") else "unknown",
        }
    return info


# ---------------------------------------------------------------------------
# PCB parasitic awareness
# ---------------------------------------------------------------------------

_RHO_CU = 1.72e-8  # Copper resistivity (Ω·m)
_CU_THICKNESS_1OZ = 35e-6  # 1oz copper thickness (m)

# Footprint -> typical max capacitance (ceramic MLCC)
_FOOTPRINT_MAX_CAP = {
    "0402": 100e-9, "0603": 1e-6, "0805": 10e-6,
    "1206": 22e-6, "1210": 47e-6,
}


def _find_pcb_analysis(schematic_json_path: str) -> str:
    """Try to find PCB analysis JSON in the same analysis folder."""
    sch_dir = os.path.dirname(os.path.abspath(schematic_json_path))
    parent = os.path.dirname(sch_dir)
    # Convention: analysis/schematic/foo.json -> analysis/pcb/foo.json
    if os.path.basename(sch_dir) == "schematic":
        pcb_dir = os.path.join(parent, "pcb")
    elif "schematic" in sch_dir:
        pcb_dir = sch_dir.replace("schematic", "pcb")
    else:
        return None
    if os.path.isdir(pcb_dir):
        for f in sorted(os.listdir(pcb_dir)):
            if f.endswith(".json"):
                return os.path.join(pcb_dir, f)
    return None


def _extract_parasitics(pcb_analysis: dict, det: dict) -> dict:
    """Extract trace parasitics for components in a detection."""
    parasitics = {}
    tracks = pcb_analysis.get("tracks", {})
    if not tracks:
        tracks = pcb_analysis.get("track_summary", {})

    refs_in_det = _find_refs_in_det(det)
    for ref in refs_in_det:
        # Find component's nets from pin_nets or detection context
        comp_nets = set()
        for path, vkey in refs_in_det.get(ref, []):
            obj = det
            for k in path:
                obj = obj[k]
            net = obj.get("net", "")
            if net:
                comp_nets.add(net)

        total_r = 0.0
        total_l = 0.0
        net_name = None
        for net in sorted(comp_nets):
            net_tracks = tracks.get(net, [])
            if isinstance(net_tracks, dict):
                net_tracks = [net_tracks]
            for t in net_tracks:
                length_m = t.get("length_mm", 0) * 1e-3
                width_m = t.get("width_mm", 0) * 1e-3
                if length_m > 0 and width_m > 0:
                    r = _RHO_CU * length_m / (width_m * _CU_THICKNESS_1OZ)
                    l = (2e-7 * length_m * math.log(2 * length_m / width_m)
                         if width_m > 0 and length_m > width_m else 0)
                    total_r += r
                    total_l += abs(l)
            if net_tracks:
                net_name = net

        if total_r > 0 or total_l > 0:
            parasitics[ref] = {
                "net": net_name,
                "R_trace_ohms": round(total_r, 6),
                "L_trace_H": round(total_l, 12),
            }

    return parasitics


def _check_footprint_fit(suggestions: list, pcb_analysis: dict) -> list:
    """Check if suggested cap values fit in current footprints."""
    warnings = []
    fp_map = {}
    for comp in pcb_analysis.get("footprints", []):
        ref = comp.get("reference", "")
        fp = comp.get("footprint", "")
        fp_map[ref] = fp

    for s in suggestions:
        ref = s.get("ref", "")
        if s.get("field") != "farads":
            continue
        fp = fp_map.get(ref, "")
        for size, max_cap in _FOOTPRINT_MAX_CAP.items():
            if size in fp:
                for series in ("E96", "E24", "E12"):
                    ev = s.get("e_series", {}).get(series, {}).get("value", 0)
                    if ev > max_cap:
                        warnings.append(
                            f"\u26a0 {ref}: suggested {_format_value(ev, 'farads')}"
                            f" may require larger package than current {size}"
                            f" (typical max {_format_value(max_cap, 'farads')})"
                        )
                break
    return warnings


# ---------------------------------------------------------------------------
# Text formatter
# ---------------------------------------------------------------------------

def _format_value(val, field):
    """Format a value with appropriate units."""
    if not isinstance(val, (int, float)):
        return str(val)
    if "hz" in field.lower():
        if val >= 1e6:
            return f"{val/1e6:.2f}MHz"
        if val >= 1e3:
            return f"{val/1e3:.2f}kHz"
        return f"{val:.2f}Hz"
    if "ohms" in field.lower():
        if val >= 1e6:
            return f"{val/1e6:.2f}MΩ"
        if val >= 1e3:
            return f"{val/1e3:.2f}kΩ"
        return f"{val:.2f}Ω"
    if "farad" in field.lower():
        if val >= 1e-3:
            return f"{val*1e3:.2f}mF"
        if val >= 1e-6:
            return f"{val*1e6:.2f}µF"
        if val >= 1e-9:
            return f"{val*1e9:.2f}nF"
        return f"{val*1e12:.2f}pF"
    if field.endswith("_pF"):
        return f"{val:.1f}pF"
    if field.endswith("_A"):
        if val < 1:
            return f"{val*1000:.1f}mA"
        return f"{val:.3f}A"
    if "ratio" in field:
        return f"{val:.4f}"
    if "gain" in field.lower() and "dB" not in field:
        return f"{val:.3f}"
    if "dB" in field:
        return f"{val:.1f}dB"
    if field.startswith("estimated_vout") or field.endswith("_V") or field.endswith("_v"):
        return f"{val:.3f}V"
    return fmt_g4(val)


def format_text(result: dict) -> str:
    """Format what-if results as human-readable text."""
    lines = []

    # Header
    changes = result.get("changes", {})
    change_strs = []
    for ref, info in changes.items():
        before = info.get("before_str", str(info.get("before", "?")))
        after = info.get("after_str", str(info.get("after", "?")))
        change_strs.append(f"{ref} {before} -> {after}")
    lines.append(f"What-If Analysis: {', '.join(change_strs)}")
    lines.append("")

    subcircuits = result.get("affected_subcircuits", [])
    lines.append(f"Affected subcircuits: {len(subcircuits)}")
    if not subcircuits:
        lines.append("  No subcircuits reference the changed component(s).")
        return "\n".join(lines)

    lines.append("")

    for sc in subcircuits:
        label = sc.get("label", sc.get("type", "?"))
        lines.append(f"  {label}:")

        for d in sc.get("delta", []):
            field = d["field"]
            before = _format_value(d["before"], field)
            after = _format_value(d["after"], field)
            pct = d.get("delta_pct")
            pct_str = f" ({fmt_signed(pct)}%)" if pct is not None else ""
            lines.append(f"    {field}: {before} -> {after}{pct_str}")

        for t in sc.get("tolerance", []):
            field = t["field"]
            low = _format_value(t["worst_low"], field)
            high = _format_value(t["worst_high"], field)
            spread = t["spread_pct"]
            lines.append(f"    {field} tolerance: {low} .. {high} (\u00b1{spread/2:.1f}%)")

        # SPICE results
        for key, d in sc.get("spice_delta", {}).items():
            before = _format_value(d["before"], key)
            after = _format_value(d["after"], key)
            pct = d.get("delta_pct")
            pct_str = f" ({fmt_signed(pct)}%)" if pct is not None else ""
            lines.append(f"    SPICE {key}: {before} -> {after}{pct_str}")

        # PCB parasitics
        for ref, p in sc.get("parasitics", {}).items():
            r = p.get("R_trace_ohms", 0)
            l = p.get("L_trace_H", 0)
            net = p.get("net", "?")
            parts = []
            if r > 0:
                parts.append(f"R_trace={_format_value(r, 'ohms')}")
            if l > 0:
                parts.append(f"L_trace={l*1e9:.1f}nH")
            if parts:
                lines.append(f"    (PCB parasitics on {net}: {', '.join(parts)})")

        lines.append("")

    emc = result.get("emc_delta")
    if emc:
        lines.append("EMC impact preview:")
        lines.append(f"  Overall risk score (100 = lowest risk): "
                     f"{emc['before_risk']} \u2192 {emc['after_risk']}")
        for r in emc.get("resolved", []):
            lines.append(f"  {r['rule']}: RESOLVED \u2014 {r['detail']}")
        for r in emc.get("improved", []):
            lines.append(f"  {r['rule']}: IMPROVED \u2014 {r['before']} \u2192 {r['after']}"
                         + (f" ({r['detail']})" if r.get("detail") else ""))
        for r in emc.get("worsened", []):
            lines.append(f"  {r['rule']}: WORSENED \u2014 {r['before']} \u2192 {r['after']}"
                         + (f" ({r['detail']})" if r.get("detail") else ""))
        for r in emc.get("new_findings", []):
            lines.append(f"  {r['rule']}: NEW \u2014 {r['detail']}")
        if not (emc.get("resolved") or emc.get("improved") or emc.get("worsened")
                or emc.get("new_findings")):
            lines.append("  No EMC findings changed.")
        lines.append("")

    return "\n".join(lines)


def _format_sweep_table(sweep_result: dict) -> str:
    """Format sweep results as markdown tables."""
    lines = []
    ref = sweep_result["ref"]
    strs = sweep_result["value_strs"]
    results = sweep_result["results"]
    lines.append(f"Sweep: {ref} = {', '.join(strs)}")
    lines.append("")

    if not results or not results[0].get("affected_subcircuits"):
        lines.append("  No subcircuits affected.")
        return "\n".join(lines)

    n_subs = len(results[0]["affected_subcircuits"])
    for si in range(n_subs):
        label = results[0]["affected_subcircuits"][si]["label"]
        lines.append(f"### {label}")
        lines.append("")

        # Collect all fields across all steps
        all_fields = []
        for step in results:
            if si < len(step["affected_subcircuits"]):
                for d in step["affected_subcircuits"][si].get("delta", []):
                    if d["field"] not in all_fields:
                        all_fields.append(d["field"])

        if not all_fields:
            continue

        # Build markdown table
        col_w = max(8, max(len(s) for s in strs) + 2)
        header = f"| {'Metric':<16}|"
        sep = f"|{'-' * 17}|"
        for s in strs:
            header += f" {s:>{col_w - 1}} |"
            sep += f"{'-' * (col_w + 1)}:|"
        lines.append(header)
        lines.append(sep)

        for field in all_fields:
            row = f"| {field:<16}|"
            for step in results:
                val = None
                if si < len(step["affected_subcircuits"]):
                    val = step["affected_subcircuits"][si].get("after", {}).get(field)
                cell = _format_value(val, field) if val is not None else "-"
                row += f" {cell:>{col_w - 1}} |"
            lines.append(row)

        lines.append("")

    return "\n".join(lines)


# ---------------------------------------------------------------------------
# Inverse solver for --fix mode
# ---------------------------------------------------------------------------

def _solve_fix(det: dict, det_type: str, target_field: str,
               target_value: float) -> list:
    """Compute ideal component values to achieve target.

    Uses inverse solver from detection schema. Returns suggestions with
    E-series snapped alternatives.
    """
    from detection_schema import get_inverse_solver
    from kicad_core.values import snap_to_e_series

    inverse = get_inverse_solver(det_type, target_field)
    if inverse is None:
        return []

    suggestions = inverse(det, target_field, target_value)

    # A suggestion for a parallel group or a series chain is the combined value the
    # group needs, not a value for its first ref
    parts = {}
    for val in det.values():
        if isinstance(val, dict) and "ref" in val:
            parts.setdefault(val["ref"], val)
    for s in suggestions:
        part = parts.get(s["ref"], {"ref": s["ref"]})
        members = _part_member_refs(part)
        if len(members) > 1:
            kind = "series chain" if part.get("chain_resistors") else "parallel group"
            s["combined_refs"] = members
            s["note"] = (f"ideal is the combined value of the {kind} {', '.join(members)}; "
                         f"change the group, not {s['ref']} alone")
        anchor = parts.get(s.get("anchor_ref"))
        if anchor is not None and len(_part_member_refs(anchor)) > 1:
            s["anchor_combined_refs"] = _part_member_refs(anchor)

    # Add E-series snapped values
    for s in suggestions:
        s["e_series"] = {}
        for series in ("E12", "E24", "E96"):
            snapped, err = snap_to_e_series(s["ideal"], series)
            s["e_series"][series] = {"value": snapped, "error_pct": err}

    return suggestions


# ---------------------------------------------------------------------------
# Auto-fix scanner — identify out-of-spec detections with known targets
# ---------------------------------------------------------------------------

def _scan_fixable(signal_analysis: dict) -> list:
    """Scan signal analysis for detections that are out-of-spec with known targets.

    Returns list of dicts, each describing a fixable issue:
      {detection_type, index, det, target_field, target_value,
       issue, confidence, category}

    Categories:
      'value_fix' — component value change via inverse solver
      'derating'  — package or voltage rating recommendation
    """
    from kicad_core.netnames import parse_voltage_from_net_name

    issues = []

    # --- 1. Feedback divider Vout mismatch ---
    # Check if regulator estimated_vout differs from voltage in rail name
    for i, reg in enumerate(signal_analysis.get("power_regulators", [])):
        fb = reg.get("feedback_divider")
        if not fb:
            continue
        vout = reg.get("estimated_vout")
        vref = reg.get("assumed_vref")
        if not vout or not vref or vref <= 0:
            continue
        rail = reg.get("output_rail", "")
        rail_v = parse_voltage_from_net_name(rail)
        if rail_v is None or rail_v <= 0:
            continue
        # Compare estimated_vout with voltage parsed from rail name
        error_pct = abs(vout - rail_v) / rail_v * 100
        if error_pct < 2.0:
            continue  # Close enough — not fixable
        # Target ratio: Vref / desired_Vout (Rbot/(Rtop+Rbot)); on a three-terminal
        # adjustable Vref sits across the top resistor instead
        target_ratio = vref / rail_v
        if fb.get("reference") == "out_adj":
            target_ratio = 1 - target_ratio
        if target_ratio <= 0 or target_ratio >= 1:
            continue
        # Find this divider in voltage_dividers or feedback_networks
        fb_r_top_ref = fb.get("r_top", {}).get("ref", "")
        fb_r_bot_ref = fb.get("r_bottom", {}).get("ref", "")
        det_type = None
        det_idx = None
        det_obj = None
        for dtype in ("feedback_networks", "voltage_dividers"):
            for j, vd in enumerate(signal_analysis.get(dtype, [])):
                if (vd.get("r_top", {}).get("ref") == fb_r_top_ref and
                        vd.get("r_bottom", {}).get("ref") == fb_r_bot_ref):
                    det_type, det_idx, det_obj = dtype, j, vd
                    break
            if det_type:
                break
        if not det_type:
            continue
        ref_reg = reg.get("ref", reg.get("reference", ""))
        confidence = (reg.get("_estimated_vout_provenance") or {}).get("confidence", "heuristic")
        issues.append({
            "detection_type": det_type,
            "index": det_idx,
            "det": det_obj,
            "target_field": "ratio",
            "target_value": target_ratio,
            "issue": (
                "{ref} feedback divider: Vout={vout:.3g}V but rail "
                "'{rail}' implies {rail_v}V (error {err:.1f}%)"
            ).format(ref=ref_reg, vout=vout, rail=rail,
                     rail_v=rail_v, err=error_pct),
            "confidence": confidence,
            "category": "value_fix",
        })

    # --- 2. Crystal load capacitance mismatch ---
    for i, xtal in enumerate(signal_analysis.get("crystal_circuits", [])):
        status = xtal.get("load_cap_status")
        if status in ("ok", None):
            continue
        source = xtal.get("target_load_source")
        if source == "frequency_default":
            continue  # Low confidence target — skip auto-fix
        target = xtal.get("target_load_pF")
        actual = xtal.get("effective_load_pF")
        if not target or not actual:
            continue
        error_pct = abs(actual - target) / target * 100
        if error_pct < 10:
            continue
        xref = xtal.get("reference", "Y?")
        issues.append({
            "detection_type": "crystal_circuits",
            "index": i,
            "det": xtal,
            "target_field": "effective_load_pF",
            "target_value": target,
            "issue": (
                "{ref} load capacitance: {actual:.1f}pF vs {target:.1f}pF "
                "target ({err:.0f}% error, status={status})"
            ).format(ref=xref, actual=actual, target=target,
                     err=error_pct, status=status),
            "confidence": "deterministic",
            "category": "value_fix",
        })

    # --- 3. Output capacitor DC bias derating ---
    for i, reg in enumerate(signal_analysis.get("power_regulators", [])):
        ref_reg = reg.get("ref", reg.get("reference", ""))
        vout = reg.get("vout_estimated") or reg.get("estimated_vout")
        rail = reg.get("output_rail", "")
        for cap in reg.get("output_capacitors", []):
            df = cap.get("derating_factor")
            if df is None or df >= 0.5:
                continue
            cap_ref = cap.get("ref", "?")
            package = cap.get("package", "?")
            dielectric = cap.get("dielectric", "?")
            nominal_uf = cap.get("farads", 0) * 1e6
            effective_uf = cap.get("effective_farads", 0) * 1e6
            issues.append({
                "detection_type": "power_regulators",
                "index": i,
                "det": None,  # Not a value fix — recommendation only
                "target_field": None,
                "target_value": None,
                "issue": (
                    "{cap_ref} ({nominal:.1f}uF {dielectric} {pkg}) on "
                    "{rail_or_reg}: {df:.0f}% effective capacitance "
                    "({eff:.1f}uF of {nom:.1f}uF)"
                ).format(cap_ref=cap_ref, nominal=nominal_uf,
                         dielectric=dielectric, pkg=package,
                         rail_or_reg=rail or ref_reg,
                         df=df * 100, eff=effective_uf, nom=nominal_uf),
                "confidence": "medium",
                "category": "derating",
                "cap_ref": cap_ref,
                "cap_package": package,
                "cap_dielectric": dielectric,
                "derating_factor": df,
            })

    return issues


def _suggest_all_fixes(issues: list, pcb_analysis: dict = None) -> dict:
    """Compute fix suggestions for all scanned issues.

    For 'value_fix' issues: runs inverse solver + E-series snapping.
    For 'derating' issues: generates package/voltage recommendations.

    Returns dict with 'fix_suggestions' and 'derating_recommendations' lists.
    """
    fix_suggestions = []
    derating_recs = []

    for issue in issues:
        if issue["category"] == "value_fix":
            det = issue["det"]
            det_type = issue["detection_type"]
            target_field = issue["target_field"]
            target_value = issue["target_value"]

            suggestions = _solve_fix(det, det_type, target_field, target_value)
            if not suggestions:
                continue

            # Compute before/after for the best suggestion (first one)
            best = suggestions[0]
            best_e24 = best.get("e_series", {}).get("E24", {}).get("value")
            if best_e24 and best_e24 > 0 and best.get("combined_refs"):
                # The E24 value replaces the group's combined value
                from detection_schema import recalc_derived
                patched = copy.deepcopy(det)
                for key, val in patched.items():
                    if isinstance(val, dict) and val.get("ref") == best["ref"] and best["field"] in val:
                        val[best["field"]] = best_e24
                        break
                recalc_derived(patched, det_type)
                delta = _compare(det, patched, det_type)
            elif best_e24 and best_e24 > 0:
                # Simulate fix with E24 value
                changes = {best["ref"]: (best_e24, _format_value(best_e24, best["field"]))}
                matched = {best["ref"]: _find_refs_in_det(det).get(best["ref"], [])}
                # a load cap with no net is a leg of its own, as in the recalculation
                leg = {c.get("ref"): c.get("net") or i
                       for i, c in enumerate(det.get("load_caps") or []) if isinstance(c, dict)}
                if (det_type == "crystal_circuits"
                        and len({leg.get(sg["ref"]) for sg in suggestions}) == len(suggestions)):
                    # The load-cap solution sizes one cap per leg: they change together
                    refs = _find_refs_in_det(det)
                    for sg in suggestions[1:]:
                        e24 = sg.get("e_series", {}).get("E24", {}).get("value")
                        if e24 and e24 > 0 and refs.get(sg["ref"]):
                            changes[sg["ref"]] = (e24, _format_value(e24, sg["field"]))
                            matched[sg["ref"]] = refs[sg["ref"]]
                if matched[best["ref"]]:
                    patched = _apply_changes(det, changes, matched, det_type=det_type)
                    delta = _compare(det, patched, det_type)
                else:
                    delta = []
            else:
                delta = []

            entry = {
                "detection_type": det_type,
                "detection_index": issue["index"],
                "issue": issue["issue"],
                "confidence": issue["confidence"],
                "target_field": target_field,
                "target_value": target_value,
                "suggestions": suggestions,
                "delta_with_e24": delta,
            }
            if pcb_analysis:
                fp_warnings = _check_footprint_fit(suggestions, pcb_analysis)
                if fp_warnings:
                    entry["footprint_warnings"] = fp_warnings
            fix_suggestions.append(entry)

        elif issue["category"] == "derating":
            cap_ref = issue.get("cap_ref", "?")
            package = issue.get("cap_package", "?")
            dielectric = issue.get("cap_dielectric", "?")
            df = issue.get("derating_factor", 0)

            recs = []
            # Suggest larger package
            pkg_upgrade = {
                "0402": "0603", "0603": "0805", "0805": "1206",
            }
            next_pkg = pkg_upgrade.get(package)
            if next_pkg:
                recs.append(
                    "Upgrade {ref} from {pkg} to {next_pkg} — larger "
                    "package has less DC bias derating".format(
                        ref=cap_ref, pkg=package, next_pkg=next_pkg))
            # Suggest higher voltage rating
            recs.append(
                "Use higher voltage rating for {ref} — reduces voltage "
                "ratio and derating".format(ref=cap_ref))
            # Suggest C0G if small value
            if dielectric != "C0G":
                recs.append(
                    "Consider C0G/NP0 dielectric for {ref} — no DC bias "
                    "derating (available up to ~100nF)".format(ref=cap_ref))

            derating_recs.append({
                "issue": issue["issue"],
                "confidence": issue["confidence"],
                "cap_ref": cap_ref,
                "recommendations": recs,
            })

    return {
        "fix_suggestions": fix_suggestions,
        "derating_recommendations": derating_recs,
        "summary": {
            "fixable_issues": len(fix_suggestions),
            "derating_issues": len(derating_recs),
            "total_scanned": len(issues),
        },
    }


def _format_fix(fix_result: dict) -> str:
    """Format fix suggestion results as text."""
    lines = []
    for fix in fix_result.get("fix_suggestions", []):
        det_type = fix["detection_type"]
        target = fix["target_value"]
        field = fix["target_field"]
        lines.append(f"Fix suggestion for {det_type}[{fix['detection_index']}]"
                     f" \u2014 target {field}={_format_value(target, field)}")
        lines.append("")
        for s in fix.get("suggestions", []):
            ref = s["ref"]
            current = s["current"]
            ideal = s["ideal"]
            vkey = s["field"]
            anchor = s.get("anchor_ref")
            anchor_note = f" (keeping {anchor})" if anchor else ""
            if s.get("combined_refs"):
                ref = "combined " + "+".join(s["combined_refs"])
            lines.append(f"  {ref}{anchor_note}:")
            lines.append(f"    Ideal:  {_format_value(ideal, vkey)}")
            for series in ("E96", "E24", "E12"):
                e = s["e_series"].get(series, {})
                ev = e.get("value", 0)
                err = e.get("error_pct", 0)
                lines.append(f"    {series}:    {_format_value(ev, vkey):>10}  ({fmt_signed(err)}%)")
            lines.append("")
    for fix in fix_result.get("fix_suggestions", []):
        for w in fix.get("footprint_warnings", []):
            lines.append(f"  {w}")
    return "\n".join(lines)


def _format_suggestions(result: dict) -> str:
    """Format batch fix suggestion results as human-readable text."""
    lines = []
    fixes = result.get("fix_suggestions", [])
    derecs = result.get("derating_recommendations", [])
    summary = result.get("summary", {})

    lines.append("=== Fix Suggestions ===")
    lines.append("{total} issues found: {fix} fixable, {derate} derating".format(
        total=summary.get("total_scanned", 0),
        fix=summary.get("fixable_issues", 0),
        derate=summary.get("derating_issues", 0)))
    lines.append("")

    for i, fix in enumerate(fixes, 1):
        lines.append("--- Fix {i}: {issue} ---".format(i=i, issue=fix["issue"]))
        lines.append("  Confidence: {conf}".format(conf=fix["confidence"]))
        lines.append("  Target: {field} = {val}".format(
            field=fix["target_field"],
            val=_format_value(fix["target_value"], fix["target_field"])))
        lines.append("")
        for s in fix.get("suggestions", []):
            ref = s["ref"]
            current = s["current"]
            ideal = s["ideal"]
            vkey = s["field"]
            anchor = s.get("anchor_ref")
            anchor_note = " (keeping {a})".format(a=anchor) if anchor else ""
            if s.get("combined_refs"):
                ref = "combined " + "+".join(s["combined_refs"])
            lines.append("  {ref}{note}:".format(ref=ref, note=anchor_note))
            lines.append("    Current: {cur}".format(
                cur=_format_value(current, vkey)))
            lines.append("    Ideal:   {ideal}".format(
                ideal=_format_value(ideal, vkey)))
            for series in ("E96", "E24", "E12"):
                e = s.get("e_series", {}).get(series, {})
                ev = e.get("value", 0)
                err = e.get("error_pct", 0)
                lines.append("    {ser}:     {val:>10}  ({err:+.1f}%)".format(
                    ser=series, val=_format_value(ev, vkey), err=err))
            lines.append("")
        delta = fix.get("delta_with_e24", [])
        if delta:
            lines.append("  Impact (with E24 value):")
            for d in delta:
                lines.append("    {field}: {before} -> {after} ({pct:+.1f}%)".format(
                    field=d["field"],
                    before=_format_value(d["before"], d["field"]),
                    after=_format_value(d["after"], d["field"]),
                    pct=d.get("delta_pct", 0) or 0))
            lines.append("")
        for w in fix.get("footprint_warnings", []):
            lines.append("  Warning: {w}".format(w=w))

    if derecs:
        lines.append("")
        lines.append("=== Derating Recommendations ===")
        for i, rec in enumerate(derecs, 1):
            lines.append("")
            lines.append("--- Derating {i}: {issue} ---".format(
                i=i, issue=rec["issue"]))
            for r in rec.get("recommendations", []):
                lines.append("  * {r}".format(r=r))

    if not fixes and not derecs:
        lines.append("No fixable issues found.")

    return "\n".join(lines)


# ---------------------------------------------------------------------------
# EMC impact preview
# ---------------------------------------------------------------------------

def _run_emc_preview(analysis: dict, patched_json: dict,
                     pcb_path: str = None) -> dict:
    """Run EMC analysis on original and patched JSON, return delta."""
    import subprocess
    import tempfile

    emc_script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
                              "..", "..", "emc", "scripts", "analyze_emc.py")
    if not os.path.exists(emc_script):
        print("Warning: analyze_emc.py not found, skipping EMC preview", file=sys.stderr)
        return None

    def _run_emc(schematic_json: dict) -> dict:
        fd, sch_path = tempfile.mkstemp(suffix=".json")
        out_path = sch_path + ".emc.json"
        try:
            with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as f:
                json.dump(schematic_json, f, indent=2)
            cmd = [sys.executable, emc_script, "--schematic", sch_path, "--output", out_path]
            if pcb_path:
                cmd.extend(["--pcb", pcb_path])
            subprocess.run(cmd, capture_output=True, timeout=30, check=False)
            if os.path.exists(out_path):
                with open(out_path, encoding="utf-8") as f:
                    return json.load(f)
        except (subprocess.TimeoutExpired, OSError, json.JSONDecodeError) as e:
            print(f"Warning: EMC analysis failed: {e}", file=sys.stderr)
        finally:
            for p in (sch_path, out_path):
                try:
                    os.unlink(p)
                except OSError:
                    pass
        return None

    before = _run_emc(analysis)
    after = _run_emc(patched_json)
    if not before or not after:
        return None

    import diff_engine

    found = diff_engine.diff_emc(before, after, 1.0).get("findings", {})
    rank = {"info": 0, "warning": 1, "error": 2}

    def _severity_row(c):
        return {"rule": c["rule_id"], "before": c["base_severity"], "after": c["head_severity"],
                "detail": c.get("title", "")}

    changed = found.get("changed_severity", [])
    worse = [c for c in changed if rank.get(severity_bucket(c["head_severity"]), 0)
             > rank.get(severity_bucket(c["base_severity"]), 0)]
    better = [c for c in changed if c not in worse]
    n_before = sum(1 for f in before.get("findings", []) if isinstance(f, dict))
    summary_before = before.get("summary") or {}
    summary_after = after.get("summary") or {}
    return {
        "before_risk": summary_before.get("emc_risk_score"),
        "after_risk": summary_after.get("emc_risk_score"),
        "resolved": [{"rule": f["rule_id"], "detail": f.get("title", "")}
                     for f in found.get("resolved", [])],
        "improved": [_severity_row(c) for c in better],
        "worsened": [_severity_row(c) for c in worse],
        "new_findings": [{"rule": f["rule_id"], "detail": f.get("title", "")}
                         for f in found.get("new", [])],
        "unchanged": n_before - len(found.get("resolved", [])) - len(changed),
    }


# ---------------------------------------------------------------------------
# Main
# ---------------------------------------------------------------------------

def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="What-if parameter sweep for KiCad designs"
    )
    parser.add_argument("input", help="Analyzer JSON (from analyze_schematic.py)")
    parser.add_argument("changes", nargs="*", default=[],
                        help="REF=VALUE pairs (e.g., R5=4.7k C3=22n)")
    parser.add_argument("--spice", action="store_true",
                        help="Re-run SPICE simulations on affected subcircuits at the new "
                             "values (not with a sweep)")
    parser.add_argument("--offline", action="store_true",
                        help="With --spice: part models from the cache and the built-in "
                             "table only")
    add_output_arg(parser, help="Write the patched analysis JSON to FILE (single changes only)")
    add_text_arg(parser, help="Human-readable text output")
    parser.add_argument("--emc", action="store_true",
                        help="Show EMC impact preview (runs analyze_emc.py)")
    parser.add_argument("--pcb",
                        help="PCB analysis JSON for parasitic awareness")
    parser.add_argument("--fix",
                        help="Detection to fix (e.g., voltage_dividers[0])")
    parser.add_argument("--target", type=float,
                        help="Target value for --fix, in the detection's own field: a ratio "
                             "0-1 for voltage_dividers (Vout/Vin) and for a regulator's "
                             "feedback_networks (Vref/Vout), Hz for rc_filters/lc_filters, "
                             "gain for opamp_circuits, pF for crystal_circuits")
    parser.add_argument("--suggest-fixes", action="store_true",
                        help="Scan analysis for fixable issues and suggest component changes")
    add_only_deterministic_arg(parser, consumer=True)
    args = parser.parse_args(argv)
    if args.text:
        utf8_text_stdout()

    if not args.changes and not args.fix and not args.suggest_fixes:
        parser.error("at least one REF=VALUE change, --fix, or --suggest-fixes is required")

    # Load analysis JSON (honor --only-deterministic: skip merged/ overlay)
    def _resolve_input_path(path):
        from pathlib import Path
        p = Path(path)
        if not args.only_deterministic:
            overlay = reviewed_overlay(str(p))
            if overlay:
                return Path(overlay)
        return p

    try:
        with open(_resolve_input_path(args.input), encoding="utf-8") as f:
            analysis = json_load(f)
    except (json.JSONDecodeError, OSError, UnicodeDecodeError) as e:
        print(f"Error reading {args.input}: {e}", file=sys.stderr)
        return 1

    if is_old_schema(analysis):
        print("Error: this JSON uses the pre-v1.3 signal_analysis wrapper "
              "format.\nRe-run analyze_schematic.py to produce the current "
              "findings[] format.", file=sys.stderr)
        return 1

    signal = group_findings_by_detection_type(analysis)
    if not signal:
        print("Error: no subcircuit findings in input JSON", file=sys.stderr)
        return 1

    # Load PCB analysis if available
    pcb_path = args.pcb
    pcb_analysis = None
    if pcb_path:
        try:
            with open(pcb_path, encoding="utf-8") as f:
                pcb_analysis = json_load(f)
        except (json.JSONDecodeError, OSError, UnicodeDecodeError) as e:
            print(f"Warning: cannot load PCB analysis: {e}", file=sys.stderr)
    else:
        auto_pcb = _find_pcb_analysis(args.input)
        if auto_pcb:
            try:
                with open(auto_pcb, encoding="utf-8") as f:
                    pcb_analysis = json_load(f)
            except (json.JSONDecodeError, OSError, UnicodeDecodeError):
                pass

    # --- Suggest-fixes branch ---
    if args.suggest_fixes:
        issues = _scan_fixable(signal)
        result = _suggest_all_fixes(issues, pcb_analysis)
        if args.text:
            print(_format_suggestions(result))
        else:
            json.dump(result, sys.stdout, indent=2)
            print()
        return 0

    # --- Fix branch ---
    if args.fix:
        import re as _re
        m = _re.match(r'(\w+)\[(\d+)\]', args.fix)
        if not m:
            print(f"Error: invalid --fix target '{args.fix}' \u2014 use type[index] "
                  f"(e.g., voltage_dividers[0])", file=sys.stderr)
            return 1
        fix_det_type = m.group(1)
        fix_idx = int(m.group(2))
        dets = signal.get(fix_det_type, [])
        if fix_idx >= len(dets):
            print(f"Error: {fix_det_type}[{fix_idx}] does not exist "
                  f"(have {len(dets)} detections)", file=sys.stderr)
            return 1
        det = dets[fix_idx]

        if args.target is not None:
            from detection_schema import get_derived_field_names
            fields = get_derived_field_names(fix_det_type)
            target_field = fields[0] if fields else "ratio"
            target_value = args.target
        else:
            # Try to infer target from context
            target_field, target_value = None, None
            if fix_det_type in ("voltage_dividers", "feedback_networks"):
                vref = det.get("regulator_vref")
                vout = det.get("target_vout")
                if vref and vout and vout > 0:
                    target_field, target_value = "ratio", vref / vout
            elif fix_det_type == "crystal_circuits":
                tl = det.get("target_load_pF")
                if tl:
                    target_field, target_value = "effective_load_pF", tl
            if target_field is None:
                print(f"Error: cannot infer target for {fix_det_type} \u2014 use --target",
                      file=sys.stderr)
                return 1

        suggestions = _solve_fix(det, fix_det_type, target_field, target_value)
        if not suggestions:
            if target_field == "ratio" and not 0 < target_value < 1:
                why = (f"target ratio {target_value:g} is outside (0, 1); a divider target is "
                       f"Vout/Vin (feedback: Vref/Vout), not a voltage")
            else:
                why = (f"no component values reach {target_field}={target_value:g} "
                       f"for this detection")
            print(f"Error: {fix_det_type}[{fix_idx}]: {why}", file=sys.stderr)
            return 1
        result = {"fix_suggestions": [{
            "detection_type": fix_det_type,
            "detection_index": fix_idx,
            "target_field": target_field,
            "target_value": target_value,
            "suggestions": suggestions,
        }]}
        if pcb_analysis:
            fp_warnings = _check_footprint_fit(suggestions, pcb_analysis)
            if fp_warnings:
                result["fix_suggestions"][0]["footprint_warnings"] = fp_warnings
        if args.text:
            print(_format_fix(result))
        else:
            json.dump(result, sys.stdout, indent=2)
            print()
        return 0

    # Parse changes — returns (dict of Change, optional SweepSpec)
    changes, sweep = _parse_changes(args.changes)

    # Verify refs exist in the analysis
    all_refs = set()
    for comp in analysis.get("components", []):
        if "reference" in comp:
            all_refs.add(comp["reference"])
    for ref in changes:
        if ref not in all_refs:
            print(f"Warning: {ref} not found in component list", file=sys.stderr)
    if sweep and sweep.ref not in all_refs:
        print(f"Warning: {sweep.ref} not found in component list", file=sys.stderr)

    # --- Sweep branch ---
    if sweep is not None:
        if args.spice:
            parser.error("--spice cannot be combined with a sweep; simulate one value at a time")
        if sweep.tolerance is not None or any(c.tolerance is not None for c in changes.values()):
            parser.error("tolerance corners are not supported with a sweep; "
                         "run each value as a single change")
        if args.output:
            parser.error("--output exports one patched design; it cannot be combined with a sweep")
        sweep_result = _run_sweep(analysis, sweep, changes)
        if args.text:
            print(_format_sweep_table(sweep_result))
        else:
            json.dump(sweep_result, sys.stdout, indent=2)
            print()
        return 0

    # --- Single-value branch ---
    # Convert Change objects to legacy (value, str) tuples for downstream functions
    changes_legacy = {ref: (c.value, c.value_str) for ref, c in changes.items()}

    # Find affected detections
    affected = _find_affected(signal, changes_legacy)
    if not affected:
        print(f"No subcircuits reference {', '.join(changes_legacy.keys())}",
              file=sys.stderr)
        if args.output:
            try:
                atomic_write_text(args.output, json.dumps(analysis, indent=2), follow_symlinks=False)
            except OSError as e:
                print(f"Error: cannot write {args.output}: {e}", file=sys.stderr)
                return 1
            print(f"No subcircuit changed; wrote the unchanged analysis to {args.output}",
                  file=sys.stderr)
        result = {
            "changes": _change_info(analysis, changes_legacy),
            "affected_subcircuits": [],
            "summary": {"components_changed": len(changes_legacy),
                        "subcircuits_affected": 0, "spice_verified": False},
        }
        if args.text:
            print(format_text(result))
        elif not args.output:
            json.dump(result, sys.stdout, indent=2)
            print()
        return 0

    # Apply changes to each affected detection
    patched_dets = []
    part_values = _part_values(analysis)
    for det_type, idx, det, matched in affected:
        patched = _apply_changes(det, changes_legacy, matched, det_type=det_type,
                                 part_values=part_values)
        patched_dets.append(patched)

    # Build before/after comparisons
    subcircuit_results = []
    for (det_type, idx, det, matched), patched in zip(affected, patched_dets):
        deltas = _compare(det, patched, det_type)
        label = _get_det_label(det, det_type)
        comps = []
        refs_in_det = _find_refs_in_det(det)
        for r in refs_in_det:
            comps.append(r)

        entry = {
            "type": det_type,
            "label": label,
            "components": comps,
            "delta": deltas,
            "before": {d["field"]: d["before"] for d in deltas},
            "after": {d["field"]: d["after"] for d in deltas},
        }
        subcircuit_results.append(entry)

    # PCB parasitics
    if pcb_analysis:
        for (det_type, idx, det, matched), sc in zip(affected, subcircuit_results):
            paras = _extract_parasitics(pcb_analysis, det)
            if paras:
                sc["parasitics"] = paras

    # Tolerance analysis
    has_tolerance = any(c.tolerance is not None for c in changes.values())
    if has_tolerance:
        tol_results = _run_tolerance(analysis, changes)
        for tr in tol_results:
            for sc in subcircuit_results:
                if sc["type"] == tr["type"] and sc["label"] == tr["label"]:
                    sc["tolerance"] = tr.get("tolerance", [])

    # Optional SPICE
    spice_results = {}
    if args.spice:
        spice_results = _run_spice_comparison(affected, patched_dets, analysis,
                                              offline=args.offline)
        for i, (det_type, idx, _det, _matched) in enumerate(affected):
            key = (det_type, idx)
            if key in spice_results:
                subcircuit_results[i]["spice_delta"] = spice_results[key]

    result = {
        "changes": _change_info(analysis, changes_legacy),
        "affected_subcircuits": subcircuit_results,
        "summary": {
            "components_changed": len(changes_legacy),
            "subcircuits_affected": len(affected),
            "spice_verified": bool(spice_results),
        },
    }

    # EMC impact preview
    if args.emc:
        patched_json = _patch_full_json(analysis, affected, patched_dets, changes_legacy)
        pcb = getattr(args, "pcb", None)
        emc_delta = _run_emc_preview(analysis, patched_json, pcb_path=pcb)
        if emc_delta:
            result["emc_delta"] = emc_delta

    # Export patched JSON if requested
    if args.output:
        patched_json = _patch_full_json(analysis, affected, patched_dets, changes_legacy)
        try:
            atomic_write_text(args.output, json.dumps(patched_json, indent=2), follow_symlinks=False)
        except OSError as e:
            print(f"Error: cannot write {args.output}: {e}", file=sys.stderr)
            return 1
        print(f"Patched JSON written to {args.output}", file=sys.stderr)

    # Output results
    if args.text:
        print(format_text(result))
    elif not args.output:
        json.dump(result, sys.stdout, indent=2)
        print()
    return 0


if __name__ == "__main__":
    from kicad_core.cli import utf8_stdio
    utf8_stdio()
    sys.exit(main())
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall