16. Build Your Reusable Engineering Toolkit

What you will be able to do

You will turn a practiced review procedure into the second project skill, evaluate it with a meaningful defect and clean work, and resume a bounded task without the old conversation. Start with Chapter 15 and CP08. This checkpoint has shared NORMAL/FAULT policy, synthetic replay, and basic assertions; thresholds, hysteresis, and commands arrive in the capstone. The deliverable is a tested review procedure and a handoff supported by actual evidence. No physical board is required.

Keep the parts that earn their maintenance

A useful toolkit is a small collection of things that reduce repeated effort. You already have a README, sourced hardware context, project instructions, a constraints skill, and maintained command wrappers. Each has a distinct job. The next improvement is not to collect more files indiscriminately, but to identify a recurring action whose result you can evaluate.

Consider the work you repeat during a firmware review. You inspect the requested diff, read the requirement it affects, look at nearby callers, examine failure and recovery paths, and ask whether a test could distinguish the defect. Those steps involve judgment. They belong in a focused procedure rather than a string of unrelated commands. A skill can make the procedure available without requiring the full explanation in every prompt.

Contrast that with compiling a known source list or rejecting malformed fixture rows. Those tasks need deterministic behavior. The maintained scripts and parser are better places for them. A skill may call a wrapper when appropriate, but it should not become a second, subtly different build system. Keep the executable operation in one maintained location and describe its role in the procedure.

Your toolkit also needs subtraction. Remove a redundant rule when its detail already has a current home. Replace an outdated command rather than preserving both and hoping the agent chooses correctly. Keep the next task and active evidence in the handoff, not in a growing catalogue of abandoned ideas. A file earns its place when a person can explain what repeated problem it solves.

Separate expectations from procedures

The root AGENTS.md describes recurring project expectations: consult current context, keep work bounded, use relevant checks, and report results honestly. The hardware document contains exact source-dependent facts. The review skill describes how to inspect a bounded change. The task prompt identifies the particular diff and the requested outcome. These layers should cooperate without repeating every detail.

A rule saying “run all possible checks before any response” can obstruct an inspection-only task or a harmless wording change. A better procedure connects checks to findings and scope. Reviewing a supplied diff does not automatically authorize rewriting it. If execution is available and relevant, use it to resolve a concrete uncertainty. If execution is unavailable, state the predicted consequence and the missing verification rather than inventing an observed failure.

The official OpenAI skills guide describes Codex's skill packaging and invocation; the AGENTS.md guide covers project guidance discovery. The course's installed-host behavior still needs its own fresh-session record. A valid skill file or a readable instruction summary is not evidence that the intended workflow occurred.

The firmware-review skill

Open .agents/skills/firmware-review/SKILL.md in CP08. Its bounded purpose is to review an embedded firmware or shared C++ policy diff for actionable correctness issues. It excludes unrelated documentation changes and full security audits. The distinction keeps a small review from becoming an uncontrolled investigation of the entire project.

The inputs are the exact diff, nearby source needed to understand it, applicable requirements, and relevant evidence. Ask the reviewer to identify which checkpoint is active before applying a checklist. CP08 does not contain the capstone command parser, so a review that demands its tests is working from the wrong stage. Figure SS16-01 shows the actual skill file and its boundaries.

A useful finding names a file and location, a concrete trigger, the resulting consequence, and a check or source that supports the claim. “There may be timing problems” gives the engineer little to do. “After the last valid sample ages beyond 3000 milliseconds, the changed polling path leaves the cached reading current” identifies an observable behavior and a discriminating test.

Review timing arithmetic, missing and nonfinite inputs, stale data, recovery, integer conversions, bounded work, output formatting, and relevant tests. These are inspection lenses, not a requirement to manufacture one finding in every category. If the diff is clean within the inspected scope, say that no actionable issue was supported and identify only material verification gaps.

Separate severity from certainty. A potentially serious consequence can still be a hypothesis. An executed reproducer strengthens confidence that a specific defect exists. The report should make the difference visible. Do not use dramatic wording to compensate for missing evidence, and do not downgrade an established correctness defect merely because its patch is one line.

Worked example: review the stale-data fault

