Markdown for LLMs
Author and reviewer handbook
The source Markdown for this article. Copy it into your assistant or download it as a text file.
# Author and reviewer handbook ## Task and place This handbook turns a normative act into a canon package that a machine can check and run: pinned sources, explicit rules, scenarios with expected answers, and review records. It sits between learning and lookup. The tutorials teach the language on small fictional examples; the reference defines each construct and each diagnostic; this handbook covers the working method for real acts — what to do, in which order, and what to hand over. The site around this handbook divides the labor: [Tutorials](/tutorials/) for learning, the [language reference](/constructs/) for lookup, [Build](/build/) for running the tooling, [Agents](/agent-engineering/) for machine-assisted drafting. This handbook is the method layer between them. It sends you to Tutorials to learn, to the reference to look up, to Build to run, and to Agents for drafting help; finished canon packages themselves live in the corpus tree of the repository. ## Inputs Three roles read this handbook: - Author — models the act and writes scenarios. - Reviewer — checks the model against the pinned sources and records findings. - Maintainer — releases the package and revisits it when the act changes. You bring the act text (or a pointer to it), a working `law` tool, and the question the package must answer. You do not need a finished model; scope comes before modeling. ## Reproduce it first Every run quoted on these pages replays from one download — the accepted candidate, the source snapshot, all drills, all records, and the checker: - Download the [handbook bundle](/handbook/handbook-bundle.zip) (fifteen-file candidate inside; per-file hashes in [MANIFEST.json](/handbook/MANIFEST.json)). - Install the pinned tool: `npm i -g @arxo/cli@0.1.0`, then confirm `law version` reads `law 0.1.0` with `semantics: law.core/0.2`. - Verify identity: recompute the candidate snapshot id per the [accept page](/handbook/accept-release/) and expect `7635d197…`. - Run: `law engine check eai-candidate` then `law test eai-candidate` — expect `check OK` and thirty-seven of thirty-seven. The bundle's README carries the full runs table with every expected tally. ## Actions Five reading routes cross the same pages; pick yours. Each route lists its pages in order and the artifact it ends with: - Route A — first package end to end: [workflow](/handbook/workflow/) → [scope](/handbook/scope/) → [acquire](/handbook/acquire-source/) → [pin](/handbook/pin-editions/) → [inventory](/handbook/inventory/) → [vocabulary](/handbook/vocabulary/) → [constructs](/handbook/constructs/) → [decisions](/handbook/decisions/) → [absence](/handbook/absence-negation-conflict/) → [readings](/handbook/interpretations-judgment/) → [evidence](/handbook/evidence-admission/) → [time](/handbook/time-calendars/) → [calculations](/handbook/calculations-external-inputs/) → [reuse](/handbook/reuse-dependencies/) → [scenarios](/handbook/scenarios/) → [properties](/handbook/properties-mutations/) → [workbench](/handbook/draft-workbench/) → [coverage](/handbook/coverage-quality/) → [semantic review](/handbook/semantic-review/) → [technical review](/handbook/technical-review/) → [accept](/handbook/accept-release/) → [revisit](/handbook/revisit-after-change/). Ends with the [worked example](/handbook/worked-example/): the assembled dossier of a released package. - Route B — scope and sources, for analysts who fix what is covered before any rule is written: [workflow](/handbook/workflow/) → [scope](/handbook/scope/) → [acquire](/handbook/acquire-source/) → [pin](/handbook/pin-editions/) → [inventory](/handbook/inventory/). Ends with a filled scope card and source inventory, no rules yet. - Route C — modeling rules, for authors who turn pinned provisions into strict rules: [workflow](/handbook/workflow/) → [vocabulary](/handbook/vocabulary/) → [constructs](/handbook/constructs/) → [decisions](/handbook/decisions/) → [absence](/handbook/absence-negation-conflict/) → [readings](/handbook/interpretations-judgment/) → [time](/handbook/time-calendars/) → [calculations](/handbook/calculations-external-inputs/) → [reuse](/handbook/reuse-dependencies/). Ends with rules plus decision records for every close call. - Route D — scenarios and review, for reviewers who probe answers and record findings: [workflow](/handbook/workflow/) → [scenarios](/handbook/scenarios/) → [properties](/handbook/properties-mutations/) → [coverage](/handbook/coverage-quality/) → [semantic review](/handbook/semantic-review/) → [technical review](/handbook/technical-review/). Ends with a suite plus a review record carrying findings. - Route E — release and revisit, for maintainers who publish and track later change: [workflow](/handbook/workflow/) → [workbench](/handbook/draft-workbench/) → [accept](/handbook/accept-release/) → [revisit](/handbook/revisit-after-change/). Ends with a release verdict and a revisit procedure for the next amendment. Every role starts at the workflow page, which maps the whole pipeline. Each page ends with a next step, so a route is simply the pages you refuse to skip; [troubleshooting](/handbook/troubleshooting/) and [templates](/handbook/templates/) serve all routes from the side. ## Decisions - Solo or shared: a solo draft keeps lighter records; a shared canon package needs full decision and review records. The workflow page spells out both lanes. - Breadth of scope: cover a few articles well rather than the whole act thinly. The scope page shows how to draw the line. - Strictness of review: every shared package passes review with recorded findings; solo drafts self-review against the same record shape. ## Artifact A finished package hands over a scope card, pinned sources with hashes, rule sources, scenarios with expected answers, decision records for modeling choices, a review record with findings, and release notes. Templates for the records live beside this handbook: - [scope card template](/handbook/files/templates/scope-card.md) - [source inventory template](/handbook/files/templates/source-inventory.md) - [decision record template](/handbook/files/templates/decision-record.md) - [review record template](/handbook/files/templates/review-record.md) Filled examples for the running example: - [filled EAI scope card](/handbook/files/filled/eai-scope-card.md) ([v2](/handbook/files/filled/eai-scope-card-v2.md), [v3](/handbook/files/filled/eai-scope-card-v3.md)) - [filled EAI source inventory](/handbook/files/filled/eai-source-inventory.md) ([v2](/handbook/files/filled/eai-source-inventory-v2.md), [v3](/handbook/files/filled/eai-source-inventory-v3.md)) - [filled EAI tariff decision](/handbook/files/filled/eai-decision-tariff.md) - [filled EAI threshold decision](/handbook/files/filled/eai-decision-threshold.md) - [filled EAI penalty decision](/handbook/files/filled/eai-decision-penalty.md) - [filled EAI premium-base decision](/handbook/files/filled/eai-decision-premium-base.md) - [filled EAI review](/handbook/files/filled/eai-review-agent.md) ([candidate](/handbook/files/filled/eai-review-candidate.md), [R3](/handbook/files/filled/eai-review-candidate-r3.md)) ## EAI example The running example on every page is the employee accident insurance package: name kz.corpus.employee_accident_insurance, version 0.1.0, language 0.2, zero dependencies, explicit local imports. [Source snapshot]: it covers the duty, tariff, payout, and penalty branches of four articles: the employer duty to insure (Article 8), the late-payment penalty (Article 9), tariff classes with premium (Article 17), and payout eligibility (Article 19). 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 package passes its static check and all seven scenarios pass under tool `law` 0.1.0, including loss thirty established against loss twenty-nine left undecided, a class 22 premium of 29600 KZT on a payroll of one million, and a penalty of 3000 KZT. Modeling choices stand as EAI-D1 (tariff as strict rules), EAI-D2 (inclusive thirty boundary), and EAI-D3 (penalty with no rounding policy); review left findings EAI-R1 and EAI-R3. This paragraph is the canonical statement of the running numbers; pages that repeat them point here. The accepted candidate — EAI plus the R1 fix, the R3 premium re-grounding, the full tariff suite, both boundary pairs, the fractional-penalty probe, and the three premium-base probes — passes thirty-seven of thirty-seven under the same tool, with snapshot id `7635d197…`; the post-amendment revisit passes thirty-seven of thirty-seven with snapshot id `02469c81…`. The record checker passes seventeen of seventeen over four templates and thirteen filled records. The synthetic drills that complete the stages EAI leaves flat: readings profiles four of four each, admission six of six, time windows and terms seven of seven, payroll borrowing one of one pinned. Every tally on every page traces to one of these runs, quoted with its command in place. ## Pitfall Starting with rules before scope. Authors who model first tend to cover the easy articles twice and the hard ones never. Write the scope card first, and let it say no to most of the act. ## Verify You used this landing page correctly when you can name your role, your route, and the records your package will hand over. Criterion: state in one breath which pages you will read and which records you will produce — if either list is blank, re-read the routes and the artifact list above. ## Limits This handbook does not teach the language (see Tutorials), does not define constructs (see Reference), and does not replace legal judgment about what the act means. Multi-act bridges and corpus-wide migrations are maintainer topics beyond the solo lane. ## Next step Continue with [Package workflow](/handbook/workflow/), which maps the full pipeline every route follows. ## Sources - [Four states of support](/tutorials/four-states/) - [Real article source](/tutorials/real-article-source/) - [Vocabulary](/constructs/vocabulary/) - [Language](/language/) - [Reading an answer](/guide/reading-an-answer/) - [Decision protocol](/protocols/decision-protocol/) - [Fact protocol](/protocols/fact-protocol/) - [Diagnostics](/diagnostics/)