sanurb/feedback-loop

Feedback Loop

Create fast, deterministic feedback loops so the agent can self-validate and converge.

When to Load

• Task stalled or unclear success criteria
• Need reproducible failures or measurable outcomes
• UI/visual or data outputs hard to validate

Step 0: Discover Repro

Before any loop, find or create the repro command. In an unfamiliar codebase:

1. Check AGENTS.md, README.md, CONTRIBUTING.md for test/dev/build commands
2. Inspect runner configs: package.json scripts, Makefile, justfile, Taskfile, Cargo.toml, pyproject.toml
3. Check CI: .github/workflows/, .gitlab-ci.yml, Jenkinsfile for test/build steps
4. Search for test files near affected code: glob **/*test*.*, **/*spec*.*
5. If no test exists, write a minimal reproduction script or test first — this is your first loop iteration

Loop Selector

| Signal | Loop type | Recipe | |---|---|---| | Failing tests, errors, type errors, regressions | Debugging | loop-recipes.md#debugging | | Visual output, animation, layout, rendering | UI/visual | loop-recipes.md#uivisual | | Metrics drift, ETL, data quality | Data pipeline | loop-recipes.md#data-pipeline | | Build/compile errors, dependency issues | Debugging | Use build command as repro |

If multiple match, prefer the loop with the most deterministic measurement.

Core Loop (every iteration)

1. Sense: capture current output + signal (run repro, read watcher output)
2. Hypothesize: state suspected cause and what you expect to change
3. Change: smallest fix to test hypothesis (one thing at a time)
4. Measure: run deterministic check (test, snapshot, metrics query)
5. Decide: keep if green, revert if no signal change, iterate with new hypothesis

Principles

• Convert human-centric signals into text or structured artifacts
• Encode state in parameters so results are deterministic
• Prefer fast, headless runs over slow UI paths
• Allow the agent to add logs/metrics to expose signal
• Separate exploration (agent) from acceptance (human)

Required Artifacts (non-negotiable)

| Artifact | What | Example | |---|---|---| | Repro | Deterministic command or URL | npm test -- auth, agent-browser open localhost:3000 | | Expected vs observed | Explicit comparison | "expected 200, got 401" | | Measurement method | Re-runnable check | test runner, agent-browser snapshot -i, metrics query |

Full artifact matrix per loop type: loop-recipes.md

Persistent Observability (tmux)

If tmux is available, set up persistent feedback sources in adjacent panes:

| Source | Start command | Read signal | |---|---|---| | Test watcher | npm run test:watch / pytest-watch | tmux capture-pane -p -J -t {pane} -S -50 then grep PASS/FAIL | | Dev server | npm run dev / cargo watch -x run | tmux capture-pane -p -J -t {pane} -S -50 then grep ERROR | | Build watcher | tsc --watch / cargo watch -x check | tmux capture-pane -p -J -t {pane} -S -50 then grep error | | Browser | agent-browser open localhost:3000 | agent-browser snapshot -i |

Read from adjacent pane: tmux capture-pane -p -J -t {pane} -S -50 Wait for pattern: while ! tmux capture-pane -p -t {pane} -S -20 | grep -q "pattern"; do sleep 1; done

This gives continuous feedback without re-running full commands each iteration.

Artifact Persistence

• During loop: keep artifacts in conversation context (fast, ephemeral)
• On rescope or escalation: persist to a markdown file for tracking
• On completion: include final repro + resolution in commit message or PR description

Exit Criteria

• Expected output matches observed and measurement is green
• Repro command passes deterministically

Rescoping (when loop stalls)

If no new signal after 2 iterations:

1. State what you tried and why it didn't produce signal
2. Question your loop type — wrong category? Re-run selector
3. Question your repro — is it actually exercising the bug? Widen scope
4. Improve observability — add more logging, check adjacent systems, use tmux watchers
5. Reduce scope — find a smaller, more isolated failing case
6. If still stuck: escalate to user (see below)

Loop Switching

If a bug spans domains (e.g., visual symptom but root cause in data/logic):

• Start with the most deterministic measurement
• If 2 iterations produce no signal, switch loop type
• Derive a text/assertion proxy from visual symptoms where possible (e.g., check computed styles, DOM structure, API response instead of screenshot)
• Carry artifacts forward — repro command and observations transfer between loops

Escalation Triggers

Stop and ask the user when:

• Agent cannot execute measurement (no screenshot tool, no DB access, no metrics)
• Fix requires changes outside agent scope (infra, permissions, external service)
• 3 rescope attempts with no convergence
• Measurement is subjective (visual "looks right", UX feel)

When escalating, provide: repro command, last hypothesis, all artifacts collected.

Handling Flaky Repros

If the repro is non-deterministic:

• Pin randomness (seed values, --seed flags)
• Freeze time (mocks, faketime, test fixtures with fixed dates)
• Mock external dependencies (network, APIs, filesystems)
• Run N times to distinguish signal from noise
• Reduce concurrency / isolate the test

In This Skill

| File | Purpose | |---|---| | loop-recipes.md | Steps, tooling, artifacts, checklists per loop type | | examples.md | Full worked loop iterations with hypotheses + decisions |