Keep CP08 active in a checkout cloned from the history bundle so the review skill is available. Supply the bounded diff using git diff CP07 FAULT-stale -- firmware/sensor-monitor/monitor_policy.cpp. The FAULT-stale snapshot is CP07-based and lacks the second skill, so do not assume it discovers firmware-review on its own. The intentional mutation disables stale expiration in poll while still compiling. Ask for review without repair, preserving the actual response and tool evidence. Execute the faulty source only in a separate FAULT-stale exercise copy.

The intended requirement is that input age exactly 3000 milliseconds remains current, while age 3001 milliseconds becomes stale. In the supplied stale-recovery sequence, the last valid sample is at timestamp 1000. At 4000 it is still current. At 4001 its temperature must no longer be presented as current. The requirement therefore supplies a precise trigger independently of the implementation.

The expected review finding concerns the missing expiration path and its effect on state and output. It should connect poll to FAULT/stale and unavailable temperature, rather than merely complain about formatting. If the agent reports a finding, inspect the source and requirement yourself. The example defines the acceptance criterion; it is not a transcript of a run that you have not performed.

Run the relevant commands from the separate FAULT-stale exercise root when you are ready to verify the faulty behavior:

.\scripts\test.cmd
.\scripts\replay.cmd fixtures/stale-recovery.csv

A behaviorally useful fault exercise compiles and then fails the relevant assertion or expected sequence. A syntax error that prevents compilation does not show that the behavioral test detects stale data. Preserve the failing output, identify the assertion, and compare it with the expected condition before attributing a cause.

After review, use a separate authorized repair task or make the correction yourself. Restore the expiration guard, repeat the same checks, and inspect the diff. A firmware/shared-source change also needs the cross-build:

.\scripts\build-firmware.cmd

The final record should distinguish review, repair, host verification, and firmware compilation. A successful result supports those software claims for the recorded source. It does not establish a physical sensor, upload, electrical behavior, or device timing. Figure SS16-02 should show the actual actionable review result and its evidence relationship.

Test useful restraint

The defect case is only part of the skill evaluation. Create a clean comparison in a disposable CP08 copy by consistently renaming a local variable without changing behavior. Ask for a bounded review. The desired result is not a compulsory warning; it is an accurate assessment of the actual diff and any relevant limitations. Verify that the rename is genuinely consistent before calling the case clean.

Then use a fresh task to improve one README sentence without changing firmware. Do not name the review skill in this negative case. The task should remain ordinary documentation work rather than forcing a firmware audit. Explicitly invoking the skill would change the question and weaken the test of unwanted implicit selection.

Record selection separately from output quality. If the interface reveals that the skill file was read, preserve that evidence. If it does not, avoid inferring activation merely because the response uses a familiar format. A well-formed finding and an observable skill invocation answer different questions. Both can matter when maintaining the procedure after a host update.

Change one demonstrated weakness at a time. A broad description may need a tighter trigger. An unsupported finding may need a clearer evidence requirement. A clean change that provokes invented defects may need an explicit “no supported issue” outcome. Repeat the affected cases and preserve the before/after records rather than replacing failures with the final successful answer.

Write a handoff that can be checked

A handoff is a compact map of active state. It should identify the current checkpoint or commit, the completed change, the last relevant checks with evidence pointers, open questions, and one next bounded action. It should tell the next worker what can be trusted and what still needs inspection. A transcript of the entire conversation usually obscures that information.

Do not write “everything passes” when the evidence concerns an earlier source revision. Link a result to the source it checked. If the working tree changed afterward, identify which checks are still relevant and which need repetition. A saved command is useful only when its input, environment, and result can be related to the current task.

The CP08 handoff includes a concrete exercise: add an assertion proving that negative infinity produces FAULT/nonfinite with no current temperature, leaving production behavior unchanged. If you already added negative infinity in Chapter 15, use a fresh CP08 copy to avoid duplicating that extension. This is a good restart task because the requirement already covers nonfinite input, the test file contains nearby NaN and positive-infinity cases, and success can be inspected in a small diff.

Use a separate Monitor instance or carefully ordered injected timestamps so the new case does not accidentally depend on unrelated test state. For example, an independent monitor can receive negative infinity at timestamp zero. Assert its state, error category, and current flag. The existing output tests already cover unavailable temperature formatting; distinguish a policy assertion from a JSON formatting assertion.

The expected result is a stronger test for behavior that already exists. It is not an excuse to add capstone thresholds or redesign the policy. If the new assertion fails, diagnose the discrepancy against the requirement before changing production code. The task may reveal a defect, but that finding needs evidence rather than an assumption that tests are always correct.

