E. Project records that survive the conversation

A small set of records keeps different kinds of knowledge from collapsing into one long README. Requirements state desired behavior. Hardware references state sourced constraints. Decisions explain a chosen tradeoff. Test plans describe checks to run. Results record checks that actually happened. A handoff names the current state and next task. Link them where one depends on another.

Requirement example

An original requirement record can say: “R-EX: A missing synthetic sample selects FAULT and exposes no current temperature. Check by supplying a missing event and inspecting the output fields.” The requirement defines behavior; it is not a test result. A later result should identify which version implemented it and what the check observed.

The final reference project has its own R01–R12 contract, including threshold equality, hysteresis, stale age, recovery, command grammar, shared source, and reproducibility. Do not copy a simplified introductory rule over that contract. Name the stage and requirement before changing behavior.

Hardware/source row

Use columns for claim, exact part/board, value and unit, conditions, source title/revision/location, confidence or unknown, and design consequence. If the board guide supplies a connection while the silicon datasheet supplies an electrical limit, keep those sources distinct. A row should not imply the same document established both facts unless it actually did.

An incomplete row is useful when it names what is missing: “Connector mapping unresolved; need schematic for the exact assembled revision.” A confident unsourced pin number is less useful because it hides the dependency. Physical observations belong in a separate result record with setup and method.

Decision record

Decision: Use synthetic input for the required workflow.
Context: The course must be reproducible without buying or wiring hardware.
Choice: Share policy/parser/output source between host and firmware builds.
Consequence: Host tests and replay can check software behavior; physical
acquisition, electrical operation, and sensor accuracy remain separate work.
Revisit when: The optional physical adapter has a sourced plan and bench method.

This is an original explanation of the course design, not a bench result. A good decision record helps a future contributor understand why an apparently obvious alternative was not chosen. It need not become a long meeting transcript.

Test plan and result

Write expected values before execution. The final policy's clear boundary is 27.0 °C at the default threshold; the test should include equality because < and <= differ there. The expected value must come from the requirement, not from copying the implementation's current result.

Use this compact result format:

Check ID and requirement:
Date, environment, tools:
Source commit/hash and checkpoint:
Input origin and fixture:
Exact working directory and command:
Expected result:
Actual output/exit and evidence path:
Interpretation:
Remaining limitation:

A plan with empty actual fields is not failed documentation; it is simply a plan awaiting execution. A result must contain real observations. If a test cannot start because a dependency is missing, record that setup failure separately from the behavior you intended to test.

Handoff example

“Current source is the named reviewed commit. The README origin label is corrected. CP01 replay and cross-build results are saved at the listed evidence paths with their tool versions. No physical observation occurred. Next task: create a branch for the documentation improvement in Chapter 8 and preserve the current baseline. The unresolved item is a missing setup explanation for the compiler override.”

Replace every generic field with your actual state. A handoff should let the next person start without reading the entire history of attempts. Put current facts first and link diagnosis history if it remains useful. Do not mark a file accepted merely because a previous session said it was done.

Download the record templates, then fill them as the project creates evidence. Empty templates are scaffolding; a useful knowledge base contains a small number of accurate, linked records whose claims can be checked.