PPA Distill
The boundary this skill lives inside
This skill produces a structured case record and a draft rule. It never
produces a gate verdict, and it never promotes its own case. The lifecycle from
RAW to PROGRAMMED is owned by _ppa/distillation.py per
docs/PPA_INTERFACES.md §4, and every rung of that ladder is a program's
decision made against evidence this document supplies.
The failure this guards against is the one that makes a plugin worse the harder
it is used: a fix that worked once on one design gets written down as a rule,
the rule fires on a design it was never true for, and the fix is now a defect
that arrives with authority. The fingerprint is what stops that. A case that
cannot say which designs it applies to has not been distilled; it has been
remembered.
The draft rule is the point of the exercise. A case that stays prose is a case a
future author has to remember; a case that becomes a deterministic rule is one
nobody has to. Write the rule as something a program could execute, even while
the case is still RAW and nothing may execute it yet.
When to use
Trigger when:
- A closure or recovery loop reached a result the deterministic path did not
- A diagnosis found a cause that the program-first diagnosis missed
- The same fix has now been applied on more than one design
- Someone asks for a case to be promoted a rung
Inputs to gather
- What failed, in metric terms and with scope — not "timing was bad"
- What the deterministic path did, and where it stopped
- What the judgement step did that changed the outcome
- The before and after metric records, at matched scope
- Everything about the design that might be why this worked: PDK, clock domain
count, macro count, utilization, hierarchy depth, the flow and its version
Workflow
- Write the case before writing the rule. The case is what happened; the
rule is what should happen next time. Deriving the second without recording
the first produces a rule nobody can re-check.
- Bind the case to evidence. Before and after records, with source hashes.
A case whose improvement cannot be re-derived from artefacts is a story.
- Fingerprint the design, deliberately over-narrow. List everything that
might matter, including things you doubt. A fingerprint that is too narrow
costs a missed reuse; one that is too broad costs a wrong rule firing on a
design nobody checked. The costs are not symmetric.
- State the promotion criteria as a countable condition. "Once we trust it"
is not a criterion. "Reproduced on three designs with differing fingerprints,
with no counter-example" is.
- Draft the rule as a program would run it. Its input, its condition, its
action, and the observation that would refute it. If you cannot write the
condition, the case is not ready to be a rule and says so.
- Record the counter-examples too. A design where this was tried and did not
help is the most valuable row in the case, and it is the one that never gets
written down.
Do not
- Do not promote the case here.
Lifecycle: records the rung it is on; the
program moves it.
- Do not write a rule keyed on a design name, a chip name, a project name or any
other identifier of one particular design. A rule that recognizes the design it
was derived from is a lookup table, and it makes every benchmark number that
touches it meaningless.
- Do not distil a case whose improvement was never remeasured at matched scope.
- Do not omit the counter-examples, and do not soften them into caveats.
- Do not record a case as evidence for itself. The before and after records come
from
ppa-measure, not from this document.
Output format
The deliverable is one markdown case record. The template below is the whole shape.
# PPA Case — <one line, what was recovered>
Verdict authority: _ppa/distillation.py - this record promotes nothing itself.
## Summary
<what the deterministic path could not do, and what judgement did instead>
Lifecycle: RAW
Design fingerprint: pdk=gf180mcuD, clock_domains=1, macros=0,
utilization=0.62, hierarchy_depth=4, flow=orfs, flow_version=<v>
## Case
Read the actual native path or metric breakdown and record the engineering hypothesis and measured effect of its fix. The retired diagnostic router supplies no current result.
## Counter-examples
| design fingerprint | outcome | artefact |
|---|---|---|
| pdk=gf180mcuD, macros=3 | no improvement; congestion dominated | sha256:77c1de40 |
## Programmed rule draft
Input: the failing-endpoint list from the STA path report
Condition: at least 70% of failing endpoints share one net AND that net's
fanout exceeds the technology buffering threshold
Action: emit a buffering candidate for that net as a ppa-optimize actuator
Refuted by: a run where the condition held and buffering did not improve WNS
Promotion criteria: reproduced on 3 designs with differing fingerprints, with
the counter-example table showing no unexplained failure
## Evidence
| artefact | sha256 | tool |
|---|---|---|
| phase3/stage3/sta/paths.rpt | sha256:0a5b93f6 | opensta |
Next: run /ppa-benchmark
1---2name: ppa-distill3description: Turn a PPA recovery that worked into a case with evidence, a design fingerprint that bounds where it may be reused, and a draft of the deterministic rule it should eventually become. Use when the user says "capture this", "we should remember this fix", "distill the lesson", "promote this case", or after any closure loop where judgement recovered a result a program could not.4metadata:5 source: https://skillmd.com/skills/vibeic/ppa-distill6---78# PPA Distill910## The boundary this skill lives inside1112This skill produces a **structured case record and a draft rule**. It never13produces a gate verdict, and it never promotes its own case. The lifecycle from14`RAW` to `PROGRAMMED` is owned by `_ppa/distillation.py` per15`docs/PPA_INTERFACES.md` §4, and every rung of that ladder is a program's16decision made against evidence this document supplies.1718The failure this guards against is the one that makes a plugin worse the harder19it is used: a fix that worked once on one design gets written down as a rule,20the rule fires on a design it was never true for, and the fix is now a defect21that arrives with authority. The fingerprint is what stops that. A case that22cannot say which designs it applies to has not been distilled; it has been23remembered.2425The draft rule is the point of the exercise. A case that stays prose is a case a26future author has to remember; a case that becomes a deterministic rule is one27nobody has to. Write the rule as something a program could execute, even while28the case is still `RAW` and nothing may execute it yet.2930## When to use3132Trigger when:33- A closure or recovery loop reached a result the deterministic path did not34- A diagnosis found a cause that the program-first diagnosis missed35- The same fix has now been applied on more than one design36- Someone asks for a case to be promoted a rung3738## Inputs to gather39401. What failed, in metric terms and with scope — not "timing was bad"412. What the deterministic path did, and where it stopped423. What the judgement step did that changed the outcome434. The before and after metric records, at matched scope445. Everything about the design that might be why this worked: PDK, clock domain45 count, macro count, utilization, hierarchy depth, the flow and its version4647## Workflow48491. **Write the case before writing the rule.** The case is what happened; the50 rule is what should happen next time. Deriving the second without recording51 the first produces a rule nobody can re-check.522. **Bind the case to evidence.** Before and after records, with source hashes.53 A case whose improvement cannot be re-derived from artefacts is a story.543. **Fingerprint the design, deliberately over-narrow.** List everything that55 might matter, including things you doubt. A fingerprint that is too narrow56 costs a missed reuse; one that is too broad costs a wrong rule firing on a57 design nobody checked. The costs are not symmetric.584. **State the promotion criteria as a countable condition.** "Once we trust it"59 is not a criterion. "Reproduced on three designs with differing fingerprints,60 with no counter-example" is.615. **Draft the rule as a program would run it.** Its input, its condition, its62 action, and the observation that would refute it. If you cannot write the63 condition, the case is not ready to be a rule and says so.646. **Record the counter-examples too.** A design where this was tried and did not65 help is the most valuable row in the case, and it is the one that never gets66 written down.6768## Do not6970- Do not promote the case here. `Lifecycle:` records the rung it is on; the71 program moves it.72- Do not write a rule keyed on a design name, a chip name, a project name or any73 other identifier of one particular design. A rule that recognizes the design it74 was derived from is a lookup table, and it makes every benchmark number that75 touches it meaningless.76- Do not distil a case whose improvement was never remeasured at matched scope.77- Do not omit the counter-examples, and do not soften them into caveats.78- Do not record a case as evidence for itself. The before and after records come79 from `ppa-measure`, not from this document.8081## Output format8283The deliverable is one markdown case record. The template below is the whole shape.8485 # PPA Case — <one line, what was recovered>8687 Verdict authority: _ppa/distillation.py - this record promotes nothing itself.8889 ## Summary90 <what the deterministic path could not do, and what judgement did instead>9192 Lifecycle: RAW93 Design fingerprint: pdk=gf180mcuD, clock_domains=1, macros=0,94 utilization=0.62, hierarchy_depth=4, flow=orfs, flow_version=<v>9596 ## Case9798Read the actual native path or metric breakdown and record the engineering hypothesis and measured effect of its fix. The retired diagnostic router supplies no current result.99100 ## Counter-examples101102 | design fingerprint | outcome | artefact |103 |---|---|---|104 | pdk=gf180mcuD, macros=3 | no improvement; congestion dominated | sha256:77c1de40 |105106 ## Programmed rule draft107108 Input: the failing-endpoint list from the STA path report109 Condition: at least 70% of failing endpoints share one net AND that net's110 fanout exceeds the technology buffering threshold111 Action: emit a buffering candidate for that net as a ppa-optimize actuator112 Refuted by: a run where the condition held and buffering did not improve WNS113 Promotion criteria: reproduced on 3 designs with differing fingerprints, with114 the counter-example table showing no unexplained failure115116 ## Evidence117118 | artefact | sha256 | tool |119 |---|---|---|120 | phase3/stage3/sta/paths.rpt | sha256:0a5b93f6 | opensta |121122 Next: run /ppa-benchmark