user-input-protocol

What this skill does

# User Input Protocol

**Version:** 1.0.0
**Portability:** High

---

## Objective

Defines a pattern for subagents (background tasks, delegated agents) to request user input when they cannot directly call AskUserQuestion.

**Purpose:** Enable long-running or background agents to ask clarifying questions without failing or making assumptions.

**Scope:**
- **Included:** Pause pattern, state preservation, question format, resumption workflow
- **Excluded:** Specific checkpoint implementations (framework-dependent)

---

## Core Principles

### Principle 1: Subagents Cannot Directly Ask Questions

**The Problem:** In most agent frameworks, only the main conversation can call AskUserQuestion. Subagents (background tasks, delegated agents) attempting to call it will fail.

**Why this matters:** Long-running agents often hit decision points requiring user input. Without a pattern, they must either guess (bad) or fail (wasteful).

**How to apply:**
- Accept that subagents have limited tools
- Design a pause-and-resume pattern instead of direct calls
- Use the main conversation as an intermediary

**Example:**
```
# Agent framework limitation
Main Conversation: CAN call AskUserQuestion ✓
Subagent (background): CANNOT call AskUserQuestion ✗

# Solution
Subagent pauses → Main conversation asks → Subagent resumes
```

### Principle 2: Save State Before Pausing

**The Principle:** Before requesting input, save all necessary context so work can resume seamlessly.

**Why this matters:** Session restarts lose conversation history. State preservation ensures no wasted work redoing analysis.

**How to apply:**
1. Document what you've done so far
2. Save references to files created/read
3. Store the specific decision pending
4. Preserve enough context to continue without re-analyzing

**Example (Framework-Agnostic):**
```
State to preserve:
- Task description and progress
- Files created: [auth_test.rs, auth.rs]
- Files analyzed: [user.rs, session.rs]
- Decision needed: "Should Email validation be strict or lenient?"
- Context: "Found 3 different email patterns in existing code"
```

### Principle 3: Structured Question Format

**The Principle:** Use a consistent, structured format for questions that includes context, options, and constraints.

**Why this matters:** Ad-hoc question formats lead to confusion. Structured formats ensure users have enough context to make informed decisions.

**How to apply:**
- Provide context explaining why you're asking
- Offer specific options (2-4 choices)
- Include descriptions explaining each option's implications
- Indicate whether multiple selections are allowed

**Example Format:**
```json
{
  "context": "Why you're asking this question",
  "question": "The actual question text?",
  "options": [
    {
      "label": "Option A",
      "description": "What this means and its implications"
    },
    {
      "label": "Option B",
      "description": "What this means and its implications"
    }
  ],
  "multiSelect": false
}
```

### Principle 4: Clean Resumption

**The Principle:** When resuming with the user's answer, retrieve saved state and continue seamlessly without redoing work.

**Why this matters:** Users expect agents to remember what they were doing. Redoing analysis wastes time and creates frustration.

**How to apply:**
1. Retrieve saved state (checkpoint, task metadata, etc.)
2. Load files you were working on
3. Read the user's answer
4. Continue immediately from where you paused

**Example:**
```
# Bad: Restart from scratch
"Let me re-analyze all the code to understand the problem again..."

# Good: Resume cleanly
"You chose Option A (strict email validation). Continuing implementation..."
```

---

## Constraints and Boundaries

### DO:
- Save comprehensive state before pausing (all context needed to resume)
- Provide clear context explaining why you need input
- Offer specific options with clear descriptions
- Indicate you're pausing and waiting for input
- Resume cleanly using saved state

### DON'T:
- Assume you can call AskUserQuestion from a subagent (you can't)
- Pause without saving state (context will be lost)
- Ask vague questions without options ("What should I do?")
- Make assumptions when user input is actually needed
- Redo analysis when resuming (use saved state)

**Rationale:** This pattern bridges the gap between subagent limitations and user interaction needs while preserving work and context.

---

## Usage Patterns

### Pattern 1: Background Agent Needs Clarification

**Scenario:** Long-running mutation testing agent finds surviving mutants and needs to know whether to create individual tasks.

**Approach:**
1. Pause current work
2. Save state (mutant details, progress so far)
3. Format question with specific options
4. Signal pause to main conversation
5. Main conversation asks user via AskUserQuestion
6. Main conversation resumes agent with answer
7. Agent retrieves state and continues

**Example (Conceptual):**
```
# Step 1: Agent pauses
Save state:
- Feature: user-authentication
- Progress: Mutation testing complete, 97% score
- Pending decision: 3 surviving mutants found
- Mutant details: [file:line details for each]

# Step 2: Agent signals
Output: PAUSED_FOR_INPUT
Question: "Found 3 surviving mutants. Create individual fix tasks?"
Options: ["Yes - create tasks", "No - just report"]

# Step 3: Main conversation intermediates
(Main conversation detects pause, calls AskUserQuestion)
User answer: "Yes - create tasks"

# Step 4: Agent resumes
Retrieve state → Read mutant details → Create 3 tasks → Complete
```

### Pattern 2: Domain Agent Encounters Ambiguous Business Rule

**Scenario:** Domain modeling agent finds conflicting patterns in existing code and needs business rule clarification.

**Approach:**
1. Document the conflict found
2. Save analysis of both patterns
3. Ask user which is correct
4. Resume and apply the chosen rule

**Example:**
```
State:
- Analyzing: Email validation logic
- Found: Two patterns
  - Pattern A: Strict RFC 5322 compliance (auth module)
  - Pattern B: Lenient validation (signup module)
- Decision: Which pattern should be standard?

Question: "Found two email validation approaches. Which should be canonical?"
Options:
  - "Strict RFC 5322 (more secure, may reject valid emails)"
  - "Lenient (more permissive, may accept invalid emails)"
  - "Keep both (context-dependent)"
```

### Pattern 3: Code Reviewer Needs Architectural Decision

**Scenario:** Code review agent finds architectural inconsistency and needs to know preferred approach.

**Approach:**
1. Document the inconsistency
2. Present the tradeoffs
3. Ask for preferred direction
4. Resume and apply feedback

---

## Integration with Other Skills

**Works well with:**
- **debugging-protocol:** When debugging reveals ambiguous root cause, pause and ask user
- **tdd-constraints:** When test requirements are unclear, pause and clarify acceptance criteria
- **orchestration-protocol:** Main orchestrator detects pauses and manages user interaction

**Prerequisites:**
- Framework must support agent resumption (continuing with full context)
- State preservation mechanism (checkpoints, task metadata, or similar)
- Main conversation can spawn and resume subagents

---

## Common Pitfalls

### Pitfall 1: Trying to Call AskUserQuestion from Subagent

**Problem:** Subagent attempts direct tool call and fails

**Solution:** Accept the limitation. Use pause-and-resume pattern instead.

### Pitfall 2: Pausing Without State Preservation

**Problem:** Agent pauses but doesn't save context. On resumption, starts over.

**Solution:** Always save comprehensive state before signaling pause. Test resumption to verify no work is lost.

### Pitfall 3: Vague Questions Without Options

**Problem:** "What should I do about this?" with no context or choices

**Solution:** Provide specific context, clear options with descriptions, and enough information for user to decide.

### Pitfall 4: Assuming Answer Format

**Problem:** Agent assume