Markdown for LLMs
Technical review
The source Markdown for this article. Copy it into your assistant or download it as a text file.
# Technical review ## Task and place Technical review asks whether the package is soundly built, whatever it means. It sits after semantic review: meaning has been checked against the pinned source, and now structure, pins, dependencies, suites, and reproducibility get their own pass. The reviewer runs the tooling, reads the manifests, and records an engineering opinion on the exact version in front of them. ## Inputs - The package directory with its manifest, lock file, model files, suites, and pinned source bytes. - The semantic opinion with its scope, so technical findings do not reopen meaning: the filled [EAI review record](/handbook/files/filled/eai-review-agent.md), the [candidate review record](/handbook/files/filled/eai-review-candidate.md), and the [R3 review record](/handbook/files/filled/eai-review-candidate-r3.md). - The decision records behind the suite expectations: the filled [EAI tariff decision](/handbook/files/filled/eai-decision-tariff.md), [EAI threshold decision](/handbook/files/filled/eai-decision-threshold.md), and [EAI penalty decision](/handbook/files/filled/eai-decision-penalty.md). - The [review record template](/handbook/files/templates/review-record.md), reused for the engineering opinion. ## Actions - Read the manifest: package name, version, language line, namespace, declared suites with their worlds, and the explicit-imports marker. - Read the lock file: dependency edges must match the manifest claim — empty for a zero-dependency package — and the root identity must name the same package and version. - Confirm every pinned publication resolves: the local bytes exist and their hash matches the pin. A renamed or edited source file fails here. - Run the static check, the full suite, and the pin comparison, and record the tool version with each result. - Reproduce from a fresh copy: copy the directory, rerun the same commands, and confirm identical results before writing the opinion. ## Decisions - Which findings block acceptance and which travel as notes: a broken pin or a failing check blocks; a style remark does not. - How much of the dependency closure to recheck: for a zero-dependency package the closure is the package itself, stated in one line. - Whether the suites earn trust: small named suites with fixed expectations count; expectations edited to match observed runs do not. ## Artifact The artifact is the engineering opinion on the exact version reviewed: the manifest and lock readings, the three recorded runs with the tool version, and a verdict per engineering aspect. For the running example the opinion covers the candidate snapshot only — any later edit needs a fresh pass, however small. ## 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 base as insured sum times rate plus the minimum floor, 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. The static check reports OK and all thirty-seven candidate checks pass: loss thirty established against twenty-nine undecided, loss one hundred established against one hundred one undecided, per-row tariff premiums on an insured sum of one million, premium 59200 on a doubled sum against payroll one million, penalty of 3000 KZT on round figures and exactly 1.5 KZT on the fractional probe. The per-row tariff checks trip EAI-D1, the two boundary pairs trip EAI-D2, the fractional probe trips EAI-D3, the three premium-base probes trip EAI-D4. Structure reading: four model files (vocabulary, sources, core rules, the R1 fix), seven suite files with thirty-seven checks in one family, a lock file with empty dependency edges and empty package list, and the pinned Russian source bytes beside the publication record. The manifest declares suites over a single world matching the package name, and the authoring marker selects explicit local imports. ## Pitfall Trusting a green suite without reading the lock file. A suite can pass while the manifest claims suites that never run, or while the lock file names dependencies the manifest forgot. Read both files line by line: suite lists, worlds, edges, and the root identity. A second trap is reviewing a dirty directory — uncommitted edits make the opinion describe a version nobody can reconstruct. List what changed before running anything, and record the exact version in the opinion. ## Verify The stage is done when the three runs are recorded with the tool version. Observed runs on the accepted candidate with the pinned tool (`law` 0.1.0, semantics law.core/0.2, published build): ```sh $ law engine check docs/handbook/files/fixtures/eai-candidate check OK: docs/handbook/files/fixtures/eai-candidate $ law test docs/handbook/files/fixtures/eai-candidate ``` ```text ok [kz.corpus.employee_accident_insurance#authored] tests/tariff.lawtest / EAI-TARIFF-CLASS-01-PREMIUM ... ok [kz.corpus.employee_accident_insurance#authored] tests/penalty-fractional.lawtest / EAI-PENALTY-FRACTIONAL-EXACT total: 37 checked, 37 passed, 0 failed, 0 not run; code 0 ``` A fresh copy of the candidate reproduces the tally exactly (thirty-seven of thirty-seven, same build), and the local 0.1.0 build agrees. The pin comparison runs on the local build only — the published build has no `gen` command: ```sh $ law gen pinning docs/handbook/files/fixtures/eai-candidate --check ``` The pin comparison prints nothing and exits zero: every pin holds. Criterion: the static check reports OK, all thirty-seven lines read ok with both boundary pairs disagreeing in the expected direction, and the pin comparison exits zero without naming any drift. A fourth honest data point comes from this handbook's own fixture work: a copy missing its lock file is refused with LDC-E1104, and a copy missing its pinned source bytes is refused with LDC-E5204 — both refusals observed, both proving the tooling reads the files it claims to read. ## Limits A technical review says nothing about meaning: pins can hold and suites can pass while a whole branch of the act stays unmodeled — that was finding EAI-R1, caught only by semantic review. It also covers one snapshot on one tool release: a new tool release or a single edited line reopens the opinion. The EAI opinion names the candidate snapshot id and tool release 0.1.0 together, so a later reader knows exactly what was deemed sound. ## Next step Continue with [Accept and release](/handbook/accept-release/), which turns the two review opinions into a release decision with a recorded identity. ## Sources - [Semantic review](/handbook/semantic-review/) — the meaning pass this stage follows. - [Pinning editions](/handbook/pin-editions/) — how pins are made and compared. - [Reuse and dependencies](/handbook/reuse-dependencies/) — reading the lock file. - [Command line](/cli/) — the check, test, and pinning commands used above. - [Diagnostics](/diagnostics/) — reading refusals such as LDC-E1104 and LDC-E5204.