tractatus/docs/governance/INST_095_QA_TRACKING_DRAFT.md

# inst_095: Question Tracking and Clarification Protocol

**Created**: 30 October 2025  
**Status**: Draft for Integration  
**Purpose**: Prevent missed questions in both User→Claude and Claude→User communications

---

## Problem Statement

Two recurring patterns create communication gaps:

1. **User Questions Missed by Claude**: In busy prompts with multiple tasks, Claude sometimes proceeds with tasks while ignoring explicit questions posed by the user.

2. **Claude Questions Missed by User**: User sometimes forgets to answer questions posed by Claude, either in terminal responses or in plan documentation.

**Impact**: Missed questions lead to:
- Incorrect assumptions
- Work proceeding on wrong premises
- Repeated clarification cycles
- Frustration and inefficiency

---

## Instruction Specification

### inst_095: Question Tracking and Clarification Protocol

**Classification**:
```json
{
  "id": "inst_095",
  "text": "Track all questions in both directions (User→Claude and Claude→User). At end of each interaction, verify all questions have been addressed. Issue explicit alert if question remains unanswered. Apply to terminal interactions and documentation.",
  "quadrant": "OPERATIONAL",
  "persistence": "HIGH",
  "temporal_scope": "PERMANENT",
  "verification_required": "REQUIRED",
  "explicitness": 0.92,
  "source": "user_instruction",
  "parameters": {
    "tracking_scope": ["terminal", "documentation", "plan_mode"],
    "alert_threshold": "immediate",
    "question_types": ["explicit_query", "clarification_request", "decision_point"],
    "exempt_patterns": ["rhetorical_question"]
  },
  "active": true
}
```

---

## Operational Protocol

### 1. Question Detection

**Explicit Questions** (Always Track):
- Sentences ending with "?"
- Statements prefixed with "Question:", "Can you...", "Should we...", "What about..."
- Decision requests: "Which approach?", "Option A or B?"
- Clarification requests: "Please clarify...", "What do you mean by..."

**Implicit Questions** (Context-Dependent):
- "I'm not sure if..." (implies: "Can you confirm?")
- "It's unclear whether..." (implies: "Please clarify")
- "We could do X or Y" (implies: "Which should we choose?")

**Exempt** (Do Not Track):
- Rhetorical questions (obvious context)
- Questions immediately answered in same message
- Hypothetical scenario questions with no decision needed

### 2. Tracking Mechanism

**During Interaction**:
```
CLAUDE INTERNAL CHECKLIST:
□ User asked question 1: [topic] - Status: [Answered/Pending]
□ User asked question 2: [topic] - Status: [Answered/Pending]
□ I asked question A: [topic] - Status: [User answered/Pending]
□ I asked question B: [topic] - Status: [User answered/Pending]
```

**At End of Response**:
- Count questions detected
- Verify all marked as "Answered" or explicitly deferred
- If any "Pending": Issue alert

### 3. Alert Protocol

**Format** (When Question Unanswered):

```
⚠️ UNANSWERED QUESTION DETECTED

[User→Claude] or [Claude→User]

Question: [exact text of question]

Context: [where question appeared - prompt line X, plan section Y, etc.]

Action Required:
- [For Claude] I will pause and answer this question before proceeding
- [For User] Please provide response, or explicitly mark as "defer" or "not applicable"

Proceeding without answer may result in incorrect assumptions.
```

