H. Troubleshooting by evidence boundary
Begin with the exact symptom, command, current folder, checkpoint, and most recent relevant change. Preserve a small reproducer and the original diagnostic. Then choose a test that distinguishes explanations. Randomly changing source, reinstalling tools, and increasing permissions at once makes the result harder to interpret.
| Symptom | First useful check | Targeted recovery |
|---|---|---|
| A relative file cannot be found | Get-Location, expected root contents |
Enter the correct extraction root and rerun the affected command |
| Tool name is not recognized | Get-Command, documented install location |
Use supported installation or current-session override; reopen terminal when needed |
A .ps1 file is blocked |
Existing execution policy and checkpoint README | Use the primary .cmd wrapper; do not weaken policy to follow the course |
| Native executable exits before output | Actual exit code and runtime location | Use the documented wrapper/compiler distribution; distinguish loader failure from a test failure |
| Firmware target is unavailable | Core list and manifest FQBN | Install the pinned documented platform and select exact options |
| Host check passes but cross-build fails | Compiler diagnostic and target source list | Investigate target compatibility separately; host success does not establish cross-build success |
| Replay reports fixture line error | Original row, grammar, line number | Correct malformed fixture input; do not disguise it as a sensor fault |
| Replay enters FAULT | Event, validity, freshness, recovery requirement | Decide whether FAULT is expected behavior before changing code |
| AI explains a missing file | Actual action record and folder scope | Correct context/path and repeat bounded inspection |
| Skill seems ignored | Exact path/name, metadata, host discovery | Test explicit invocation, then trigger behavior; simplify conflicting guidance |
| Git push fails | Remote URL, identity, fetched history | Separate auth, destination, and divergence; preserve work before integration |
| A new checkout cannot build | Tracked files and documented dependencies | Add missing source or setup instruction, then repeat the affected reproduction |
When an AI answer is the failing artifact
Isolate one consequential claim. Ask whether it is code-supported, documented, tested, inferred, or unresolved. Provide the exact relevant passage or source and request a corrected artifact. Do not make an answer true by silently changing the requirement to match it. If an alternative design is worth considering, record it as a proposed decision with tradeoffs.
If an agent makes unrelated changes, stop further work and inspect the actual diff. Preserve useful content and return to a known state using the appropriate Git operation. Narrow the next brief around a concrete artifact and acceptance criteria. The correction should remove the unrelated effect while retaining the requested improvement.
When a test fails
First confirm the test executed. A compiler error, loader failure, failed assertion, and valid FAULT-state replay are different events. Read the project format contract: successful replay may intentionally produce FAULT, while malformed fixture syntax exits with a diagnostic. Do not equate every alarming word with the same failure.
Keep expected values independent of the current implementation. If you change both the program and its expected output to make a test pass, explain which requirement justified the new expectation. A seeded fault should fail before the fix and the original source should still pass afterward. That demonstrates a meaningful distinguishing check.
Optional serial and physical work
The required firmware uses synthetic acquisition and the core course does not require upload. If you choose the optional physical extension, identify the actual board variant, cable capabilities, host port mapping, documented boot mode, and adapter configuration. Check the manufacturer's current instructions. A charge-only cable, missing device mapping, or wrong port can prevent communication without any policy defect.
Do not describe a cross-build as an upload receipt. Record the actual board, source artifact, upload command, tool result, and observed serial behavior if performed. Keep physical connections and measurements separate from host simulation. A serial line received from a board can still contain deliberately synthetic values; origin depends on the firmware's acquisition path, not simply the cable.
Know when to pause one path
Some dependencies require a human login, an unavailable account allowance, a source document, or optional physical observation. Name the exact missing item and continue work that does not depend on it. A pending check is preferable to a fabricated pass. The goal is to finish the engineering task with traceable evidence, not to keep every tool busy regardless of what is known.