claude-archeflow-plugin/skills/convergence/SKILL.md

name, description

name	description
convergence	Detects convergence, stalling, and oscillation in multi-cycle PDCA runs. Prevents wasted cycles by stopping early when findings are not being resolved or are bouncing between cycles. <example>Automatically loaded during Act phase before exit decision</example> <example>User: "Is the run converging?"</example>

Convergence Detection

In multi-cycle PDCA runs, the Act phase must decide whether another cycle will help or just waste tokens. This skill provides the analysis: are findings being resolved (converging), staying the same (stalling), or bouncing back (oscillating)?

When It Runs

Convergence analysis runs after the Check phase completes and before the Act phase exit decision. It requires at least 2 cycles of data — on cycle 1, it is skipped (no comparison baseline).

Check phase → Convergence Analysis → Act phase exit decision

---

Step 1: Finding Comparison

Extract findings from the current cycle and compare against the previous cycle.

Data Sources

• Current cycle findings: Parsed from check-*.md artifacts in .archeflow/artifacts/<run_id>/
• Previous cycle findings: Parsed from check-*.md artifacts in .archeflow/artifacts/<run_id>/cycle-<N-1>/

Each finding is identified by a composite key: source + category + file_location + description_keywords.

Finding Categories

Every finding from the current cycle is classified into exactly one category:

Category	Definition
NEW	Finding not present in any previous cycle
RESOLVED	Was present in the previous cycle, absent in the current cycle
PERSISTENT	Present in both the current and previous cycle (same key)
REGRESSED	Was RESOLVED in the previous cycle (was present in N-2, absent in N-1), but returned in the current cycle

Matching Algorithm

Two findings match if:

1. Same source archetype (guardian, sage, etc.)
2. Same category (security, reliability, quality, etc.)
3. Same or overlapping file location (same file, line within 10 lines)
4. 50%+ keyword overlap in description (lowercase, strip punctuation)

All four conditions must hold. This prevents false matches across unrelated findings.

---

Step 2: Convergence Score

Calculate a convergence score from the categorized findings:

convergence = resolved_count / (resolved_count + new_count + regressed_count)

If the denominator is 0 (no resolved, no new, no regressed — only persistent), the score is 0.0 (stalled, not converging).

Score Interpretation

Score Range	Status	Meaning
> 0.8	Converging	Most issues being resolved, few new ones introduced
0.5 - 0.8	Stalling	Fixing roughly as many as introducing
< 0.5	Diverging	Making things worse — more new/regressed than resolved
0.0 (all persistent)	Stuck	No progress in either direction

---

Step 3: Oscillation Detection

An oscillating finding is one that bounces between resolved and re-introduced across cycles:

1. Finding was present in cycle N-2
2. Finding was absent in cycle N-1 (resolved)
3. Finding is present again in cycle N (regressed)

This indicates the fix in cycle N-1 was undone or invalidated by other changes in cycle N.

Oscillation Rules

• A single oscillating finding: flag it in the convergence report but continue.
• Two or more oscillating findings: STOP and escalate to the user.
• Message: "Findings X and Y are oscillating between cycles. Manual intervention needed — the automated fixes are interfering with each other."

Oscillation tracking requires 3+ cycles of data. On cycles 1-2, oscillation detection is skipped.

---

Step 4: Early Termination Rules

The convergence analysis can override the normal Act phase exit decision. If any of these conditions hold, the recommendation is STOP:

Condition	Threshold	Recommendation
Diverging	Score < 0.5 for 2 consecutive cycles	STOP — changes are making things worse
Stalled	0 findings resolved between cycles	STOP — no progress, further cycles will not help
Stuck	All findings are PERSISTENT for 2 consecutive cycles	STOP — automated fixes cannot resolve these
Oscillating	2+ findings oscillating	STOP — fixes are interfering with each other

When STOP is recommended, the Act phase should:

1. Not start another PDCA cycle
2. Report all unresolved findings to the user
3. Present the best implementation so far (on its branch, not merged)
4. Include the convergence report explaining why the run was stopped

Override Behavior

