---
enforcement: high
activation: "bound"
enforcedBy:
  - aiwg:decision-engine/absolute-screening#blocking-false-ready-events
summary: "Execute tests before returning generated code; record results and root causes, apply targeted fixes, retry at most three times, and escalate with execution history."
bound_to:
  agents: ["ai-ml-engineer", "blockchain-developer", "build-engineer", "code-reviewer", "component-owner", "data-engineer", "database-optimizer", "debugger", "devops-engineer", "django-expert", "frontend-specialist", "integration-engineer", "kubernetes-expert", "legacy-modernizer", "mobile-developer", "performance-engineer", "react-expert", "reliability-engineer", "self-debug", "software-implementer", "spring-boot-expert", "test-architect", "test-engineer", "toolsmith", "toolsmith-dynamic", "toolsmith-provider"]
  skills: ["address-issues", "agent-loop", "agent-loop-ext", "aiwg-mission", "auto-test-execution", "build-poc", "code-chunker", "decompose-file", "execute-feedback", "flow-delivery-track", "flow-guided-implementation", "flow-iteration-dual-track", "flow-test-strategy-execution", "generate-tests", "mission-control", "ralph", "ralph-external"]
  flows: ["flow-delivery-track", "flow-guided-implementation", "flow-iteration-dual-track", "flow-test-strategy-execution"]
triggers:
  - "run tests before returning generated code"
  - "retry failing tests with root cause analysis"
  - "persist executable feedback debug memory"
---

# Executable Feedback Loop Rules

**Enforcement Level**: HIGH
**Scope**: All code-generating agents
**Research Basis**: REF-013 MetaGPT (+4.2% HumanEval; −63% human revision cost, 2.25→0.83 cycles)
**Issue**: #101

## Overview

Code-generating agents MUST execute tests before returning results (MetaGPT's executable-feedback pattern), and track execution history so failures inform fixes rather than blind retries.

## Mandatory Rules

Gate coverage is scoped to D29 held-out evidence screening: the
`aiwg:decision-engine/absolute-screening#blocking-false-ready-events` gate
rolls back on any false-ready event in the `failed-test` blocking slice. It
checks screening outcomes; test execution and retry discipline remain guidance.

### Rule 1: Execute Before Return
Never return generated code without running its tests. Flow: generate → execute tests → pass? return : debug & retry. Returning untested code is FORBIDDEN.

### Rule 2: Track Execution History
Maintain debug memory per attempt: timestamp, code hash, test results (passed/failed/errors), failure analysis (test, error, root cause), and the fix applied. This history is what makes retries informed.

### Rule 3: Retry on Failure
On failure: (1) analyze, (2) identify root cause, (3) apply fix, (4) re-execute, (5) repeat until pass or max attempts. Retry policy: `max_attempts: 3`, immediate backoff, escalate to human review on max.

### Rule 4: Failure Analysis is REQUIRED
**FORBIDDEN**: retry with random changes. **REQUIRED**: for each failure record error type, message, stack-trace snippet, root cause, and fix strategy before changing code.

### Rule 5: Test Coverage Requirements
Minimum coverage before returning:

| Code Type | Min Coverage | Required Tests |
|-----------|--------------|----------------|
| New function | 80% | happy path + edge cases |
| Bug fix | 100% of fix | regression test for the bug |
| Refactor | match original | existing tests must pass |
| API endpoint | 90% | integration + error cases |

### Rule 6: Debug Memory Persistence
Persist debug memory across sessions at `.aiwg/ralph/debug-memory/` (JSON, ~30-day retention, indexed by file / error-type / test).

### Rule 7: Learning from History
Before generating, check debug memory (recent window) for similar file edits, the same test failures, and recurring error types; apply those learnings.

## Execution Protocol

Generate code → generate tests if absent (happy/edge/error) → execute and record → if pass, record success and return; if fail, analyze (parse errors, root cause, check memory for patterns), apply targeted fix, increment attempt, loop while attempts < max, else escalate to human with the full debug-memory context (original code, all test results, failure analyses, fix attempts).

## Checklist

Before returning code: tests generated for new code; tests executed (not skipped); all passing; debug memory updated; failures analyzed (if any); coverage meets minimum; learnings recorded.

## References

- @.aiwg/research/findings/REF-013-metagpt.md
- @$AIWG_ROOT/agentic/code/addons/agent-loop/schemas/debug-memory.yaml — debug memory schema
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/test-engineer.md
- #101

---

**Rule Status**: ACTIVE
**Last Updated**: 2026-01-25
