git:20260825.9926828 to git:20260825.cef276d

---

name: ppa-measure

description: Read PPA artefacts that the tools already wrote — STA reports, power reports, area reports, DEF/GDS summaries — and turn them into an evidence-linked measurement report of canonical `vibeic.ppa.metric.v1` records, each carrying its scope and its source hash. Use when the user says "measure PPA", "what is the real area/power/timing", "collect the PPA numbers", "post-route PPA", or when a report must state what was measured AND what was not.

---

# PPA Measure

## The boundary this skill lives inside

This skill produces an **evidence-linked report**. It never produces a

gate verdict, and no part of it asks the model to settle whether the design is

good enough. The pass/fail call belongs to a deterministic program —

`_ppa/feasibility.py` per `docs/PPA_INTERFACES.md` §4 — and this report only

supplies the records that program consumes.

Concretely, this skill may say *"setup WNS is -0.124 ns at the `ss` corner,

parsed from `<file>` whose sha256 is `<hash>`"*. It may not say what that number

means for the release. If a caller wants the release answer, the handoff is the

gate program, and the report says so on its own `Verdict authority:` line.

The reason for the split is not tidiness. A number that a model produced and a

number a parser produced look identical once they are in a table, and only one

of them can be re-derived from an artefact. Keeping the verdict in a program

keeps the re-derivable half load-bearing.

## When to use

Trigger when the user:

- Has finished a synthesis / PnR / STA / power run and wants the numbers collected

- Asks what the design's real post-route PPA is, as opposed to an early estimate

- Needs the inputs a feasibility gate or a Pareto comparison will read

- Needs an honest statement of PPA coverage — which metrics exist and which do not

**Not** this skill: an early, pre-synthesis guess. That is `ppa-predict`, and the

two must never be mixed in one table. A `ppa-predict` number carries status

`ESTIMATED`, which `docs/PPA_INTERFACES.md` §2 forbids from ever entering final

PPA; a `ppa-measure` number carries status `MEASURED` and a source hash.

## Inputs to gather

1. The design / run directory, and which stage it reached (synthesis, post-place,

post-route, post-route-extracted)

2. The artefacts themselves: STA report(s), power report(s), area report, DEF or

GDS summary — by path, one per view

3. The analysis views actually run: process corner, voltage, temperature, RC

corner, clock, check type

4. The activity basis for any power number: vectorless, or a named VCD/SAIF

5. Whether an extracted-parasitics run exists, or only the pre-extraction estimate

If an input is absent, that absence is a result. Record it as `NOT_MEASURED`

with a `reason`; do not substitute a value from a different stage and do not

leave the row out.

## Workflow

1. **Enumerate the views before reading any number.** Write down the list of

(stage, mode, process, voltage, temperature, rc_corner, clock, check) tuples

the run was supposed to cover. This list is the denominator; without it a

report of three green rows cannot be told apart from a run that only produced

three rows.

2. **Parse, never recompute.** Each number is lifted from an artefact by a parser

and hashed as parsed. A number you arrived at by arithmetic is `DERIVED` and

must carry its formula alongside; a number you arrived at by judgement is not

a measurement at all and does not belong in the table.

3. **Bind every record to its source.** `source.path`, `source.sha256`,

`source.tool`, `source.parser`. A record without a resolvable source is

`INVALID`, not `MEASURED`.

4. **Keep the taxonomy split.** Synthesis area and post-route area are different

metrics, not two samples of one. Vectorless power and VCD power are different

metrics. Pre-extraction and post-extraction timing are different metrics.

Collapsing them is the single most common way a PPA table becomes a fiction.

5. **Emit the coverage line.** Count `MEASURED`, `NOT_MEASURED`,

`NOT_APPLICABLE`. An unstated denominator is how "we measured everything"

and "we measured what happened to be lying around" print the same page.

6. **Generate the report from the records — do not typeset it.** The markdown

below is emitted by `programs/ppa_report_gen.py`, which reads the records and

writes both the human page and the `claims.json` that binds every sentence in

it to the artefact behind it. See the next section.

7. **Hand off.** Name the program that will read these records and state that the

verdict is its output, not this document's.

## The report is generated, and then it is checked

```bash

# records (file or directory of vibeic.ppa.metric.v1) -> page + claims

python3 plugins/vibe-ic/programs/ppa_report_gen.py <records.json|records_dir> \

--out reports/ppa/report.md --claims reports/ppa/claims.json \

--json reports/ppa/report_run.json

# the page may not say more than the claims support

python3 plugins/vibe-ic/programs/ppa_page_claim_check.py reports/ppa/report.md \

--claims reports/ppa/claims.json --cite-numbers

```

**Why a generator and not a template.** A report is the last place a number is

touched before a human believes it, and a sentence carries implications an

artefact does not. `ppa_report_gen` is a gate, not a formatter:

| rc | meaning |

|---|---|

| 0 | the page and `claims.json` were written |

