| name | convergence-gate |
| model | opus |
| description | Runs a structured 7-phase convergence session to arrest strategic drift after 3-4 Sonnet feature sessions — the full remediation, not just a status check (for a quick RED/YELLOW/GREEN triage first, use `dojo-craft:convergence-checker`). Use when the drift-detector fires YELLOW or RED, or when you notice accumulating uncommitted state, deferred validations, and growing open-items lists. |
| category | repo-docs-health |
| version | 1.1.0 |
| tags | ["convergence","drift","hygiene","governance"] |
| inputs | [{"name":"trigger_reason","type":"string","description":"Why convergence is being run — YELLOW drift warning, RED drift warning, or manual call","required":false}] |
| outputs | [{"name":"convergence_report","type":"ref","format":"markdown","description":"Updated convergence ledger entry with session count reset, commit sweep results, triage decisions, and strategic evaluation"}] |
Convergence Gate Skill
Philosophy
Sonnet sessions produce excellent artifacts but poor trajectory. Each session is locally optimal — clean build, tests pass, seed captured — 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-detector.sh hook enforces this mechanically, but the convergence gate skill is the procedure that actually runs when the hook fires.
Convergence also enforces two deployment disciplines: a pre-deployment readiness check that forces full build/lint/test/e2e verification before any release, and a deployment retrospective that captures friction from recent deploys before it evaporates.
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)
- When open-items lists have been growing across multiple sessions without resolution
- When multiple deferred validations (tests, build checks, config audits) have accumulated
- When you sense "things are going well" but can't clearly articulate what the next priority is — that ambiguity is exactly what convergence resolves
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.
Workflow
Phase 1: Inventory
Objective: Establish a complete picture of the current state before touching anything.
- Run
git status across all active repos to count dirty files and identify untracked paths.
- Read
~/.claude/convergence-ledger.md to confirm session count since last convergence.
- Identify the drift severity: YELLOW (10+ files or 4+ sessions) or RED (25+ files or 6+ sessions).
- List all open items from CLAUDE.md, MEMORY.md, and any active TODO files — do not edit them yet.
- Identify deferred validations: any
go build, go test, migration checks, or connectivity tests that were skipped in prior sessions.
Output of Phase 1: a flat inventory list. No judgments or actions yet.
Phase 2: Commit Sweep
Commit all work-in-progress that is ready to ship.
