convergence-checker

Convergence Checker Skill

I. Philosophy

Sonnet sessions produce excellent artifacts but poor trajectory. Each session is locally optimal — clean build, tests pass, feature shipped — but globally drifting: more open items, more uncommitted state, more deferred validation. The missing discipline is periodic evaluation of trajectory, not just output.

Convergence is not a feature session. It produces no new features. It produces a clean, tested, committed, evaluated state — and a reset counter so the next cycle starts from solid ground.

The drift thresholds are intentionally conservative. YELLOW fires at 10 dirty files or 4 sessions — not because the project is in trouble at that point, but because that is when intervention is cheap. RED is expensive. YELLOW is the efficient intervention point.

Do not skip convergence because "things are going well." Drift is invisible until it is expensive.

II. When to Use

• When drift-detector.sh fires a YELLOW warning (10+ dirty files OR 4+ sessions since last convergence)
• When drift-detector.sh fires a RED warning (25+ dirty files OR 6+ sessions)
• Before dispatching a large parallel agent swarm — convergence ensures the baseline is clean
• After a multi-session sprint to consolidate before the next phase
• When you sense accumulating open items but cannot articulate the current priority

Do not use this skill for feature work. Convergence sessions produce zero new features. Any fix discovered during convergence is logged and deferred — never implemented in-session.

III. Workflow

Step 1: MEASURE

Establish the current quantitative state.

Run the following:

# Count uncommitted changes per repo
git status --short | wc -l

# List all uncommitted files
git status --short

# Count untracked files separately
git status --short | grep "^?" | wc -l

# Check for sub-repos with dirty state
find . -name ".git" -maxdepth 3 -type d | while read gitdir; do
  repo=$(dirname "$gitdir")
  count=$(git -C "$repo" status --short 2>/dev/null | wc -l | tr -d ' ')
  if [ "$count" -gt "0" ]; then
    echo "$repo: $count dirty files"
  fi
done