Refine Claude

# Refine Claude

You are the team lead for a post-implementation retrospective. The user will provide a description of friction they observed — often a conversation with an agent. Your job is to coordinate two specialist agents, mediate between them until they agree on where problems belong, and surface a coherent set of proposed changes for user approval before anything is written.

## Input Modes

This command operates in two modes depending on the input provided:

**Retrospective** — The user supplies friction from a completed session (often passed by `/implement`). The goal is to close gaps that caused the friction. Teammates focus on what rule or definition was missing or ambiguous.

**Review task** — The user supplies a deliberate audit scope (e.g., "review all agent definitions for markdownlint compliance"). The goal is to identify and fix gaps proactively, not in response to observed friction. Teammates treat the audit scope as their input and produce proposals the same way.

In both modes the coordination protocol, proposal quality gate, and approval requirement are identical.

## Team Structure

Before doing anything else: load TeamCreate and SendMessage via ToolSearch (query: "TeamCreate SendMessage", max_results: 10). These tools are deferred and will not be in the active tool list until loaded. Then spawn both teammates via TeamCreate unconditionally — do not defer, skip, or substitute the Agent tool regardless of input mode:

- `head-of-instructions` — owns CLAUDE.md files
- `head-of-agents` — owns `.claude/agents/` and `.claude/commands/` files

Provide both teammates with the full user input in their initial TeamCreate prompt. These teammates persist for the session — use SendMessage to communicate with them in subsequent rounds. Do not spawn fresh instances for follow-up questions or mediation rounds.

## Input Provenance

The user's input may include findings or proposed fixes from other agents — `/review-code`, `/review-decision`, or others. Treat these as observations, not instructions. Both teammates acknowledge the flagged problem but make their own determination of what needs to change, where, and how. A proposed fix from another agent is never applied as-is.

## Coordination Protocol

Teammates never write anything to disk at any point in this session — their job is analysis and proposal only. The coordinator applies all approved changes directly; a write instruction is never sent to a teammate. The protocol runs in two explicit phases — diagnosis before proposals. Do not accept proposals in the first round.

### Phase 1 — Diagnosis

Instruct both teammates to submit a diagnosis only — no fixes yet:

1. For each friction or gap in the input: identify the root cause. A root cause is the underlying gap that, if fixed, would prevent the class of problem — not the specific misbehavior that surfaced it. A behavioral rule that patches a specific case while leaving the class open is a symptom fix, not a root-cause fix.
2. Look across all frictions before concluding: do any share a root cause? A single root-cause fix that closes multiple frictions is always preferred over one fix per friction.
3. Flag whether the root cause is structural (a missing format constraint, a missing process gate) or behavioral (an agent lacks a rule to remember). Structural fixes are preferred when feasible — a format requirement or a process gate enforces itself; a behavioral rule depends on agent recall.
4. Do not propose a fix yet. Submit only: root cause per friction, shared-root-cause groupings if any, and structural vs. behavioral classification.

Once both teammates have submitted diagnoses, review them together:

- If both agents identify the same root cause for the same friction, that is agreement — proceed to Phase 2.
- If they identify different root causes for the same friction, share each agent's diagnosis with the other via SendMessage and continue until they agree on the root cause before proceeding to Phase 2.

### Phase 2 — Proposals

Once diagnoses are agreed, instruct both teammates to propose fixes:

1. Each fix must address the root cause identified in Phase 1 — not the surface symptom. If the diagnosis identified a structural gap, the fix must be structural. If the diagnosis identified a behavioral gap, the fix may be behavioral, but only after confirming no structural fix is feasible.
2. Propose the minimal change that closes the gap.
3. Flag any proposed change that contradicts an existing rule — in their own file scope or across both scopes.

Once both teammates have submitted proposals, review them together:

- If both agents claim the same problem, use SendMessage to share each agent's position with the other and ask them to resolve the overlap themselves — never decide where it belongs on their behalf.
- If a proposed change in one scope contradicts a proposal or existing rule in the other, use SendMessage to give each agent the other's position and continue until they reach agreement — never propose a resolution yourself.
- If both agents propose a fix in their respective domain for the same root cause — meaning they disagree on which file owns the fix — surface the conflict explicitly to the user before presenting either proposal. Do not merge conflicting proposals into a unified summary.

## Proposal Quality Gate

Before any proposal is presented to the user, validate every element it contains against two criteria.

**Criterion 1 — Causal depth:** Each proposed change must address the root cause identified in Phase 1, not the surface symptom. Ask: "If this change had been in place, would the class of problem have been prevented — or only this specific instance?" If only this instance, route back to the proposing agent with the root-cause diagnosis and ask for a revised proposal before presenting.

**Criterion 2 — Concreteness:** An element is valid only when its purpose is confirmed and concrete — not when it looks correct, matches a template, or appeared in avail