**When to Issue Alert**:
- **Immediately** if question is decision-critical (blocks progress)
- **End of response** if question is informational (doesn't block)
- **Start of next session** if question spans sessions (via session state)

### 4. Busy Prompt Handling

**Special Case**: User sends prompt with:
- Multiple tasks AND
- One or more questions embedded

**Protocol**:
1. Parse prompt for both tasks and questions
2. BEFORE starting tasks, acknowledge questions detected
3. Either answer questions immediately OR state "will address after [task X]"
4. Never proceed with all tasks while ignoring questions

**Example**:

```
User: "Update the architecture page and also can you explain why 
we need the gradient principle? Also fix the typo in values.html"

Claude Response:
✓ Detected tasks: 1) Update architecture page, 2) Fix typo in values.html
✓ Detected question: "Why do we need the gradient principle?"

I'll answer your question first:
[Explanation of gradient principle...]

Now proceeding with tasks:
1. Updating architecture page...
```

### 5. Documentation Questions

**In Plan Mode** or **Design Documents**:
- Questions marked as "TO BE ANSWERED:" or "USER INPUT NEEDED:"
- Track in session state
- Flag at start of each subsequent interaction until resolved

**Example Session State Addition**:
```json
{
  "pendingQuestions": [
    {
      "id": "q_001",
      "question": "Should we use Option A or Option B for deployment?",
      "askedBy": "claude",
      "context": "deployment-plan.md line 45",
      "timestamp": "2025-10-30T12:00:00Z",
      "status": "pending"
    }
  ]
}
```

### 6. Cross-Session Persistence

**Problem**: Questions asked at end of session may be forgotten by next session.

**Solution**:
- session-init.js checks for pendingQuestions in session state
- Displays at start: "⚠️ 2 questions from previous session require response"
- User must address or explicitly defer

---

## Verification Checklist

Before completing any response, verify:

1. ✓ All questions in user's prompt detected
2. ✓ All questions answered OR explicitly acknowledged with timeline
3. ✓ Any questions I'm asking user are clearly marked
4. ✓ Decision-critical questions prioritized
5. ✓ If question deferred, documented reason and timeline

---

## Examples

### Example 1: Missed Question in Busy Prompt

**❌ Current Behavior (Bad)**:
```
User: "Deploy to production and what's the rollback plan? Also update docs"
Claude: [Proceeds with deployment and doc update, ignores rollback question]
```

**✅ With inst_095 (Good)**:
```
User: "Deploy to production and what's the rollback plan? Also update docs"
Claude: "⚠️ Question detected: 'What's the rollback plan?'
I'll answer this before proceeding with deployment:

Rollback plan:
1. [detailed plan...]

Now that rollback is clear, proceeding with:
1. Deployment to production
2. Documentation updates"
```

### Example 2: User Forgets to Answer Claude's Question

**❌ Current Behavior (Bad)**:
```
Claude: "Should I use approach A or B for this feature?"
User: [Next session] "Please continue with the feature"
Claude: [Guesses approach, possibly wrong]
```

**✅ With inst_095 (Good)**:
```
Claude: "Should I use approach A or B for this feature?"
[Session ends]
[Next session - session-init.js loads]

⚠️ UNANSWERED QUESTION FROM PREVIOUS SESSION:
Question: "Should I use approach A or B for this feature?"
Asked: 2025-10-30 19:00
Status: Pending (22 hours)

User: "Use approach B"
Claude: "✓ Question resolved. Proceeding with approach B..."
```

### Example 3: Rhetorical Question (Exempt)

```
User: "Isn't it great that the framework works so well?"
Claude: [Recognizes as rhetorical, does not track as pending question]
```

---

## Integration with Existing Framework

**Complements**:
- **inst_078** (Framework audit responses): Q&A tracking ensures audit questions get answered
- **inst_082** (Framework statistics): Could add "pending questions" to stats
- **Session management**: Integrates with session-init.js and session state

**MetacognitiveVerifier Role**:
- Verify Q&A protocol followed during multi-step operations
- Flag if Claude proceeds with assumptions without confirming questions answered

**ContextPressureMonitor Role**:
- Elevated pressure = increased question-tracking rigor
- At HIGH/CRITICAL pressure, mandatory question resolution before task execution

---

## Success Criteria

**Quantitative**:
- Zero instances of work proceeding with unanswered decision-critical questions
- <5% of informational questions going unanswered beyond one message cycle
- 100% of cross-session questions surfaced at session start

**Qualitative**:
- User reports reduced frustration from missed questions
- Fewer clarification cycles and rework
- Improved decision accuracy (no guessing on unclear requirements)

---

## Risks and Limitations

**Risk 1: Over-Tracking Noise**
- Mitigation: Exempt rhetorical questions, use context to distinguish
- Allow user to say "just proceed, assume X" to bypass tracking

**Risk 2: Alert Fatigue**
- Mitigation: Distinguish critical (blocks progress) vs informational (doesn't block)
- Use clear formatting to make alerts scannable

**Risk 3: Ambiguous Questions**
- Mitigation: If question ambiguous, ask for clarification rather than guessing
- Mark as "needs clarification" rather than "answered"

---

## Implementation Notes

**Technical Approach**:
1. Add question tracking to session state JSON
2. Enhance session-init.js to display pending questions
3. MetacognitiveVerifier integration for verification
4. No new service needed - operational protocol for Claude to follow

**Timeline**:
- Integration: Immediate (inst_095 added to instruction-history.json)
- Session state enhancement: Week of 4 November
- Effectiveness monitoring: Ongoing

---

**Document Status**: Ready for Integration  
**Next Step**: Add to instruction-history.json as inst_095  
**Version**: Framework 4.3 → 4.4 (if adopted)