Utility · use it before asking for help
Troubleshoot by layer
This week adds two layers above the code: the spec can be wrong, and the logic can be wrong, before Python ever gets a chance to be. The ladder sorts them, and the further left the fault, the cheaper the fix.
Find the layer that failed
- A. Spec. Symptom: the pair argues about whether behaviour is a bug, or a requirement cannot be tested. Diagnosis tools: the five qualities on the Requirements page. Fix: edit the requirement, then everything downstream.
- B. Logic. Symptom: the trace table (or the running program, faithfully translated) does the wrong thing. Diagnosis tool: trace the exact failing scenario on paper; the row where the table diverges from intent is the bug. Fix the pseudocode, re-trace, then re-translate.
- C. Translation. Symptom: code and pseudocode disagree. Diagnosis tool: read them side by side, line by line; the construct map makes mismatches mechanical to spot. Classic culprits below.
- D. Runtime. Tracebacks, venvs, wiring: Week 4's ladder applies verbatim.
Symptom table
| Symptom | Layer | Most likely cause | What to do |
|---|---|---|---|
| Partners disagree on whether behaviour is correct | A | The requirement is ambiguous, or missing | Write or repair the R-line until one reading survives; the code follows it |
| A requirement cannot be checked ("shall be responsive") | A | No measurable tail | The repair shop moves: find the observable behaviour, add units and a threshold |
| Loop never exits, on paper or on the Pi | B | No line changes the condition; no EXIT reachable | Three trace rows expose it; add the line that moves the loop toward exit |
| False start also reports a time (R4 broken) | B | The early-press fact never leaves the loop | The flag pattern: set it inside, decide after (worked design) |
| One press affects the next round too | B | No wait-for-release between rounds | The edge case the design's release waits exist for; add them in the pseudocode first |
| Behaviour right once, wrong on repeat | B | State (counter, flag, mode) not reset where a round begins | Trace two consecutive rounds; the leftover value shows in the table's second lap |
| Code branch that no pseudocode line explains | C | The driver "improved" the design silently | Back to the navigator: change the design or delete the branch; the two must match |
| IF body runs at the wrong time despite clean syntax | C | Indentation puts a line outside the block the design intended | Compare indent levels against the pseudocode's; the grammar rule |
| Off-by-one: five rounds specified, four (or six) played | C | range() or a < vs <= mistranslation | Trace the boundary lap by hand; check the map's FOR row |
| Reaction times drift or go negative | C/D | Wall clock used for an interval | monotonic(), per the timing background |
| Traceback, import error, dark LED, bouncing button | D | Last week's territory | Week 4's ladder and symptom table, unchanged |
Fix it upstream
The week's discipline in one rule: a fault is fixed at its own layer, and the artifacts downstream are updated to match. Patching the Python to hide a design flaw leaves docs/design.md lying about the code; patching the design to dodge a spec ambiguity leaves the pair still disagreeing at the demo. The professional reflex, in this course and in automation work, is the same one your change-controlled wiring diagrams follow: change the drawing, then the panel. When the running system reveals that a requirement was wrong, that is not a failure of the method, it is the method working: edit the R-line, note why in the commit message, and let the change flow down. The commit history becomes the record of what was learned, which is precisely what the project's documentation grade rewards.
Before you ask for help
Bring evidence, and the teacher can help in one minute instead of ten. For this week that means:
- Which layer (A to D) you got stuck at, and why you ruled out the ones to its left.
- For A: the disputed requirement, as written, and the two readings of it.
- For B: your trace table of the failing scenario, to the row where it goes wrong.
- For C: the pseudocode block and the Python block, side by side.
- For D: exactly what Week 4's list asks.