LAB16: resume from repository context

Allow 50–75 minutes, excluding account or dependency waiting. Extract CP08 into a new folder or create a new branch from the supplied history bundle. Preserve earlier work. Open the actual project root and inspect the starting status before creating the handoff test.

1. Read docs/handoff.md, AGENTS.md, the README, stage requirements, and the relevant test file. Confirm that negative infinity is the intended bounded next task.
2. Start a fresh agent session in this folder. Ask it to complete the handoff using repository context, without pasting the solution or commands into the prompt.
3. Observe which files it inspects, what it changes, and which maintained commands it actually runs. Preserve the exact prompt and available tool/results evidence.
4. Independently inspect the new assertion. Confirm that the expected state, error, and current flag follow from the nonfinite-input requirement and that the case does not depend on an accidental timestamp order.
5. Inspect the actual test result and any relevant replay/build result. Record source identity and limitations; an announced check is not execution.
6. Update the handoff with the completed bounded change, evidence pointers, remaining questions, and one next action. Do not claim the capstone is implemented in CP08.

Submit the review skill's defect/clean/unrelated records, the fresh-session handoff record, the small test diff, and the revised handoff. A blocked command leaves an execution gate open; the prepared documentation and static review can still be complete. Physical hardware is not a prerequisite.

Failure and recovery: a handoff without receipts

Suppose the handoff says that basic tests passed but contains no command, source identity, or saved output. The next session should not repeat that claim as established history. Search the project's evidence location and relevant prior result records. If the receipt cannot be found, mark the claim unestablished and run the applicable check when possible.

Do not overwrite the old handoff silently. Record the correction: the previous claim lacked an accessible receipt, and the current record now contains a specific result or an open dependency. This preserves the reason for the change and prevents a future reader from confusing reconstructed evidence with the original run.

Another failure is resuming the wrong checkpoint. A task that starts implementing commands in CP08 has skipped the capstone's requirements and review. Check the active source, stage README, and handoff before editing. Recover in a fresh exercise folder if necessary, preserving any useful work. Figure SS16-04 should demonstrate the actual resumed task and validation path rather than a prepared success message.

Maintain a small behavior baseline

After changing a skill description, relevant instructions, or the host interface, rerun a representative set: one meaningful defect, one clean diff, one unrelated task, and the repository-only handoff. Keep source and prompt inputs stable enough to compare outcomes. If both the input and procedure change, record both instead of attributing improvement to the skill alone.

Do not measure quality by the number of findings, files, or tokens. A review that correctly leaves a clean change alone can be better than a long report of speculative defects. A short handoff with valid receipts can be better than a detailed story that omits the active source. Measure whether the toolkit reduces repeated work while preserving the engineer's ability to verify the result.

Completion check and review answers

Complete the chapter when the second skill has actual defect, clean, and unrelated case records; the fresh session resumes the bounded CP08 task; and the handoff links to real current evidence. A static skill check and an instruction summary do not satisfy those runtime gates.

Why test a clean diff? A reviewer must avoid inventing correctness findings. Correct restraint is part of the procedure's value.

Why use a separate monitor for the new nonfinite case? It isolates the requirement and avoids accidental dependence on previous recovery state or timestamp order.

Does a failing compilation prove the stale-data test works? No. The useful seeded defect should compile and then be rejected for the intended behavior.

What should a fresh session do with an unsupported passing claim? Find the receipt or mark the claim unestablished and run the relevant check. It should not copy the claim into a new report.

What belongs in the handoff? Active source/state, completed work, relevant receipts, open questions, and one bounded next task. Detailed reference material stays in its own current document.

Transfer to your own work

Choose one procedure you repeat and one task you often have to reconstruct after a break. Package the procedure with a bounded output and write the task's handoff. Test them on a small real change before adding more machinery. Your toolkit is successful when another session can find the next action and verify it without relying on the old conversation.

Sources and figures

Project paths and behavior refer to the matching CP08/FAULT-stale release and its requirements. Host-specific references: OpenAI build skills, OpenAI AGENTS.md, and the Agent Skills specification, checked September 12, 2026. Figures: SS16-01 review skill, SS16-02 actionable defect, SS16-03 handoff, SS16-04 fresh-session resume. The tests described here require actual recorded execution before a passing claim.