Embedded Project Loop
Use a small durable loop for work that crosses the boundary between files and
physical hardware. The agent may prepare and verify host-side artifacts, but it
must not invent soldering, flashing, measurement, or field evidence.
Recommended entry point
Load this skill before arduino-workflow-router whenever the request includes
physical hardware, more than one session, a pending measurement, a field test,
or recovery work. It owns the durable goal, next todo, evidence boundary,
rollback path, and physical gate. The router then selects board, wiring, code,
toolchain, test, and deployment specialists without closing this loop on its
behalf.
State
Use .arduino/ in the project, or a user-selected external evidence directory:
.arduino/goal.md
.arduino/next-todo.md
.arduino/board-profile.md
.arduino/evidence/{build,upload,hardware,system,deployment}/
.arduino/experiment-log.jsonl
.arduino/resume-token.md
Keep secrets, tokens, private network credentials, and unredacted personal data
out of these artifacts. goal.md records the exact target, success criteria,
non-goals, safety constraints, stop conditions, and rollback path. The next-todo
file contains one action, owner, prerequisites, expected evidence, gate, and
status.
Bounded iteration
- Read the goal, next todo, board profile, and last ledger entry.
- Select one causal firmware, wiring, power, measurement, or diagnostic change.
- Run the narrowest safe host/build check available.
- Stop at a physical gate if the next action requires the user.
- Compare the supplied observation with the expected result and independent
safety gate.
- Append the action, evidence path, decision, rollback, and next todo.
- Keep only a verified candidate; otherwise record a blocker or restore the
current experiment surface.
One iteration must not combine several wiring changes, firmware images, power
sources, or measurements. One change keeps failures attributable.
Physical gate
Use a specific question and wait for the observation:
Physical gate: On <exact board/revision>, perform <one action> with power
<state>. Capture <measurement/log/photo> at <location>. Expected:
<observable result>. Reply with the observation or `blocked: <reason>`; do not
reply with an unverified yes.
For a failed upload, request the exact port/device identity, image/hash, and
redacted uploader log. For a power question, request the meter location, units,
and minimum/maximum observed value. For wiring, request a continuity/polarity
check or labeled photo before enabling loads.
Evidence boundary
- Build evidence proves source/configuration and dependency compilation only.
- Upload evidence proves an image was accepted by a named target path only.
- Hardware evidence requires target identity plus measurements, serial output,
continuity, scope data, or a contextualized photo.
- System evidence requires the integrated scenario and representative load.
- Deployment evidence requires health check, staged update, rollback, recovery,
and maintenance records.
If evidence is absent, say unverified or blocked and keep the next todo open.
Read the router recovery reference before erase, bootloader repair, or reflash.
Anti-rationalization
| Shortcut |
Response |
| "The checkbox is done." |
Require the artifact and proof stage. |
| "The compile passed." |
Do not promote it to upload, hardware, or system proof. |
| "The user probably wired it." |
Ask the concrete gate question and wait. |
| "Try three fixes together." |
Split them into one-change iterations. |
| "Erase first." |
Confirm target, last-known-good image, recovery path, and data-loss impact. |
| "No new output means success." |
Record a no-op observation; it does not close the goal. |
Verification
- State files exist and the next todo names one deterministic action.
- Every completed physical step links to evidence with a proof-stage label.
- The ledger records decision, rollback, and next candidate append-only.
- Stop conditions and repair caps are explicit.
- In this repository, run
python3 scripts/run_arduino_evals.py; the
loop-engine-evidence-contract case checks valid and invalid durable loop
artifacts and fails closed when required state or ledger fields are missing.
Shared output contract
Use the shared Arduino skill contract:
state assumptions, required tools and versions, implementation steps,
tests/evidence by proof stage, known limitations, and recovery/security notes.
1---
2name: embedded-project-loop
3description: Use first when Arduino or embedded hardware work spans sessions, parts delivery, wiring, soldering, flashing, measurements, field tests, recovery, or a durable next-todo is needed. Maintain explicit evidence and concrete physical-world user gates instead of assuming completion.
4metadata:
5 triggers: "hardware loop, next todo, long-running embedded project, physical gate, evidence log, resume hardware work"
6 recommended: "first for long-running or physical work"
7 attribution: "Adapted from the local loop-engine and long-run-harness-execution contracts; physical evidence remains user-owned."
8---
9
10# Embedded Project Loop
11
12Use a small durable loop for work that crosses the boundary between files and
13physical hardware. The agent may prepare and verify host-side artifacts, but it
14must not invent soldering, flashing, measurement, or field evidence.
15
16## Recommended entry point
17
18Load this skill before `arduino-workflow-router` whenever the request includes
19physical hardware, more than one session, a pending measurement, a field test,
20or recovery work. It owns the durable goal, next todo, evidence boundary,
21rollback path, and physical gate. The router then selects board, wiring, code,
22toolchain, test, and deployment specialists without closing this loop on its
23behalf.
24
25## State
26
27Use `.arduino/` in the project, or a user-selected external evidence directory:
28
29```text
30.arduino/goal.md
31.arduino/next-todo.md
32.arduino/board-profile.md
33.arduino/evidence/{build,upload,hardware,system,deployment}/
34.arduino/experiment-log.jsonl
35.arduino/resume-token.md
36```
37
38Keep secrets, tokens, private network credentials, and unredacted personal data
39out of these artifacts. `goal.md` records the exact target, success criteria,
40non-goals, safety constraints, stop conditions, and rollback path. The next-todo
41file contains one action, owner, prerequisites, expected evidence, gate, and
42status.
43
44## Bounded iteration
45
461. Read the goal, next todo, board profile, and last ledger entry.
472. Select one causal firmware, wiring, power, measurement, or diagnostic change.
483. Run the narrowest safe host/build check available.
494. Stop at a physical gate if the next action requires the user.
505. Compare the supplied observation with the expected result and independent
51 safety gate.
526. Append the action, evidence path, decision, rollback, and next todo.
537. Keep only a verified candidate; otherwise record a blocker or restore the
54 current experiment surface.
55
56One iteration must not combine several wiring changes, firmware images, power
57sources, or measurements. One change keeps failures attributable.
58
59## Physical gate
60
61Use a specific question and wait for the observation:
62
63```text
64Physical gate: On <exact board/revision>, perform <one action> with power
65<state>. Capture <measurement/log/photo> at <location>. Expected:
66<observable result>. Reply with the observation or `blocked: <reason>`; do not
67reply with an unverified yes.
68```
69
70For a failed upload, request the exact port/device identity, image/hash, and
71redacted uploader log. For a power question, request the meter location, units,
72and minimum/maximum observed value. For wiring, request a continuity/polarity
73check or labeled photo before enabling loads.
74
75## Evidence boundary
76
77- Build evidence proves source/configuration and dependency compilation only.
78- Upload evidence proves an image was accepted by a named target path only.
79- Hardware evidence requires target identity plus measurements, serial output,
80 continuity, scope data, or a contextualized photo.
81- System evidence requires the integrated scenario and representative load.
82- Deployment evidence requires health check, staged update, rollback, recovery,
83 and maintenance records.
84
85If evidence is absent, say `unverified` or `blocked` and keep the next todo open.
86Read the router recovery reference before erase, bootloader repair, or reflash.
87
88## Anti-rationalization
89
90| Shortcut | Response |
91|---|---|
92| "The checkbox is done." | Require the artifact and proof stage. |
93| "The compile passed." | Do not promote it to upload, hardware, or system proof. |
94| "The user probably wired it." | Ask the concrete gate question and wait. |
95| "Try three fixes together." | Split them into one-change iterations. |
96| "Erase first." | Confirm target, last-known-good image, recovery path, and data-loss impact. |
97| "No new output means success." | Record a no-op observation; it does not close the goal. |
98
99## Verification
100
101- State files exist and the next todo names one deterministic action.
102- Every completed physical step links to evidence with a proof-stage label.
103- The ledger records decision, rollback, and next candidate append-only.
104- Stop conditions and repair caps are explicit.
105- In this repository, run `python3 scripts/run_arduino_evals.py`; the
106 `loop-engine-evidence-contract` case checks valid and invalid durable loop
107 artifacts and fails closed when required state or ledger fields are missing.
108
109## Shared output contract
110
111Use [the shared Arduino skill contract](../../docs/arduino-skill-contract.md):
112state assumptions, required tools and versions, implementation steps,
113tests/evidence by proof stage, known limitations, and recovery/security notes.
wedsamuel1230