docs← Back to article

Markdown for LLMs

Revisit after change

The source Markdown for this article. Copy it into your assistant or download it as a text file.

Download this articlePlain text ↗
# Revisit after change

## Task and place

Revisit asks what a change breaks and what it spares. It sits after release
and replays the pipeline on demand: the act is amended, the model is edited,
or a dependency moves, and the maintainer must diff the structure, re-run the
scenarios, and review every decision and scope line the change touches. A
revisit ends with a fresh verdict on a new version — never a silent patch on
an old one.

## Inputs

- The released candidate with its identity record and its two review opinions.
- The change itself: an amended publication, a model edit, or a moved
  dependency — each named with its date and source.
- The decision records and scope card that may reopen: the filled [EAI tariff decision](/handbook/files/filled/eai-decision-tariff.md), [EAI threshold decision](/handbook/files/filled/eai-decision-threshold.md), and [EAI scope card](/handbook/files/filled/eai-scope-card.md).
- The suite with its recorded tally, which becomes the control panel: every
  check either survives the change or names its impact.

## Actions

- Diff the structure first: which rules, vocabulary lines, pins, and manifest
  entries moved, added, or vanished. One changed line is still a new version.
- Re-run the full suite unchanged and sort the results: surviving checks are
  control cases proving what the change spared; failing checks measure impact.
- Review each decision whose check moved: update the record, the expectation,
  or the rule — then re-run until the suite is green for stated reasons.
- Review the scope card: an amended article may widen or narrow coverage, and
  new paragraphs need new pin lines before any rule cites them.
- Write a revisit note naming the change, the diff, the moved and surviving
  checks, and the reopened decisions, and attach it to the new candidate.

## Decisions

- New version or withdrawn candidate: any model or pin edit mints a new
  version; only a no-op publication refresh keeps the old one, with a note.
- Which failures are impact and which are breakage: impact updates
  expectations through a decision record; breakage fixes the model.
- What stays in scope: the amended article may pull neighboring paragraphs in,
  and the scope card must say so before rules follow.

## Artifact

The artifact is the impact report with its surviving control case plus the
resolved candidate: the named change, the structural diff, the
before-and-after tallies, the checks that survived, the decisions reopened,
the justified new expectations, and the fresh verdict. The [synthetic impact report](/handbook/files/fixtures/amendment/impact-report.md) shows detection on the
source suite; the [revisited candidate](/handbook/files/fixtures/amendment-revisited/README.md) carries the same fictional change through to a new passing
verdict. Both are fictional from end to end, labeled synthetic in every file
they touch.

## EAI example

The running example is the employee accident insurance package: name kz.corpus.employee_accident_insurance, version 0.1.0, language 0.2, zero dependencies, explicit local imports. It covers the employer duty to insure, the twenty-two-class tariff with premium as payroll times rate, payout for capacity loss from thirty through one hundred percent, and penalty as unpaid times 0.015 times days. Sources are pinned to edition EAI_EDITION with materialization PINNED_UNOFFICIAL_COPY — an Adilet API copy retrieved 2026-09-13, sha256 pinned, local copy kept in the package. This paragraph describes the source snapshot — the frozen before-state, payroll base and all; the accepted candidate reads the insured sum instead (finding EAI-R3). The static check reports OK and all seven checks pass: loss thirty established against loss twenty-nine undecided, class twenty-two premium of 29600 KZT on a payroll of one million, penalty of 3000 KZT on one hundred thousand unpaid for two days. The premium check trips EAI-D1, the boundary pair trips EAI-D2, the exact penalty trips EAI-D3.

The worked change is SYNTHETIC and fictional: in the [amendment copy](/handbook/files/fixtures/amendment/08-17-19-core.law) the class twenty-two rate moves
from 2.96 to 3.10 percent. No act was amended; the label on the changed rule
says synthetic, and the real package is untouched. Structural diff: one rule
line — the rate literal plus the label, which the fixture swaps for the
synthetic marker (every other shared file is a byte-identical copy; the fixture only adds its impact report and omits the publisher JSON).

```diff
-rule TariffClass22(e: Employer) strict { when professional_risk_class(e, 22); then insurance_tariff(e, 0.0296); label ru-KZ official "..."; }
+rule TariffClass22(e: Employer) strict { when professional_risk_class(e, 22); then insurance_tariff(e, 0.0310); label en unofficial "SYNTHETIC ..."; }
```

Re-run impact: the class twenty-two premium check fails — the expected 29600
KZT no longer derives — while the loss-thirty payout check survives as the
control case, alongside the employer duty, the boundary silence, the penalty,
and both property checks. Decision impact: EAI-D1 reopens with the rate, while
EAI-D2 and EAI-D3 stand untouched with green checks on both sides. Scope is
unchanged: the same branches stay covered.

