In his Sentinel project diary, Philip Shaw describes five checks for catching divergence among a system’s specification, implementation, and documentation. They are not interchangeable layers of assurance: each watches a different relationship, and each has a boundary. The practical lesson is to assume drift will happen, then give each kind of drift a check that can actually see it.
Why Sentinel needed checks beyond tests
Shaw’s motivating example concerned multi-row inserts. The specification said a batch should flush at 500 rows or 100 milliseconds, whichever came first. The code had configuration for both limits and an accumulator method that could report whether a batch was due, but the live ingest loop did not call that method. The throughput benchmark did use it.
As an Amazon Associate I earn from qualifying purchases.
That distinction matters: a test or benchmark can exercise a mechanism without establishing that the application’s real execution path uses it. In Shaw’s account, a later check against the actual batch bound left the reported figure unchanged. That is his account of the sequence, not independent validation of the benchmark methodology.
The project register reported 4,369 observations a second for CP-1 ingest throughput. Shaw explains that the benchmark measured a batching strategy not used by the live ingest loop. The figure is therefore a project-specific reported result, not a general performance benchmark or independently established result.
#1 Best Overall
Five instruments, five different jobs
Shaw frames the checks as instruments: for each, ask what it watches, where its authority comes from, what keeps it honest, and where that check stops. A useful check can still be incomplete; its value depends on understanding what it does and does not establish.
| Instrument | What it watches | What gives it authority | What keeps it honest—and where that stops |
|---|---|---|---|
| Specification | The system the team intends to build. | It records the intended behavior. | It has no internal check of its own; other instruments examine it. A document cannot audit itself. |
| Registers | Enumerated specification items and open findings. | The specification items and findings they record. | An integrity check can verify register shape, not whether its statements about the outside world are true. |
| Audits | A retrospective account of a build step, including changes and unmet items. | The exit criteria that prompt the audit. | The audit is limited by those criteria; it cannot establish matters those criteria do not ask it to examine. |
| Seam reviews | The joins between documents. | The cross-document relationships being reviewed. | They address gaps between documents rather than consistency within one document. Shaw says this check was added after cross-document gaps were found. |
| Development guide | What the code does today. | Code citations attached to claims, with mechanisms marked “Proved by:” a test or “unverified.” | Structural correspondence with code can be tested, but that does not prove a cited symbol performs the behavior claimed. |
How to read the checks without overclaiming
A specification states intent; it does not confirm implementation
The specification is normative: it describes what the system is supposed to become. That makes it the reference for intended behavior, not evidence that the code currently behaves that way. Shaw puts the limitation plainly: “A document cannot audit itself; the best it can do is be written so that the others can.”
A register can be well-formed and still be wrong
Registers help a team enumerate specification items and keep open findings visible. A structural integrity check can catch malformed or missing register entries, but it cannot validate every assertion about the world. Structure is not truth.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteAn audit sees only what its exit criteria ask it to see
Audits record what happened during a build step, including changes and unmet items. Their usefulness depends on the criteria that trigger them. If an exit criterion never asks whether the live ingest caller uses the batching method, an audit built around that criterion may not expose the mismatch.
A seam review follows relationships across documents
Checking one document against itself will not necessarily reveal that a second document describes a conflicting behavior. Seam reviews focus on those joins. Shaw says the requirement was introduced after the project found cross-document gaps, illustrating how a specific blind spot can justify a new instrument.
A development guide describes the present, not the intended future
The guide is meant to tell readers what the code does today. Shaw’s method attaches code citations to claims and labels mechanisms either “Proved by:” a test or “unverified.” A test supports only the behavior it asserts; it does not automatically prove a caller relationship or that a cited symbol matches the guide’s description.
The guide’s structural check has a similarly bounded role. It can test whether the guide corresponds structurally to code, but a matching symbol reference is not proof that the symbol performs the documented behavior. Shaw captures the danger of prematurely reassuring labels: “a marker reading ‘not checked’ invites the check; one reading ‘trivially true’ ends it.”
How a team can apply the approach
- Name the relationship you need to check. Is the question whether a requirement is recorded, whether a build met its exit criteria, whether two documents agree, or whether a description matches current code?
- Choose the instrument that can observe it. Use a register for enumerated requirements and findings, an audit for a build-step account, a seam review for cross-document consistency, or a code-linked guide for current implementation claims.
- State the check’s limit alongside its result. A passing shape check does not validate external facts; a test does not prove behavior it never asserts; a document citation does not prove the cited code’s behavior.
- Treat unverified claims as open work. Shaw argues that an explicit “unverified” marker invites follow-up instead of turning an unsupported statement into an apparent conclusion.
- Add a check when a concrete gap appears. The seam review arose in response to cross-document gaps. The method is evolutionary: a revealed limitation is a reason to add a targeted check, not to pretend the existing ones cover it.
What the project’s numbers do—and do not—show
Shaw reports that the daemon covered about 36,000 lines across two repositories, while the development guide had fifteen chapters and around 3,300 lines. Eleven commits landed between the guide’s creation and its audit. Two days into the guide, he reports sixty-five claims marked “Proved by:” and three marked unverified. These are details about this project and its process, not general measures of documentation quality or evidence that a particular checking system will work for every team.
Best Value
- You are a software developer, coder or system administrator or just a hobby programmer? Then wear it with the Linux Server Joke Computer Scientist software developer design.
- You are looking for a programmer gift for a friend or colleague who is a system administrator? With the Linux Server Joke Computer Scientist software developer motif you have found the perfect gift idea e.g. as a coder shirt for hackers.
- Hardcover journal with 240 line-ruled pages (120 sheets)
- Built-in elastic closure and ribbon bookmark
- Includes an expandable inner storage pocket and a pen holder
That changing code and documents can drift is the diary’s practical premise. Shaw describes a pointer as “only as current as the last person to follow it.” A citation, audit, or test should therefore be read with its freshness and scope in mind, rather than as a permanent guarantee.
The principle behind checks and balances
The five instruments are useful because their boundaries differ: intent, enumeration, retrospective accounting, cross-document joins, and current code behavior are separate concerns. None should be asked to prove a claim outside its scope. Shaw’s conclusion is to assume documents and code will drift, assign a check to each kind of drift, and add another when an existing check exposes its own edge.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