The convergence STOP recommendation overrides the normal cycle-back logic in the Act phase. Even if CYCLE < MAX_CYCLES and there are fixable-looking findings, if convergence says STOP, the run stops.

The user can always override by explicitly requesting another cycle: "Run one more cycle anyway".

---

Step 5: Integration with Act Phase

Event Data

Convergence data is included in the cycle.boundary event emitted by the Act phase:

{
  "type": "cycle.boundary",
  "phase": "act",
  "data": {
    "cycle": 2,
    "max_cycles": 3,
    "exit_condition": "convergence_stop",
    "met": false,
    "fixes_applied": 2,
    "next_action": "stop",
    "convergence": {
      "score": 0.35,
      "status": "diverging",
      "resolved": 1,
      "new": 2,
      "regressed": 1,
      "persistent": 3,
      "oscillating": ["Timeline reference mismatch"],
      "recommendation": "stop",
      "reason": "Diverging for 2 consecutive cycles"
    }
  }
}

Decision Tree Update

The Act phase decision tree (from act-phase skill Step 4) gains a new first branch:

┌─ Convergence analysis (cycle 2+)
│
├─ Convergence says STOP
│  └─ STOP: Report to user with convergence report
│
├─ Convergence says CONTINUE
│  └─ Fall through to normal exit decision logic
│
└─ Cycle 1 (no convergence data)
   └─ Fall through to normal exit decision logic

Act Feedback Enhancement

When the Act phase builds act-feedback.md for the next cycle, it includes the convergence summary at the top:

## Convergence Analysis (Cycle 1 → 2)

Score: 0.75 (converging)
Resolved: 3 | New: 1 | Regressed: 0 | Persistent: 2

Recommendation: Continue — trend is positive

### Finding Status
| Finding | Status | Cycles |
|---------|--------|--------|
| SQL injection in user input | RESOLVED | 1 |
| Missing rate limit | RESOLVED | 1 |
| Test names unclear | RESOLVED | 1 |
| Null check missing in parser | PERSISTENT | 2 |
| Error path not tested | PERSISTENT | 2 |
| New: Unused import introduced | NEW | 1 |

---

Convergence Report Format

The full convergence report is generated as part of the orchestration output:

## Convergence Analysis (Cycle N-1 → N)

**Score:** 0.75 (converging)
**Resolved:** 3 | **New:** 1 | **Regressed:** 0 | **Persistent:** 2 | **Oscillating:** 0

### Resolved This Cycle
| Source | Category | Description |
|--------|----------|-------------|
| guardian | security | SQL injection in user input handler |
| guardian | reliability | Missing rate limit on auth endpoint |
| sage | quality | Test names don't describe behavior |

### New This Cycle
| Source | Category | Description |
|--------|----------|-------------|
| sage | quality | Unused import introduced by fix |

### Persistent (unresolved across cycles)
| Source | Category | Description | Cycles Open |
|--------|----------|-------------|-------------|
| trickster | reliability | Null check missing in parser | 2 |
| sage | testing | Error path not tested | 2 |

### Oscillating
(none)

**Recommendation:** Continue — trend is positive

---

Integration with Memory Skill

When convergence detects PERSISTENT findings (present for 2+ cycles), these are strong candidates for the memory skill's lesson extraction:

• After a run that had persistent findings, archeflow-memory.sh extract will pick these up with higher confidence (they have been confirmed across multiple cycles within a single run).
• Persistent findings that also appear in lessons.jsonl from prior runs get a double frequency boost (cross-cycle within run + cross-run pattern).

---

Design Principles

1. Conservative stopping. Requires 2 consecutive data points before recommending STOP. A single bad cycle might be noise.
2. User has final say. STOP is a recommendation, not an enforced shutdown. The user can override.
3. Cheap computation. Keyword matching on finding descriptions, simple arithmetic on counts. No ML, no embeddings.
4. Bounded scope. Only compares adjacent cycles (N vs N-1, with N-2 for oscillation). Does not attempt to model long-term trends across many cycles.
5. Observable. All convergence data is included in the cycle.boundary event, making it available for post-hoc analysis via the process log.