ouroboros-loops:determine

Ouroboros: Determine

Perform autonomous judgment on whether the loop has achieved its goal and should terminate. This step runs after evaluate and augments its simple condition checks with deeper reasoning about codebase health, progress trends, and stagnation.

When to Use

The determine step is invoked as the final step in each iteration after evaluate returns OUROBOROS_RESULT: continue. It provides a second, higher-quality judgment layer that can override continue with done when genuine completion is detected, or confirm continue when real work remains.

Design Goals

• Evaluate the completionPrompt condition using natural language reasoning, not just substring matching
• Detect stagnation: issues that appear 3+ iterations without resolution should be deferred, not re-attempted
• Assess net progress: new issues found vs. issues resolved this iteration
• Evaluate overall codebase health by reading recent findings history
• Return a well-reasoned OUROBOROS_RESULT decision

Procedure

1. Read State and History

Read .ouroboros/state.json and collect:

• goal: the original improvement objective
• completionPrompt: natural language completion condition (may be null)
• iteration: number of iterations completed so far (post-evaluate increment)
• maxIterations: upper bound
• findings: full findings object including [RESOLVED] entries
• current_iteration.fixes and current_iteration.enhancements: what was done this cycle (may be empty if evaluate already reset them — in that case, read the latest report instead)

Also read the most recent .ouroboros/reports/iteration-N.md for the summary of this cycle's work.

Read .ouroboros/handoff-history/ to assess recent history (up to 3 most recent handoff files) and identify patterns across iterations.

2. Stagnation Detection

For each unresolved finding in findings.bugs, findings.quality_issues, and findings.enhancement_opportunities (entries NOT prefixed with [RESOLVED] or [DEFERRED]):

1. Count how many consecutive iterations this finding has appeared without being resolved. Use the report files (.ouroboros/reports/iteration-N.md) to check if the finding was present but not acted on in previous cycles.

2. If a finding has been present and unresolved for 3 or more consecutive iterations:

   • Mark it as [DEFERRED] in state.json findings by prefixing the entry with [DEFERRED].
   • Log: [DEFERRED] <finding summary> — present for 3+ iterations without resolution
   • Deferred items do NOT count as "remaining work" for the completion check.

3. After deferring stagnant items, if ALL remaining unresolved findings are either [RESOLVED] or [DEFERRED], this is a completion signal (see step 4, Condition D).

Deferral write procedure: Read state.json, update the affected finding entries by prefixing them with [DEFERRED], then write back. Preserve all other fields.

3. Net Progress Assessment

Calculate net progress for this iteration:

• Issues resolved: count of findings that became [RESOLVED] this iteration (appeared without [RESOLVED] in the previous report, now have it).
• New issues found: count of findings added this iteration (present in current findings, absent from the previous report's findings).
• Net progress score = issues_resolved - new_issues_found

Classify net progress:

• score > 0: positive progress — real improvement made
• score == 0: neutral — found new issues but resolved equal number, or did nothing
• score < 0: regression — more issues introduced than resolved (rare but possible)

A negative score for 2+ consecutive iterations is a strong signal to stop (the loop may be making things worse, or the research step is over-discovering).

4. Check Completion Conditions

Evaluate all conditions. Signal done if any of the following are true:

Condition A: Iteration limit already reached (safety catch — evaluate should have caught this first)

iteration >= maxIterations

Condition B: Natural language completionPrompt evaluation

• If completionPrompt is set, read the goal and the completionPrompt text.
• Evaluate whether the spirit and substance of the condition has been met, based on:
  • What has been fixed and enhanced across all iterations (read the full reports/ directory)
  • The current state of the codebase as reflected in findings
  • Whether the completionPrompt describes a quality bar, a specific feature, or a coverage threshold
• This is a reasoning judgment, not a substring check. Use the full context of all reports to make a holistic assessment.
• If confident the condition is met: signal done with reason "completionPrompt satisfied: <brief justification>"
• If uncertain: default to continue (false negatives are safer than false positives here)

Condition C: No remaining actionable work

• All findings in findings.bugs, findings.quality_issues, and findings.enhancement_opportunities are [RESOLVED] or [DEFERRED].
• No net-negative consecutive progress (see step 3).
• Signal done with reason "no remaining actionable work after N iterations"

Condition D: Stagnation-driven completion

• All remaining unresolved findings were just deferred in step 2 (i.e., no findings remain that are neither [RESOLVED] nor [DEFERRED]).
• Signal done with reason "all remaining issues deferred after 3+ iterations without resolution"

Condition E: Regression loop detected

• Net progress score has been negative or zero for 3+ consecutive iterations.
• This indicates the loop is not making net progress and should stop to avoid diminishing returns.
• Signal done with reason "no net progress detected for 3+ consecutive iterations"

Default: if none of the above conditions are met, signal continue.

5. Return Result

Communicate the result explicitly:

If done:

OUROBOROS_RESULT: done
Reason: <specific condition that triggered termination>
Total iterations completed: N
Stagnation deferred: <count> findings

Then delete .ouroboros/active if it exists.

If continuing:

OUROBOROS_RESULT: continue
Net progress this iteration: <score> (+resolved / -new_issues)
Remaining actionable findings: <count>
Deferred findings: <count>
Starting next cycle.

6. Update state.json

Write the determination outcome to state.json under a determine_log field. This provides a persistent record of each iteration's judgment:

{
  "determine_log": [
    {
      "iteration": 2,
      "result": "continue",
      "net_progress": 3,
      "deferred_count": 0,
      "stagnation_detected": false,
      "reason": "3 issues resolved, 1 new issue found. Actionable work remains."
    }
  ]
}

If determine_log already exists, append the new entry — do not overwrite prior entries.

7. Hand Off

After completing this step, output a completion message. The agent (not this skill) is responsible for invoking ouroboros-loops:context-handoff next.

Integration with evaluate

determine runs after evaluate. The intended flow is:

... → report → evaluate → determine → (next iteration or done)

The evaluate skill performs fast, deterministic checks (iteration limit, substring match, empty findings). The determine skill performs slower, reasoning-based checks (natural language completionPrompt, stagnation, net progress trends). Together they form a two-layer termination gate:

1. evaluate: "Are the mechanical conditions for stopping met?"
2. determine: "Is it actually wise to keep going?"

If evaluate returns done, the loop ends immediately — determine is not invoked. If evaluate returns continue, determine gets a chance to override that decision.

Important: determine should NOT re-increment the iteration counter (that is evaluate's responsibility). It only reads the post-evaluate state and returns a result.

context-handoff Mapping

The context-handoff skill needs to map determine to the correct next step. Add the following mapping:

completed_step	next_step
determine	(end of iteration — same as evaluate)

This tells the handoff skill that after determine, the iteration is complete and the next step is research (beginning of the next iteration).

Notes on Model Choice

This skill runs on opus (same as evaluate). The stagnation detection and natural-language completionPrompt evaluation require reasoning beyond Sonnet's capability. When OUROBOROS_MODEL_DETERMINE is set, that value overrides the default.

Deferred vs Resolved

Prefix	Meaning
[RESOLVED]	Issue was actively fixed or enhanced
[DEFERRED]	Issue is real but not being addressed after 3+ iterations; loop may still continue if other work exists
(no prefix)	Issue is unresolved and eligible for attention in the next iteration

Deferred items appear in determine_log for transparency but are NOT re-surfaced to the analyze step as new findings. The analyze step MUST respect [DEFERRED] entries the same way it respects [RESOLVED] entries — do not re-add them as fresh findings.