mbg-repo-analysis
Maps the Microelectronic Block Generator repository, traces the active execution path from a design script to the layout pipeline, separates active implementations from legacy code kept only for backw
SKILL.md.ai/skills/mbg-repo-analysis/SKILL.md
GitHubMBG Repository Analysis
Before you read anything: context economy
This repository is big enough that how you gather information decides
whether you finish. A measured session here spent 87% of a 1 MB
conversation on tool output — one file re-read 22 times, git status
polled 27+ times, and 33 KB spent searching $HOME for a repo whose path
was already in $MBG_ROOT. Read mbg-context-economy first. The short
version: resolve the repo from $MBG_ROOT, index a file before opening it,
never re-read what is already in context, do not poll git state, and climb
the verification ladder cheapest-first. Reading less is the goal; checking
less is not.
Purpose
Give an agent a reliable, current picture of the codebase before it touches anything: where the live execution path runs, which modules are legacy compatibility shims, and how to read a SPICE netlist the way the pipeline does. This skill only inspects; it never edits.
When to Use
- Before modifying any file under
src/mbg/. - When asked "what actually runs when a design script executes" or "which module owns X".
- When you need to enumerate a netlist's devices, nets, or terminals before reasoning about placement or routing.
- When deciding whether a proposed change touches the active pipeline or a legacy fallback that other code still depends on.
When Not to Use
- Generating a layout — use
mbg-spice-to-gds. - Running DRC/LVS/PEX — use
mbg-ic-verify. - Debugging a specific placement or routing failure once you already know
which path is active — use
mbg-placement-debug/mbg-routing-debug, which assume this skill's map as background. - Making any code change — this skill is read-only by design; hand findings to whichever owner's skill covers the actual edit.
Required Inputs
- Nothing is strictly required to use the "map the repo" portion.
- For netlist analysis: a SPICE subcircuit netlist string or path.
Preconditions
- Read the actual files before asserting anything about them — module responsibilities and call graphs here can and do change; treat the summaries below as a starting map, not a substitute for grepping the current source.
- Core utilities live under
src/mbg/(see.ai/manifest.jsonproject.core_utilities).
Workflow
1. Trace the active execution path
The live path, confirmed by what design scripts actually import and call
(e.g. AI-Generated-Design-Result/*/run_layout.py,
designs/notebooks/chipathon2026-D/tests/test_all_designs.py), is:
design script
-> mbg.pipeline.spice_to_gds_with_checks(netlist)
-> mbg.pipeline.spice_to_gds(netlist_input, ...) # layout
-> mbg.checks.run_drc / run_lvs / run_pex # verification
spice_to_gds_with_checks is the one entry point design scripts are
expected to call — see AGENTS.md's "Primary Pipeline API" section and
mbg-spice-to-gds.
2. Know there are two distinct pipeline flows — do not conflate them
core/pipeline.py defines two independent SPICE-to-GDS flows that look
similar but use different placement/routing engines underneath:
| Flow | Entry points | Placement | Routing | Used by the live design-script path? |
|---|---|---|---|---|
| Legacy shape-router path | spice_to_gds, spice_to_gds_with_checks_legacy, or spice_to_gds_with_checks(..., legacy=True) |
mbg.placement.placement() |
mbg.routing.auto_router() (fixed I/L/Z/U shape catalogue) |
No, not by default any more. Reachable only via the explicit entry points at left. Kept working for reproducing archived runs. |
| DesignContext path | spice_to_gds_with_checks (the default), spice_to_gds_ctx, spice_to_gds_with_checks_ctx |
mbg.placement_engine.place_with_routability() |
mbg.router.GridRouter (A* grid maze router with rip-up/reroute and internal connectivity verification) |
Yes — spice_to_gds_with_checks now delegates here, so this is what tests/test_all_designs.py and the design scripts exercise. Adds matching groups, symmetry constraints, PinAccessPoint, RoutingFailure, power rails and view emission. |
Both are live code — neither is dead — but they are not interchangeable
and a change to one does not automatically apply to the other. When asked
to fix "the placer" or "the router", first determine which of the two flows
the reporting design script actually used. Note the name no longer tells
you: spice_to_gds_with_checks means the DesignContext path unless the
call passed legacy=True. Archived runs in AI-Generated-Design-Result/
predate the switch and went through the legacy engine, so a bug described in
those logs may live in mbg/routing.py, not mbg/router.py.
3. Separate active from legacy code
core/router.py and core/placement_engine.py document their own relation
to the older modules directly in their module docstrings:
core/routing.pyimplements a shape router (fixed I/L/Z/U wire patterns);core/router.py's docstring states plainly that this is a different algorithm, not an edit to the old one, and thatrouting.auto_routercan delegate to the new engine — but every legacy entry point inrouting.pyis kept working unchanged for existing scripts.core/placement_engine.py's docstring states that the legacymbg.placement.placement()entry point is untouched (aside from a device-width bug fix) so existing scripts keep working, while the new module adds matching/symmetry awareness, routing-channel reservation, and routability feedback.
Practical rule: do not assume a module is dead because a newer one exists beside it. Confirm which design scripts / tests actually import which entry point before treating either as removable.
4. Enumerate devices, nets, and terminals from a netlist
from mbg.spice_parser import parse_netlist_with_pdk, build_design_context
config = parse_netlist_with_pdk(netlist_string, mode="analog")
# config["metadata"]["pdk"] -> "gf180" or "sky130", auto-detected
# from the .lib/.inc line
# config["components"] -> list of dicts; one entry has
# type == "subcircuit" (name + ports),
# the rest have type == "device"
# (name, model, nodes, parameters)
ctx = build_design_context(config, pdk=None) # pdk optional for pure inspection
# ctx.devices -> dict[name -> Device] (kind, terminals, width, length,
# fingers, multipliers, finger_width)
# ctx.nets -> dict[name -> Net] (terminals as (device, terminal)
# pairs, is_power/is_ground/is_critical/is_sensitive)
# ctx.matching_groups -> diff pairs, current mirrors, generic matched sets,
# inferred purely from netlist structure — nothing
# here invents geometry
parse_netlist_with_pdk auto-detects the PDK from .LIB/.INC lines
(SKY130 -> sky130, GF180 -> gf180) and accepts both M1-style and
XM1-style MOSFET instance names. build_design_context additionally
converts total SPICE device width into glayout's expected per-finger width
(finger_width = width / (fingers * multipliers)) — read
core/spice_parser.py's build_design_context docstring before assuming
what it infers versus what it takes literally from the netlist.
Outputs
- A description of which pipeline flow (legacy vs. DesignContext) a given design script or failure actually went through.
- A device/net/terminal inventory for a given netlist, with matching groups and power/ground nets identified.
- A statement of which module is authoritative for a given responsibility, with the specific file and, where useful, line reference that supports the claim.
Failure Modes
- Asserting a call graph without having read the current source — the pipeline has two live flows that are easy to conflate; always confirm which one applies to the case at hand.
- Treating
core/placement.pyorcore/routing.pyas removable dead code without checking who still imports them. - Assuming
parse_netlist_with_pdkvalidates electrical correctness — it only parses syntax and structure; it does not simulate or verify the circuit. - Reporting a "clean" netlist inventory without noting
modeor PDK detection assumptions that shaped the parse.