Free tools Windows power users keep installed
One-click scans. No signup required.
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
In Philip Shaw’s Sentinel dev diary, the practical answer to project drift is not one all-purpose test: it is five different checks, each aimed at a different relationship among the specification, implementation, and documentation. The diary’s central lesson is to ask what each check watches, what gives it authority, and what it still cannot establish.
Why Sentinel needed more than a passing test suite
Long-running software projects accumulate divergence: the specification describes intended behavior, code implements behavior, and documentation explains either the plan or the current reality. A check can catch a particular mismatch, but passing that check does not prove every document agrees with the code.
Shaw illustrates the problem with Sentinel’s batching behavior. The specification said multi-row inserts should flush at 500 rows or after 100 milliseconds, whichever came first. The code had settings for those thresholds and an accumulator method that could report when a batch was due, but the live ingest loop did not call that method. The throughput benchmark did use it. In other words, the benchmark exercised a batching strategy that the live path did not use.
The project register reported CP-1 ingest throughput of 4,369 observations per second. Shaw says a later check against the actual batch bound left that figure unchanged. This is his account of Sentinel’s register and benchmark sequence, not an independently validated performance result or a general benchmark for similar systems.
#1 Best Overall
Five checks, five different jobs
The diary calls its checks “instruments.” They are not interchangeable assurance layers: each observes a different thing and has a different evidential limit.
| Instrument | What it watches | What keeps it honest | Where the check stops |
|---|---|---|---|
| Specification | Intended behavior and future direction | Other instruments examine it | It has no internal self-check; a document cannot establish its own accuracy merely by stating it. |
| Registers | Enumerated specification items and open findings | An integrity check of register shape | Shape validation does not establish whether claims about the outside world are true. |
| Audits | Retrospective account of a build step, including changes and unmet items | Exit criteria that prompt the audit | An audit cannot cover what its exit criteria leave out. |
| Seam reviews | Joins and gaps between documents | A review specifically comparing documents | They address cross-document consistency, not every error within each document. |
| Development guide | What the code does now | Code citations, test-linked “Proved by:” claims, and explicit “unverified” labels | Structural correspondence does not prove that a cited symbol performs the described behavior. |
Specification: the statement of intent
The specification is normative: it says what the system is meant to become. But it cannot validate itself. As Shaw puts it, “A document cannot audit itself; the best it can do is be written so that the others can.” The important consequence is that teams need checks that compare intended behavior with other evidence, rather than treating a complete-looking specification as proof of correctness.
Registers: an inventory, not a truth oracle
Registers enumerate specification items and keep findings visible. Sentinel’s integrity check can test whether the register has the expected shape, but that is a check on the record’s structure, not on the truth of every recorded claim. A well-formed register can still contain a mistaken statement about the system or the world.
Recommended Free Tools
Audits: useful only within their exit criteria
An audit records what happened during a build step, including changes and unmet items. Its coverage is bounded by the conditions that trigger and define it. If an important behavior is outside those exit criteria, an otherwise complete audit may not surface it.
Seam reviews: look between documents
A document can be internally consistent while contradicting another document or leaving a gap at the boundary between them. Shaw says Sentinel added seam reviews after finding cross-document gaps. Their distinct value is precisely that they ask whether documents connect, rather than whether each one reads consistently on its own.
Development guide: a map of current code
The guide describes what the implementation does today; it does not decide what the implementation ought to do. Shaw’s method attaches code citations to claims and labels a mechanism either “Proved by:” a test or “unverified.” A test label is meaningful only to the extent of the assertion: a test can pass while missing a caller relationship or failing to validate that a cited symbol performs the behavior attributed to it.
The guide is also checked for structural correspondence with the code, but that does not settle whether each cited symbol actually behaves as described. As Shaw cautions, “a pointer is only as current as the last person to follow it.” In the diary’s reported snapshot, the guide had fifteen chapters and about 3,300 lines; an audit came eleven commits after its creation. Two days into the guide, Shaw reported sixty-five claims marked “Proved by:” and three marked unverified. Those counts describe Sentinel’s guide at that point, not a recommended target or a measure of documentation quality.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →How to apply the checks without overstating assurance
- Separate intent from implementation. Keep the specification as the authority for intended behavior and the guide as an account of current behavior. Do not use one as a substitute for the other.
- Make the comparison explicit. For each check, identify the object it examines: specification items, a build step, document-to-document joins, or code claims. A check that covers one relationship should not be described as covering all of them.
- Read test claims at assertion scope. Ask exactly what the test asserts and which call path it exercises. A test of a helper does not prove that the application’s live path calls that helper, as Sentinel’s batching example shows.
- Preserve uncertainty visibly. Mark unsupported guide claims as unverified rather than allowing them to appear proven through confident wording or a code pointer alone. Shaw’s formulation is that “a marker reading ‘not checked’ invites the check; one reading ‘trivially true’ ends it.”
- Add a check when a concrete blind spot appears. Sentinel’s seam reviews arose from a discovered cross-document gap. The useful response to a check’s limit is to state that limit and decide whether another check is needed—not to treat the original check as broader than it is.
What the diary establishes—and what it does not
Shaw presents a project-specific method and a motivating mismatch, not a controlled comparison of documentation systems or a general performance study. The diary’s reported line counts, commit gap, claim counts, batching thresholds, and throughput figure belong to Sentinel as described by its author. They do not establish typical values for other projects, nor do they independently verify the repository or benchmark.
The transferable idea is narrower and more useful: match each check to a named failure mode, then state the boundary of what that check can prove. Specification, registers, audits, seam reviews, and code-oriented guides answer different questions. None is a universal certificate that the whole project is aligned.
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.
