titan-sync

name	titan-sync
description	Identify overlapping fixes across audit results, plan shared abstractions, produce an ordered execution plan with logical commit grouping (Titan Paradigm Phase 3)
argument-hint	null
allowed-tools	Bash, Read, Write, Glob, Grep, Edit

Titan GLOBAL SYNC — Cross-Cutting Analysis & Execution Plan

You are running the GLOBAL SYNC phase of the Titan Paradigm.

Your goal: analyze GAUNTLET results to find overlapping problems, identify shared abstractions that should be built before individual fixes, group changes into logical commits, and produce an ordered execution plan.

Context budget: This phase reads artifacts, not source. Keep codegraph queries targeted — only for specific relationship questions between failing targets.

---

Step 0 — Pre-flight

1. Worktree check:

   git rev-parse --show-toplevel && git worktree list
   

   If not in a worktree, stop: "Run /worktree first."

2. Sync with main:

   git fetch origin main && git merge origin/main --no-edit
   

   If there are merge conflicts, stop: "Merge conflict detected. Resolve conflicts and re-run /titan-sync."

3. Load artifacts. Read:

   • .codegraph/titan/titan-state.json — state, domains, batches, file audits
   • .codegraph/titan/GLOBAL_ARCH.md — architecture, dependency flow, shared types
   • .codegraph/titan/gauntlet.ndjson — per-target audit details
   • .codegraph/titan/gauntlet-summary.json — aggregated results

4. Validate state. If titan-state.json fails to parse, stop: "State file corrupted. Run /titan-reset."

5. Check GAUNTLET completeness. If gauntlet-summary.json has "complete": false:

   "GAUNTLET incomplete (/ batches). SYNC will plan based on known failures only. Run /titan-gauntlet first for a complete plan."

6. Extract. From artifacts, collect:

   • All FAIL and DECOMPOSE targets with violations and files
   • Common violation patterns by pillar
   • Community assignments
   • Dead symbols (cleanup candidates)
   • Domain boundaries and dependency flow

---

Step 1 — Find dependency clusters among failing targets

For FAIL/DECOMPOSE targets that share a file or community, check connections:

codegraph path <target1> <target2> -T --json

Group connected failures into clusters. Also check for cycles among them:

codegraph cycles --functions --json

Filter to cycles including at least one FAIL/DECOMPOSE target.

---

Step 2 — Identify shared dependencies and ownership

For each cluster, find what they share:

codegraph deps <key-file> --json

Look for:

• Shared imports: multiple failures import the same module → interface extraction candidate
• Shared callers: multiple failures called by the same function → caller needs updating
• Common violations: similar pillar violations across targets

Check code ownership for cross-team coordination:

codegraph owners <file1> <file2> -T --json

If different teams own files in the same cluster, note the coordination requirement.

Run branch structural diff to see what's already changed:

codegraph branch-compare main HEAD -T --json

Avoid re-auditing or conflicting with in-progress work.

---

Step 3 — Detect extraction candidates

For DECOMPOSE targets:

codegraph context <target> -T --json
codegraph ast --kind call --file <file> -T --json

Look for:

• Functions with multiple responsibilities (high cognitive + high fan-out + high halstead.bugs)
• Repeated patterns across failures (similar call chains)
• God files (many failing functions → split along community boundaries)

---

Step 4 — Plan shared abstractions

Identify what to build BEFORE individual fixes:

1. Interface extractions — shared dependency → extract interface
2. Utility extractions — repeated patterns → shared utility
3. Module splits — god files → split by community structure
4. Cycle breaks — circular deps → identify weakest link

For each, check blast radius:

codegraph fn-impact <shared-dep> -T --json

---

Step 5 — Build execution order with logical commits

Phases (in order)

1. Dead code cleanup — zero risk, reduces noise
   • Commit: chore: remove dead code
2. Shared abstractions — before individual fixes
   • One commit per abstraction: refactor: extract X from Y
3. Cycle breaks — unblocks dependent targets
   • One commit per break: refactor: break cycle between X and Y
4. Decompositions — highest risk, after abstractions
   • One commit per decomposition: refactor: split X into A and B
5. Fail fixes — ordered by blast radius (lowest first)
   • Group by domain: fix: address quality issues in <domain>
6. Warn improvements — optional, lowest priority
   • Group by domain: refactor: address warnings in <domain>

Ordering within each phase

• Dependencies first (if A depends on B, fix B first)
• Lower blast radius first
• Same community together

Each commit should:

• Touch one domain where possible
• Address one concern
• Be independently revertible
• Run /titan-gate before committing

---

Step 6 — Write the SYNC artifact

Write .codegraph/titan/sync.json:

{
  "phase": "sync",
  "timestamp": "<ISO 8601>",
  "clusters": [
    {
      "id": 1,
      "name": "<descriptive>",
      "targets": ["t1", "t2"],
      "sharedDeps": ["mod"],
      "hasCycle": false,
      "owners": ["team-a", "team-b"],
      "proposedAction": "Extract interface"
    }
  ],
  "abstractions": [
    {
      "type": "interface_extraction|utility_extraction|module_split|cycle_break",
      "description": "...",
      "source": "<current location>",
      "unblocks": ["t1", "t2"],
      "blastRadius": 0,
      "commit": "refactor: ..."
    }
  ],
  "executionOrder": [
    {
      "phase": 1,
      "label": "Dead code cleanup",
      "targets": ["sym1", "sym2"],
      "risk": "none",
      "commit": "chore: remove dead code",
      "dependencies": []
    }
  ],
  "deadCodeTargets": ["<from recon>"],
  "cyclesInvolvingFailures": []
}

Update titan-state.json: set currentPhase to "sync".

---

Step 7 — Report to user

Print:

• Dependency clusters found (count)
• Shared abstractions proposed (count)
• Execution order summary (phases, target counts, estimated commits)
• Key insight: what SYNC prevented (e.g., "3 targets share configLoader — without SYNC, 3 conflicting refactors")
• Path to sync.json
• Next step: start Phase 1 (dead code cleanup), validate each commit with /titan-gate

---

Rules

• Read artifacts, don't re-scan. Codegraph commands only for targeted relationship queries.
• Always use --json and -T.
• The execution order is the key output.
• Logical commits matter. Never mix concerns.
• If GAUNTLET found zero failures, produce minimal plan (dead code + warnings only).
• Keep codegraph path queries targeted — same file or community only.

Self-Improvement

This skill lives at .claude/skills/titan-sync/SKILL.md. Edit if clustering misses connections or execution order causes conflicts.