douinc Loop Engineering
Overview
Use a bounded control loop where each iteration reduces uncertainty or advances an observable result.
Entry Contract
Before acting, establish:
- one objective and its boundaries;
- observable completion evidence;
- safety, authority, and compatibility constraints;
- an iteration, time, or tool budget;
- the smallest verification command or observation that can test the next action.
Infer only reversible, low-risk defaults. If missing information would materially change public behavior, cost, scope, or an irreversible action, return needs-user-decision.
Classify the task before acting:
- trivial: run
goal → action → verificationonce; - local: run the full loop with local evidence;
- cross-cutting: run the full loop and apply Graph Escalation.
Read loop-protocol.md before iterating and stop-conditions.md before declaring an outcome.
Run the Loop
Repeat plan → act → verify → decide:
- Plan: choose one falsifiable hypothesis, one bounded action, and its expected evidence.
- Act: perform the smallest authorized action that tests the hypothesis or advances the objective.
- Verify: run the planned check and compare expected with actual evidence.
- Decide: complete, retry with new evidence, replan, block, or request user direction.
Track the protocol state in task memory or temporary scratch space. Never add loop transcripts, chain-of-thought, or speculative reasoning to durable project documentation.
Graph Escalation
Broaden local evidence into a map when:
- a public interface, shared schema, global configuration, or deployment boundary changes;
- failures appear in multiple components or layers;
- the same dependency knowledge is repeatedly rediscovered;
- impact or rollout order cannot be established from the local module.
When graph-engineering is installed, it is a REQUIRED SUB-SKILL for those cross-cutting cases. If unavailable, build a compact evidence-backed impact map inline and continue; do not fail only because the companion skill is absent.
graph-engineering never needs to invoke this skill.
Progress and Final Output
During long tool work, report evidence, the decision, and next action at least every 60 seconds without exposing private reasoning.
Finish with exactly one outcome:
| Outcome | Required report |
|---|---|
complete |
acceptance evidence, verification commands or observations, test limitations, and intentional changes |
blocked |
blocking condition, attempts made, recoverable workspace state, and next action |
needs-user-decision |
decision required, evidence, and materially different options |
Common Mistakes
| Mistake | Correction |
|---|---|
| Repeating the same action | Require new evidence or replan. |
| Treating a passing check as sufficient | Match it to every completion criterion. |
| Expanding scope after each failure | Expand only across an observed dependency boundary. |
| Calling ambiguity a technical blocker | Use needs-user-decision when user intent must govern. |
| Persisting execution history as architecture | Persist only stable, evidence-backed project knowledge. |