| 1 | `[REFUSE]` — a record cannot support the sentence it would become: a `NOT_MEASURED` carrying a `value`, a numeric sentinel (`0` / `-1` / `""`) standing in for "not measured", a collapsed single PPA score, or two records producing one claim id from different facts |

| 2 | `[CANNOT CHECK] NO_INPUT` (the path is not readable) or `EMPTY_CORPUS` (the path is there and holds no record — the zero is STATED, with the path it counted) |

An rc=1 is not a formatting problem to route around by writing the page by

hand. It is the generator naming a record you must fix upstream, in step 2 or

step 3.

**`claims.json` is the runnable half of the prose.** Every sentence a reader

will believe carries `[claim:<id>]`, and each claim names the artefact path and

hash that supports it. `ppa_page_claim_check --cite-numbers` then re-runs the

page every landing: a claim whose status outruns its weakest cited evidence, a

citation that resolves to nothing, and a sentence stating a number with no

citation are each rc=1. Prose cannot be re-read every landing; a citation can.

Pass the records path the way it should appear in the published page — the

generator quotes the path it was given, so a `/tmp/...` argument puts an

absolute machine-local path into the artefact and trips this skill's

`X_no_volatile_paths` cross-check.

The `NOT_MEASURED` rows are printed by the generator, with their `reason`,

never dropped. That is the same rule as step 5 and the "Do not" list below,

enforced once in a program instead of remembered three times.

## Do not

- Do not write `0`, `-1` or an empty string to mean "not measured". There are no

numeric sentinels; there is a status field and it is `NOT_MEASURED` with a reason.

- Do not omit a row because it has no number. A missing row and a measured zero

are different facts and a reader cannot tell them apart after the fact.

- Do not compare two numbers whose `scope` differs. That comparison is

`UNDETERMINED`; it does not have a winner.

- Do not carry a `ppa-predict` estimate into this report, in any column, under

any heading.

- Do not restate a program's exit code as your own conclusion. Quote it with its

program name and its rc.

- Do not hand-write the report page when `ppa_report_gen` refuses your records.

The refusal is about a record, and typing the page yourself publishes exactly

the sentence the refusal was protecting a reader from.

- Do not report a number whose artefact you could not open. "I could not read it"

and "I read it and it was empty" are different results and must print differently.

## Output format

The deliverable is one markdown report. The template below is the whole shape;

`<...>` are the parts you fill in.

# PPA Measurement — <design> @ <stage>

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

## Summary

<two or three sentences: which stage, which views were run, what is absent>

Coverage: MEASURED=7 NOT_MEASURED=2 NOT_APPLICABLE=1

## Measurements

| metric | status | value | unit | stage | corner | source sha256 |

|---|---|---|---|---|---|---|

| timing.setup.wns_ns | MEASURED | -0.124 | ns | post_route_extracted | ss/1.62V/125C | sha256:3f9a1c7d |

| power.total_mw | NOT_MEASURED | - | - | post_route_extracted | - | - |

## Not measured, and why

| metric | reason |

|---|---|

| power.total_mw | no activity basis: neither a vectorless run nor a VCD exists |

## Evidence

| artefact | sha256 | tool |

|---|---|---|

| phase3/stage3/sta/sta_mcorner_ocv.rpt | sha256:b204e8a1 | opensta |

Next: run /ppa-diagnose

Every row of `## Measurements` is the human view of one canonical record. The

records themselves are the machine deliverable and go in the report's JSON

sidecar, one per row, in the frozen shape:

```json

{

"schema": "vibeic.ppa.metric.v1",

"metric": "timing.setup.wns_ns",

"status": "MEASURED",

"value": -0.124,

"unit": "ns",

"scope": {"stage": "post_route_extracted", "mode": "functional",

"process": "ss", "voltage_v": 1.62, "temperature_c": 125,

"rc_corner": "max", "clock": "clk", "check": "setup"},

"source": {"path": "phase3/stage3/sta/sta_mcorner_ocv.rpt",

"sha256": "sha256:77c1de40", "tool": "opensta",

"parser": "ppa_metric_extract.py"}

}

```

Serialize with `programs/_ppa/canonical_json.py` and nothing else — sorted keys,

no spaces, UTF-8, no NaN. A hash taken over a hand-rolled `json.dumps` is a hash

of a different document than the one the next reader will re-serialize.

## Compliance gate (mandatory)

After producing your output, save it to a file and run:

```bash

python3 plugins/vibe-ic/_shared/skill_compliance_check.py \

--requirements plugins/vibe-ic/skills/ppa-measure/compliance.yaml \

<your_output_file>

```

Exit 0 = PASS, exit 1 = FAIL with specific missing elements listed, exit 2 =

the checker could not read one of its own inputs and reached no conclusion.

`compliance.yaml` in this skill directory enumerates every required element of

your output, and its `X_verdict_boundary` cross-check is what stops this report

from drifting into being a gate.

**Your task is not complete until the audit returns PASS.** Missing elements are

the single largest source of skill-execution non-determinism across agents.