The completed half replays the same fictional flip against the accepted
candidate: thirty-four of thirty-seven, exactly the three class-22 checks
failing (core premium, tariff row, sum-distinguishes). EAI-D1 reopens; the
new expectations are derived, not copied from the run — 0.0310 times the
same million is 31,000 KZT, times the doubled sum 62,000 KZT — and all three
class-22 checks move citing the reopened record. The [revisited candidate](/handbook/files/fixtures/amendment-revisited/README.md) then passes thirty-seven of
thirty-seven with snapshot id 02469c81… and an accept-synthetic verdict whose
first limit is that the amendment is fiction.

## Pitfall

Updating expectations to match the new run without a decision record. A
changed rate legitimately moves the expected premium — but only a reopened
EAI-D1 makes that move principled rather than cosmetic. The rule is simple:
every moved expectation cites the decision that moved it, or it does not move.
A second trap is forgetting the control cases: passing checks are not noise,
they are the proof the change spared them. Name at least one surviving control
case in every impact report.

## Verify

The stage is done when the before-and-after tallies are recorded with the tool
version. Observed runs with tool version `law` 0.1.0, semantics law.core/0.2,
on the amendment copy. Before the edit, seven of seven pass:

```sh
$ law test docs/handbook/files/fixtures/amendment
```

```text
итого: 7 проверено, 7 прошли, 0 не прошли, 0 не исполнены; код 0
```

[translation] The summary reads: seven checked, seven passed, zero failed, zero unexecuted, exit code zero.

After the one-line edit, the static check still reports OK but the tariff
check fails:

```sh
$ law engine check docs/handbook/files/fixtures/amendment
check OK: docs/handbook/files/fixtures/amendment
$ law test docs/handbook/files/fixtures/amendment
```

```text
  ok   [kz.corpus.employee_accident_insurance#authored] tests/core.lawtest / EAI-EMPLOYER-MUST-INSURE
  FAIL [kz.corpus.employee_accident_insurance#authored] tests/core.lawtest / EAI-MINING-CLASS-22-PREMIUM
        truth_status == TRUE_ONLY: в документе NEITHER
  ok   [kz.corpus.employee_accident_insurance#authored] tests/core.lawtest / EAI-LOSS-THIRTY-QUALIFIES
  ok   [kz.corpus.employee_accident_insurance#authored] tests/core.lawtest / EAI-LOSS-TWENTY-NINE-IS-NOT-INSURER-PAYOUT
  ok   [kz.corpus.employee_accident_insurance#authored] tests/core.lawtest / EAI-SPECIAL-LATE-PAYMENT-PENALTY
  ok   [kz.corpus.employee_accident_insurance#authored] tests/goals.lawtest / GoalEstablishedCapacityLossHasPayout-world
  ok   [kz.corpus.employee_accident_insurance#authored] tests/goals.lawtest / urn:kz:corpus:clir:employee-accident-insurance#GoalEstablishedCapacityLossHasPayout
итого: 7 проверено, 6 прошли, 1 не прошли, 0 не исполнены; код 1
```

[translation] The premium check fails: expected established, the document holds neither. The summary reads: seven checked, six passed, one failed, zero unexecuted, exit code one.

Criterion: the before tally is seven of seven, the after tally is six of
seven with exactly the tariff check failing, and the loss-thirty check stands
as the named surviving control case. The full story lives in the [synthetic impact report](/handbook/files/fixtures/amendment/impact-report.md), and its
completion — derived 31000/62000 expectations, thirty-seven of thirty-seven,
new snapshot id, fresh verdict — in the [revisited candidate](/handbook/files/fixtures/amendment-revisited/README.md). A revisit that ends at detection has done
half the stage; the stage ends at the new verdict.

## Limits

A revisit proves only what the suite probes: an amendment outside every
check's reach passes silently, which is why amended articles outside scope
still deserve a reading. The synthetic demo moves one literal in one rule; a
real amendment may renumber articles, split paragraphs, or shift meaning
across rules, and each of those needs fresh pins before fresh rules. Fixture
copies also freeze the world they copy: the amendment copy pins the same
September source bytes, so it demonstrates method, not current law.

One naming note: the study snapshots share package version 0.1.0 in their
manifests and differ by content — the candidate id 7635d197… versus the
revisited id 02469c81… — because no snapshot here is a publication. The
mint-a-new-version rule above applies when a candidate is published; inside
the study sequence, the snapshot id is the version.

## Next step

Continue with the [End-to-end worked example](/handbook/worked-example/), which replays the whole pipeline against the running example in one story.

## Sources

- [Accept and release](/handbook/accept-release/) — the candidate and identity this revisit reopens.
- [Recording decisions](/handbook/decisions/) — reopening EAI-D1 with reasons.
- [Writing scenarios](/handbook/scenarios/) — the control panel of surviving checks.
- [Command line](/cli/) — the check and test commands used above.
- [Diagnostics](/diagnostics/) — reading refusals and warnings.

For dependent packages, continue with [change impact](/corpus/changes/impact/) and [upgrades and replay](/corpus/releases/replay-and-upgrades/).