generator-evaluator-loop

generator-evaluator-loop

Automates the Generator→Evaluator→Generator feedback cycle for a single enso story. The story's ### Verification section is the immutable contract. Tool failures and convention violations trigger automatic retry. Subjective disagreements on story intent or design principles pause the loop and escalate to the human.

---

When to Use

• Story has a complete ### Verification section written by the Reasoner
• Story ## Approach & Verification Plan is finalized (planning phase complete)
• Story ## Context Scope Write/Read/Exclude lists are defined
• You want automated review with human escalation on disagreement

When NOT to Use

• Story is still in planning (Verification section incomplete or missing)
• Trivial single-step changes where review overhead exceeds value
• Story has no verifiable success criteria (commands, expected output, tests)
• Story is already in reference/completed/ — it's done

---

Roles

Role	Mode	Responsibility
Generator	Generator	Executes story. Produces changes + execution notes.
Evaluator	Quality	Reads Verification criteria. Runs tools. Reviews conventions. Produces evaluation_result.
Arbiter	Human	Resolves Generator/Evaluator disagreements on story intent or design.

The Reasoner writes the story before this skill is invoked. The Reasoner is not active during the loop.

---

The Loop

User invokes skill with story path
         │
         ▼
  ┌─ VALIDATE ──────────────────────────────────────────┐
  │  Story has complete Verification section?            │
  │  Context Scope defined?                              │
  │  Branch/Worktree resolved (if applicable)?           │
  └──────────────────────────────────────────────────────┘
         │ valid                    │ invalid
         ▼                          ▼
  Initialize Loop State        Report + exit (do not start)
  Append ## Loop State
  to story
         │
         ▼
  ┌─ GENERATOR (Generator mode) ────────────────────────────┐
  │  Inputs: story + current context                     │
  │          + prior evaluation_result (if iteration>0)  │
  │  Output: changes applied per Write scope             │
  │          + execution notes (what was done and why)   │
  └──────────────────────────────────────────────────────┘
         │
         ▼
  ┌─ EVALUATOR (Quality mode) ──────────────────────────┐
  │  1. Load convention docs (see CONVENTIONS_MAP.md)    │
  │  2. Run every tool in story Verification section     │
  │  3. Review changes against loaded convention docs    │
  │  4. Classify each finding: OBJECTIVE or SUBJECTIVE   │
  │  5. Produce evaluation_result (see template)         │
  │  6. Update Loop State iteration log                  │
  └──────────────────────────────────────────────────────┘
         │
         ├─── All criteria PASS ──────────────────────────▶ ACCEPTED
         │                                                   Check off Verification
         │                                                   boxes in story. Exit.
         │
         ├─── OBJECTIVE rejections only ─────────────────▶ RETRY
         │    (tool failure, cited convention violation)      Increment iteration.
         │    AND iteration < max                             Return to Generator
         │                                                    with feedback.
         │
         ├─── Any SUBJECTIVE rejection ──────────────────▶ ESCALATE
         │    (design judgment, story-intent ambiguity,       Append escalation_notice
         │     SOUL.md / project principle concern)           to story. Exit. Await
         │                                                    human ruling.
         │
         └─── iteration ≥ max OR same finding 2× ────────▶ FORCE ESCALATE
              (regardless of rejection type)                  Append escalation_notice
                                                              with full iteration
                                                              history. Exit.