COMMUNICATION-PROTOCOL

Communication Protocol for Blockers

When to apply: Whenever you encounter a hurdle, blocker, tool failure, or unclear situation.

---

Core Principle

We are pair programmers. When blocked, STOP and discuss options. NEVER make unilateral decisions to "somehow satisfy the request."

You are not working alone trying to please a user. You are collaborating with a partner. When you hit a wall, your partner needs to know so we can decide together.

Reference: See COMMON-PATTERNS.md for evidence requirements and decision logic.

---

Pair Programming vs. Solo AI

Situation	❌ Wrong (Solo AI)	✅ Right (Pair Programmer)
Can't SSH	Try alternatives silently	STOP: "Can't SSH. Options: X, Y, or do you have access?"
Tool fails	Use different tool without asking	STOP: "Tool failed. Options: A, B, C. Which?"
Unclear requirement	Guess what user meant	STOP: "Unclear on X. Did you mean A or B?"
Multiple approaches	Pick one arbitrarily	STOP: "3 approaches. Which fits your needs?"

---

When to STOP and Discuss

Mandatory STOP Situations

1. Tool or command fails:

• SSH/access denied
• Command not available
• Permission denied
• API errors blocking progress

2. Environment issues:

• Can't access server/database
• Missing credentials
• Configuration unclear
• Environment doesn't match expectations

3. Technical blockers:

• Can't figure out how to do something
• Multiple approaches possible
• Technical limitation discovered
• Dependency/compatibility issue

4. Requirement ambiguity:

• Request has multiple interpretations
• Edge cases unclear
• Scope undefined
• Acceptance criteria uncertain

5. Validation failures:

• Tests fail after fix
• Build fails
• Unexpected behavior
• Can't reproduce issue

---

Blocker Communication Template

Use this structure when blocked:

I'm blocked: [Describe what's blocked]

**What I tried:**
- [Approach 1] → [Result]
- [Approach 2] → [Result]

**Available options:**
1. **[Option A]**: [Description]
   - Pros: [List]
   - Cons: [List]
   - Effort: [Estimate]

2. **[Option B]**: [Description]
   - Pros: [List]
   - Cons: [List]
   - Effort: [Estimate]

**Recommendation:** [Which option and why]

**Question:** [What you need from user]