M04-L03 — Capture project and hardware facts
Build a small linked context set that distinguishes what the project wants from what its hardware sources establish. Start with CP02 and the README from Module 4. The output is a sourced identity record and explicit unknowns, not a physical wiring claim.
CP02 supplies the README, project brief, and hardware reference. Create the additional notebook records only as you add meaningful content here and in the next lesson. Use the resulting documents according to their purpose: requirements.md for intended behavior, hardware.md for exact sourced target facts, decisions.md for choices and rationale, evidence.md for observations, and handoff.md for current state and the next action. The README links readers into that structure. More filenames do not automatically mean better context.
The selected example board is Adafruit product 5477, the ESP32-S3 Feather variant identified with 4 MB flash and 2 MB PSRAM. Confirm the product identifier on the manufacturer's page before reading memory or interface details. A related family name can lead to a different variant. Keep the BME280 breakout identity, product 2652, separate from the host board and from chip-level documents.
Record publisher, title, URL, relevant section, access date, and revision when supplied. An access date is not a publication date. If the source does not establish the revision of a physical board, write that limitation. Do not fill an empty cell with a familiar number to make the table look complete.
Add a consequence to each relevant fact. The exact memory variant affects target configuration; an unknown physical revision affects optional deployment checks. The future capstone's 28.0 °C teaching threshold is a planned requirement or design choice, not a sensor-calibration claim. A source can support an identity without supporting a pin mapping.
Work through one row at a time: identify the claim, find the source location, retain units and conditions, and explain the project's consequence. If two sources disagree, check whether they describe the same board, chip, or operating condition before declaring a conflict. Preserve unresolved differences visibly.
Figure D08 connects requirements, facts, decisions, and results. Explain those four categories using one example from the project. The ability to classify a statement helps prevent an AI-generated summary from turning a plan into an observation. Finally, follow every new project link and review the diff for unsupported added facts.
Resources and completion
Use the Sensor Monitor CP02 download and its README.md; project paths in this lesson are relative to that root. Read Chapter 9 for the full lab and explanatory review answers. Figure IDs: SS09-01, SS09-02, D08. Primary references: Adafruit product 5477 and GitHub Markdown tables. Complete the exercise, preserve actual evidence, and use the separate instructor answer key for self-check after attempting the task. Narration scripts are production sources; final transcripts must match the actual narrated edit.
Recording transcript
A project becomes easier to resume when its documents tell you what kind of information you are reading. In this lesson, we will separate requirements, hardware facts, decisions, and observations. We will build a small source record for the example target and leave one important unknown visible. Start with checkpoint two and the README you improved in the previous lesson. No physical hardware is required.
Imagine a note that says the sensor monitor clears at twenty-seven degrees and works. That sentence hides several questions. Is twenty-seven degrees the intended boundary or an observed result? What was the starting state? Which source version was tested? Was the input synthetic? Did anyone execute the program? Before an agent can reason well from project context, the context needs to preserve these distinctions.
A requirement describes intended behavior that can be checked. A hardware fact comes from a source about the exact device. A decision records a project choice and its rationale. A result records what happened during a particular procedure. These categories can support one another, but one cannot stand in for another. A requirement does not prove implementation, and a manufacturer page does not prove your physical assembly.
Open the project's docs folder. The checkpoint supplies the brief and hardware reference; we add the other populated records as we work. Requirements belong in requirements dot md. The hardware reference holds sourced target information. Decisions explain why the project chose its current approach. Evidence points to actual results. The handoff names the current state and next bounded action. The README helps a reader enter this structure. We need a few complete useful documents, not a large collection of empty templates.
Begin with the project brief. It plans shared C++ logic with synthetic host input, introduced at checkpoint five. Our current baseline prints a fixed report and has a separate firmware cross-build path. The core course does not require board ownership. That short explanation gives meaning to the files that follow. It also prevents a future session from expanding a documentation task into an unnecessary hardware setup exercise.
Now open the exact board reference. The selected example is Adafruit product five four seven seven, the ESP32-S3 Feather variant with four megabytes of flash and two megabytes of PSRAM. First confirm the product identifier on the manufacturer's page. A family search may return a related variant. The name that helps you search is not always specific enough to support a build setting.
Record the identity as a sourced row. Include the publisher, page title, direct link, relevant section, and access date. If the source supplies a revision, preserve it. If it does not establish the revision of a physical board, say so. An access date tells us when a page was checked; it does not tell us when the manufacturer revised the board or the document.
Keep the sensor breakout separate. The optional BME280 breakout has its own product identity and guide. The chip datasheet, breakout guide, and host-board documentation answer different questions. A chip operating limit does not automatically describe a breakout connector. A host-board feature does not establish that a sensor is populated on the board. Careful identity prevents plausible facts from being attached to the wrong object.
Add a consequence to the memory row. The exact memory variant affects which target configuration should be preserved in the dependency record and build wrapper. This consequence is project reasoning. It is useful to distinguish it from the source's statement so a reviewer can inspect both. The source may be correct while your proposed implementation consequence still needs review.
Now add an explicit unknown: physical board revision has not been observed in this documentation exercise. Explain what that means. Before an optional physical deployment, the exact board evidence must be checked. It does not block the synthetic core path. This is a practical uncertainty statement because it identifies the missing evidence and the decision affected by it.
Do not fill missing pin mappings from memory. You may have used a similar ESP32 board before, but familiar pin numbers can belong to another variant. A page that establishes the existence of a connector may not establish every power-control or initialization requirement. Write only the supported claim, preserve the missing detail, and identify the next primary source that would resolve it.
Consider the teaching alert threshold. Twenty-eight degrees Celsius belongs in the project's requirements and decisions. It is not a claim about sensor calibration, accuracy, or manufacturer limits. Keeping the threshold out of the hardware-fact table helps a future agent understand that it is a project choice that can change deliberately. It should not be defended as an immutable property of the device.
If two documents disagree, check identity and conditions first. They may describe different variants, or one may describe a chip while the other describes a board. If the conflict remains real, preserve both references and keep the affected claim unresolved. Choosing the most convenient value or averaging two incompatible values does not establish a safe or accurate conclusion.
Your exercise is to create three sourced rows: exact board identity, memory configuration, and the explicit physical-revision unknown. Keep the future capstone's teaching-threshold requirement in the requirements document, separate from current baseline behavior. Link the documents from the README and follow those links. Submit a short note distinguishing material you actually opened from source notes supplied with the release. A source-access problem should remain visible.
Before finishing, explain the four categories using your own rows. Which sentence says what the project must do? Which sentence comes from the manufacturer? Which choice belongs to the project? Which result has an actual command or observation behind it? Review the diff for unsupported added facts. You now have context that can guide the next task without quietly converting an assumption into engineering evidence.
One useful review habit is to cover the consequence column and ask what the source alone establishes. Then uncover it and inspect the reasoning separately. This prevents a project choice from masquerading as a manufacturer statement.
Download transcript
