# Ppa Optimize

> Propose bounded, reversible actuator moves that trade power, performance and area against each other — placement density, clock period, synthesis effort, buffering, floorplan aspect — each with the effect it predicts, the remeasurement that would falsify it, and its rollback. Use when the user says "improve PPA", "close timing", "shrink area", "reduce power", "what should I try next", or when a closure loop needs its next candidate.

- Skill: `vibeic/ppa-optimize` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add vibeic/ppa-optimize`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vibeic/ppa-optimize/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vibeic (https://skillmd.com/u/vibeic)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/vibeic/ppa-optimize

---


# PPA Optimize

## Native Level 3 search

Use `programs/flow_explore.py --ppa-level 3` for native search, or `--ppa` at
the complete public physical entry. It runs the tools' shipped searches and
uses `flow_ppa_handoff` with the ordinary native engine to measure imported
layouts against the original limits. Record the best clean native result as
the Level 3 baseline with its settings, metrics and measured rows. Publish
the Level 2 adoption and use its rows for the exit code. Compare adopted area,
power, setup and hold against the baseline at the same views. Report better,
worse or equal per metric and treat equality as no improvement. Level 4 uses
this baseline as its improvement target. Retain failed and unmeasured arms.
`--native-samples` controls
AutoTuner's own budget. Do not replace a missing runtime with another search
library or install dependencies during product execution. Report that arm as
NOT_MEASURED and continue LibreLane.

Read the actual native corner and extraction reports. In particular, the
shipped ORFS gf180 platform can finish at FF/best RC only. A positive setup
slack there and router DRC0 do not establish nine-view timing or signoff
DRC/LVS. Import the final layout and use the declared PVT/RC views and the
original SDC before selecting it as clean. Keep native area definitions and
power/activity assumptions visible in the comparison.

On GF180, the reference minimum-drive exclusion `*_1` can increase mapped
logic and the automatic floorplan's fill area. Evaluate removing it with
native slew, fanout, clock capacitance and power-grid repair in the same
candidate. Each corner's electrical result decides whether that candidate
can be adopted. Compare final clock and timing-buffer area when the mapped
area improves but power does not. The compact proposals try native CTS
characterization and power recovery with the full electrical checks.

AutoTuner can reject global padding smaller than detailed padding before any
EDA tool runs. Keep those samples as native rejections; do not silently remove
them or add a plugin rule that changes the shipped distribution. A Ray training
iteration is not physical-flow completion; read the native final layout and
reports rather than its iteration counter or sentinel metrics.

LibreLane Optimizing chooses a synthesis strategy and stops at global
placement. Its success does not establish routed PPA or physical signoff.
SynthesisExploration's minimum-area strategy must go through Classic and
native final checks. Do not treat a pre-route best point as the clean baseline.

## The boundary this skill lives inside

This skill produces a **structured proposal**. It never produces a gate
verdict, and it never reports that a move worked. A proposal becomes a result
only when `ppa-measure` re-reads the artefacts afterwards and a deterministic
program — `_ppa/feasibility.py` and `_ppa/pareto.py` per
`docs/PPA_INTERFACES.md` §4 — compares the records.

That ordering is the whole point. The failure mode it prevents is the one that
looks most like success: a model proposes a change, the change is applied, and
the same model reports the improvement it predicted. Nothing in that loop is a
measurement, and the number it produces is indistinguishable from one that is.

Every candidate this skill emits therefore carries four things that make it
falsifiable: the actuator, the predicted effect, the remeasurement that would
refute the prediction, and the rollback.

## When to use

Trigger when the user:
- Has measured PPA and wants the next thing to try
- Is missing a target on one axis and wants to know what it costs on the others
- Needs candidates for a closure controller (`_ppa/closure.py`) to actuate
- Wants the trade-off surface rather than one recommendation

## Inputs to gather

1. The baseline: canonical metric records from `ppa-measure`, with their scope
2. The target: which metric, which threshold, at which scope
3. The actuators that are legal here — some designs forbid touching the RTL,
   some forbid moving the clock period, some allow only PnR configuration
4. The budget: how many tool iterations and how much wall clock the loop may spend
5. What must not regress: the axes that are already at their limit

## Workflow

1. **Pin the baseline scope first.** A proposal that improves a post-place
   number and is checked against a post-route number has not been checked at
   all. State the baseline scope on its own line and require every candidate's
   remeasurement to name the same one.
2. **Enumerate actuators, not outcomes.** "Reduce area 5%" is a wish. "Placement
   density 0.62 to 0.58" is an actuator: it is a thing that can be moved, its
   move can be undone, and the move is visible in a config diff.
3. **Predict, in the units of the metric record.** A prediction in words cannot
   be refuted. A prediction of `+0.05 ns` on `timing.setup.wns_ns` at a named
   scope can be.
4. **Attach the remeasurement.** Name it, with its scope, before the move is
   made. A remeasurement chosen after seeing the result is a different
   experiment from the one that was proposed.
5. **Attach the rollback.** Every candidate states the exact state the design
   returns to. A move with no rollback is not a candidate; it is a commitment,
   and it belongs in a different conversation.
6. **Keep the triple, do not collapse it.** Rank candidates on the frontier over
   power, performance and area. A single weighted score hides which axis paid.
7. **Spend the budget explicitly.** State how many iterations the proposal
   assumes, so a controller can refuse it before it starts rather than halfway.

## Do not

- Do not report an improvement. Report a prediction, and the remeasurement that
  would refute it.
- Do not compare a candidate against a baseline at a different stage, corner,
  mode or activity basis. That comparison is `UNDETERMINED`.
- Compare the native netlist or implementation database before and after optimization. Preserve every unused ECO spare, its keep attributes and the reserved pads; an unintentionally removed spare must be restored.
- Do not propose relaxing a rule deck, waiving a check, or hand-editing a
  layout. An improvement obtained that way is worth less than the number it replaces.
- Do not fill a required field with a placeholder. `X_no_placeholder_fields`
  catches it, and it should: an unfillable rollback field means the candidate is
  not reversible and the honest report of that is a sentence, not a dash.

## Output format

The deliverable is one markdown proposal. The template below is the whole shape.

    # PPA Optimization Proposal — <design>

    Verdict authority: _ppa/feasibility.py - this proposal states no pass/fail of its own.

    ## Summary
    <what is being missed, on which axis, at which scope>

    Baseline scope: post_route_extracted / ss / 1.62 V / 125 C / rc_corner=max
    Budget: 6 PnR iterations, 4 h wall clock

    ## Proposal

    ### C1 — loosen placement density
    Actuator: PL_TARGET_DENSITY 0.62 -> 0.58
    Expected effect: timing.setup.wns_ns +0.04 to +0.07 ns; area.core_um2 +1 to +2%
    Remeasure: run /ppa-measure at post_route_extracted, same scope as baseline
    Rollback: restore config revision 4f21 and re-run PnR from the checkpoint
    Costs: 1 PnR iteration

    ### C2 — raise synthesis effort on the critical module
    Actuator: synthesis effort low -> high, scoped to <module>
    Expected effect: timing.setup.wns_ns +0.02 to +0.05 ns; power.total_mw +0 to +3%
    Remeasure: run /ppa-measure at post_route_extracted, same scope as baseline
    Rollback: restore the previous synthesis script revision
    Costs: 1 synthesis + 1 PnR iteration

    ## Frontier

    | candidate | performance | power | area | dominated by |
    |---|---|---|---|---|
    | C1 | + | 0 | - | none |
    | C2 | + | - | 0 | none |

    ## Evidence

    | artefact | sha256 | tool |
    |---|---|---|
    | phase3/stage3/sta/sta_mcorner_ocv.rpt | sha256:0a5b93f6 | opensta |

    Next: run /ppa-measure

Baseline and candidate numbers travel as canonical records, never as loose
figures in the table above:

Read the requested PPA values from the actual native synthesis, timing, power or physical reports. Name the design scope, corner, units and source paths; an absent measurement remains NOT_MEASURED.

Serialize with `programs/_ppa/canonical_json.py` and nothing else.

## Captured rule

Native electrical closure belongs in the existing bounded PPA proposer, not in
hand-fed margin/grid files. For a template-owned Classic grid with measured EM
overload, derive grid-density scale from the native utilization ratio (next
power of two), snap pitches/landing widths to the actual PDK manufacturing grid,
and retain native spacing/supply ownership. Keep custom and pad-connected grids
unchanged. Pair native grid/slew proposals with existing native CTS options when
the reference still reports fanout violations; never raise that fanout limit or
ignore the clock counter. All original native limits and all-PASS/zero-violation
eligibility, document pins, seed and the 24-trial budget remain unchanged.

Subservient IP, image 0.4.76: fresh main v1.40.75 was 40 PASS / 4 FAIL (EM514,
664.63% worst utilization; final SS slew138/66/192; dependent aggregation). Native
program-generated proposals qualified one zero-counter candidate. Its 33 fresh
rows plus 11 ordinary remaining rows on the same unchanged worker project give
44 PASS / 0 FAIL / 0 NOT_MEASURED, native signoff/compliance counts0: EM0/69.98%,
slew/cap/fanout/route/antenna0, setup+1.671524300ns, hold+0.022734537ns, Magic and
KLayout DRC0, LVS0, final GLS0. The unchanged native comparison marks it eligible.
This is complete candidate qualification, not yet a fresh-main full PPA proof.

The generated settings came from native context: overload scale8, PDK-grid
pitches19.2/19.15um, unchanged1.6um landing width, native slew probe40 and existing
CTS8/100 option. No hand file feeds the chain. Other measured proposals remain
ineligible (including a step-PASS candidate with native fanout1); do not adopt a
partial success. Evidence: `subservient-native-electrical-spool-prepare-i0476-oai`
and its 12 existing worker packets, plus
`subservient-electrical-1-2-2-remaining-native-i0476-oai`. Automatic context reading,
native proposal generation and the existing original-limit selector are the
program-level capture. Remove the obsolete one-off slew JSON instructions.

## Captured rule

### SHA256: a requested gated synthesis arm must include resettable banks

`_ppa.synthesis.strategy_config` pairs a requested clock-gating width with
native `SYNTH_CLOCKGATE_SYNC_RESET=true`. The public Level 2 proposal producer
uses this helper after a successful native synthesis reference has supplied
its strategy. It offers widths 4, 8, and 16 within the existing trial budget.
Either clock-gating setting pinned by the documents suppresses this axis.
Ordinary arms and the reference remain unchanged.

Image 0.4.77 contains LibreLane PR #50's native `clockgate -gate_srst` support.
Fresh SHA256 IC and IP references both pass Step 34 Synthesis. Their public
producer selects a width-4 clock-gating probe. Matched native synthesis changes
512 gated flip-flops and 16 ICGs to 1574 gated flip-flops and 20 ICGs when the
reset-aware option is enabled. Native Liberty qualification selects the ICG.
The matched source tests pass 151 shared cases before and after the change;
the candidate passes 165 cases, with one existing skip and `NEW_FAILED=[]`.

The six IP preparation loops came from Yosys's formal clock-gate matcher
missing fine latch/AND cells. The tool repair is Yosys PR #10. On image
0.4.77 with the qualified Yosys `945506ebf4f4574d9b332923cc51255e7f73b013`,
the unchanged public Step 37 proves the before and reset-aware IP netlists:
1/1 partition each, including one gold-x partition. The stock-image IC
before and after consumers both pass Step 34 and Step 37, with all 1338
equivalence partitions proved, including 50 gold-x partitions. IP synthesis
also passes in both arms. Matched Step 34/37 results give
`native_NEW_FAILED=[]`; these are synthesis/equivalence consumers only.

Unmodified image 0.4.77 still cannot prepare the reset-aware IP proof. Ship
the Yosys repair before relying on this arm's default-image IP eligibility.
The merged tool head additionally retains explicit clock-gate latch init;
the consumer measurements above remain bound to the qualified 945506e
binary. Original post-route feasibility and power checks still apply.
OpenSTA PR #24 is absent from this image, so no new power result is claimed.

### A dense candidate over the supply-grid current-density limit gets the grid its own measurement asks for

A smaller floorplan puts more current on each rail between two straps, so a
candidate can exceed the electromigration limit while the reference does not.
Read the candidate's own report before judging the floorplan: the net, layer,
segment, current and limit per corner. When the grid settings are free, the
remedy is the grid, not the larger floorplan. `flow_explore.explore` does this
after the planned population returns: a trial that is not all-PASS, whose own
worst utilization is above 100 % and whose PPA would beat the best passing
trial, gets one `<name>_grid` trial with `flow_ppa_pdn.capacity_options`
computed from its own measurement. Limits and checks are unchanged and the
first trial stays in the report.

Evidence (SPM hard macro, GF180, stock image 0.4.81, main v1.41.35 plus this
change): the reference grid has one VDD strap (pitch 153.6 um on a 140 um
core) and measures 94.4 %. Every 19,208 um2 candidate measured 112-173 % on
Metal1 at max_ff_n40C_5v50 and failed. With pitch 76.8 um the same candidates
measure 49-66 % and pass all 44 rows; the chain delivers `native_002_grid` at
19,208 um2 instead of 24,937.5 um2.

On GF180 the worst Metal1 link in these reports is 0.23 um wide and lies in a
cell's supply-pin finger, not in the 0.6 um rail, which carries the same
current at about 40 %. The solver joins the rectangles of one pin through
virtual edges, so rail current under a cell is reported on the finger. Until
the tool reports it on the rail, treat a finger-width worst link next to a
rail at a fraction of the limit as this effect, and still let the native
result decide.

## Captured rule — the weakest-drive mask stays in the reference; its area is a search axis

Symptom: the reference trial on GF180 is clean but larger than an allow-`*_1` trial,
which fails only candidate electromigration (and the two aggregation rows after it).

Cause: the reference follows ORFS's gf180 DONT_USE policy (`flow_config.native_excluded_cells`
adds `*_1`). Allowing the minimum-drive cells shrinks the automatic floorplan, and the same
supply grid then carries more current per strap.

Decision and fix: keep the mask in the starting settings (the tool's policy, and the result a
Level 0/1 run delivers must pass on its own); the area is taken by the existing
`allow_min_drive` axis together with the grid follow-up of a trial over the current-density
limit (`flow_explore`, `<name>_grid`). Do not remove the mask from the defaults to win area.

Measured, SPM IP from documents, normal entry, image 0.4.81 (Level 2 report of
`spm-ip-fromdocs-v14135-grid-followup-...-20261112-0738`): reference 24,937.5 µm² core,
11.594 mW, 44/44; allow_min_drive 19,208 µm² (−23.0 %), 11.332 mW, FAIL on
candidate_electromigration; allow_min_drive_grid 19,208 µm², 11.340 mW, 44/44; adopted
native_002_grid 19,208 µm², 11.292 mW, 44/44.

## Captured rule — a synthesis-only area ranking does not choose the strategy

LibreLane's SynthesisExploration ranks strategies by synthesized area and picks the smallest
(AREA 2 on Subservient IP, v1.40.95). After placement, repair and routing that pick can lose:
on SPM IP (same run as above) AREA 2 with the weakest drives allowed ended at 19,914.9 µm²
core (compact_electrical_1_1_grid, 44/44) against 19,208 µm² for the default AREA 0 strategy
with the same cells (allow_min_drive_grid). Keep the synthesis strategy a Level 1/2 search
axis (the AREA 2 proposal) and judge it on the final native rows, not on the synthesis report;
do not make the exploration's pick the default.

## Captured rule — clock gating is a trial, not a default

Width-limited, reset-aware clock gating (`SYNTH_CLOCKGATE_*`, the v1.41.31 axis) only pays where
register switching dominates power. On SPM IP the width-4 gated trial changed total power by
0.0 % (11.594 mW in both, clock_gate_1, 44/44), and the gated native-search points that kept
the reference cell set by −0.1 to +0.2 % (the one gated point at −2.7 % also allowed the
weakest drives, which alone gave −2.3 %: allow_min_drive 11.332 mW). The reference stays ungated; a gated candidate is adopted only when it passes every
row, including netlist equivalence, and wins.

The symptom worth probing is high power from switching register banks; native reset-aware
clock gating can suppress that switching, but its benefit depends on the design. On
Subservient hard macro, sky130A, normal full entry, image 0.4.81, the reference and
`clock_gate_1` both passed 44/44 rows. With AREA 0, width 4 and synchronous-reset gating,
the adopted trial reduced maximum-view power from 2.5645 to 1.7372 mW (−32.3 %),
die area from 33,821.8 to 29,631 µm² (−12.4 %), and core area from 27,781.6 to
24,105.6 µm² (−13.2 %). These are the existing v1.41.32 full-entry measurements,
also recorded by the v1.41.35 repeat. Keep clock gating as the existing search axis;
use the candidate's native power, footprint and original-limit results to decide adoption.

## Captured rule — report what the normal entry delivers against the tools' best, with the die

State the comparison as: the design the normal entry adopts (its Level and settings) against the
best clean result of the tools' own search (Level 3 baseline), per metric, and include the die
area — the macro footprint an integrator places — next to instance area. A smaller instance
area inside the same die is not a smaller macro. The Level 3 report prints the die line as
reported, not scored; the adoption rule is unchanged. On SPM IP the LibreLane best result had a
core of 19,208 µm² inside a 26,360.1 µm² die.


## Captured rule

A fresh PPA trial must retain authored child RTL, benches, reference hooks
and native configuration from each canonical child workspace. Excluding
implementation work must not discard these source inputs. The canonical
child native override is an authored input; overrides inside prior run
folders are runtime outputs. Keep prior native States, run folders and
reports out of the clone; measure the trial from its supplied sources.


## Captured rule

Verify authored child inputs at the public reference and candidate consumers,
including the child's resolved native configuration. A packet or a standalone
clone-helper check does not establish that the public variant path carries
those inputs. Use the same source-copy owner for public variants and native
baselines so their input exclusions cannot diverge.

