---

name: hermeneia description: Clarify intent-expression gaps. Transforms known unknowns into known knowns when what you mean differs from what you said. user-invocable: true

Hermeneia Protocol

Transform known unknowns into known knowns by clarifying intent-expression gaps through user-initiated dialogue, enabling precise articulation before action proceeds.

Definition

Hermeneia (ἑρμηνεία): A dialogical act of clarifying the gap between what the user intends and what they expressed, transforming recognized ambiguity into precise articulation through structured questioning.

Copy── FLOW ──
E → G → Q → A → Î'

── TYPES ──
E  = User's expression (the prompt to clarify)
G  = Detected gaps ∈ {Expression, Precision, Coherence, Context}
Q  = Clarification question (via AskUserQuestion)
A  = User's answer
Î  = Inferred intent (AI's model of user's goal)
Î' = Updated intent after clarification

── PHASE TRANSITIONS ──
Phase 0: E → recognize(E) → trigger?             -- trigger recognition
Phase 1: E → diagnose(E) → G                     -- gap detection (internal)
Phase 2: G → Q[AskUserQuestion](G) → await → A   -- Q: extern
Phase 3: A → integrate(A, Î) → Î'                -- intent update (internal)

── LOOP ──
After Phase 3: re-diagnose for newly surfaced gaps.
Continue if progress; terminate on cycle, stall, or no gaps.

── TOOL GROUNDING ──
Q (extern)     → AskUserQuestion tool (mandatory; Escape → cancel)
diagnose       → Internal analysis (no external tool)
integrate      → Internal state update (no external tool)

── MODE STATE ──
Λ = { phase: Phase, gaps: Set(Gap), clarified: Set(Gap), active: Bool }

Core Principle

Articulation over Assumption: AI helps user express what they already know but struggle to articulate.

Distinction from Other Protocols

Key difference: User already recognizes ambiguity exists (known unknown). Hermeneia helps articulate what user already partially knows.

Mode Activation

Activation

Command invocation or trigger phrase activates mode until clarification completes.

Clarification complete = one of: |G| = 0 (no gaps remain), cycle(G) (already clarified), or Δ = 0 for 2 rounds (progress stall with user consent to proceed).

Priority

Supersedes: Direct action patterns in User Memory (Clarification must complete before any tool execution or code changes)

Retained: Safety boundaries, tool restrictions, user explicit instructions

Action: At Phase 2, call AskUserQuestion tool to present clarification options.

• Hermeneia completes before other workflows begin
• User Memory rules resume after intent is clarified

Protocol precedence (triple-activation order): Hermeneia → Prothesis → Syneidesis

Clarified expression becomes input to subsequent protocols.

Triggers

Skip:

• User's expression is unambiguous
• User explicitly declines clarification
• Expression already clarified in current session

Mode Deactivation

Gap Taxonomy

Gap Priority

When multiple gaps detected:

1. Coherence (highest): Contradictions block all interpretation
2. Context: Missing background affects all other gaps
3. Expression: Core articulation gaps
4. Precision (lowest): Refinement after core is clear

Protocol

Phase 0: Trigger Recognition

Recognize user-initiated clarification request:

1. Explicit request: User directly asks for clarification help
2. Implicit signal: User expresses doubt about their own expression
3. Meta-communication: User attempts to rephrase or explain their intent

Do not activate for AI-perceived ambiguity alone. User must signal awareness of potential gap.

Phase 1: Diagnosis (Silent)

Analyze user's expression for intent-expression gaps:

1. Parse expression: Identify stated elements and structure
2. Detect gaps: Check taxonomy against expression
3. Prioritize: Order gaps by priority (Coherence > Context > Expression > Precision)
4. Select: Choose highest-priority gap for clarification

Phase 2: Clarification

Call the AskUserQuestion tool to present clarification options.

Do NOT present clarification as plain text. The tool call is mandatory—text-only presentation is a protocol violation.

CopyI notice potential ambiguity in your request:

[Gap description]

Options:
1. **[Option A]**: [interpretation with implications]
2. **[Option B]**: [interpretation with implications]
3. **[Option C]**: [interpretation with implications]

Which best captures your intent?

Question design principles:

• Recognition over Recall: Present options, don't ask open questions
• Concrete implications: Show what each choice means for execution
• Escape hatch: Include "something else" option when appropriate
• Minimal options: 2-4 choices maximum per gap

Socratic Questioning Style

Hermeneia transforms known unknowns → known knowns. The user already possesses the knowledge; they struggle to articulate it. Apply maieutic questioning (Socratic midwifery) to help users "give birth" to their own intent.

Maieutic framing for AskUserQuestion:

Instead of:

CopyOptions:
1. Option A: [interpretation]
2. Option B: [interpretation]

Use consequential framing:

CopyOptions:
1. Option A: [interpretation] — if this, then [implication for your goal]
2. Option B: [interpretation] — if this, then [implication for your goal]
3. "Let me reconsider" — take time to reflect on underlying intent

Socratic elements:

Example transformation:

Before (standard):

CopyDid you mean:
1. Delete all files
2. Delete only selected files

After (Socratic):

CopyTo clarify your intent:
1. "All files" — this would clear the workspace entirely; is starting fresh your goal?
2. "Selected files" — this preserves structure; is targeted cleanup your goal?
3. "Let me reconsider" — reflect on what outcome you're actually seeking

Principle: Questions guide discovery, not merely gather information

Phase 3: Integration

After user response:

1. Incorporate: Update understanding with user's clarification
2. Re-diagnose: Scan clarified expression for newly surfaced gaps
3. Filter: Exclude gaps already resolved in this session
4. Progress check: Continue only if progress(Î, Î') = true (no cycle, Δ > 0)
5. Confirm: When no gaps remain, present clarified intent for verification
6. Proceed: Continue with clarified expression

Discovery triggers:

• Clarification reveals new ambiguity ("I mean the API" → "which endpoint?")
• Answer creates new tension ("fast" + "thorough" → coherence gap)
• Context shift ("for production" → new precision requirements)

Copy## Clarified Intent

Based on your clarification:
- [Original expression element] → [Clarified meaning]
- [Ambiguous element] → [Resolved interpretation]

Proceeding with this understanding.

Intensity

Multi-Gap Handling

When multiple gaps detected:

1. Sequential: Address one gap at a time, highest priority first
2. Bundled: If gaps are interdependent, present as combined question
3. Dynamic Discovery: After each clarification, re-diagnose for newly surfaced gaps
4. Merge: Combine existing queue with newly discovered gaps, re-prioritize

Termination conditions (Hybrid strategy):

• Cycle detection: Same gap signature already in History → terminate
• Progress stall: Δ = 0 for 2 consecutive rounds → offer rephrase
• User exit: Esc/interrupt always available (Claude Code native)

Gap queue limit: Max 4 gaps queued at any time (drop lowest priority if exceeded)

On termination:

• Summarize current understanding
• Ask user to rephrase if stuck
• Proceed with best interpretation if user approves

Rules

1. User-initiated only: Activate only when user signals awareness of ambiguity
2. Recognition over Recall: Always call AskUserQuestion tool to present options (text presentation = protocol violation)
3. Maieutic over Informational: Frame questions to guide discovery, not merely gather data
4. Articulation support: Help user express what they know, don't guess what they mean
5. Minimal questioning: Surface only gaps that affect execution
6. Consequential options: Each option shows interpretation with downstream implications
7. User authority: User's choice is final; no second-guessing selected interpretation
8. Session Persistence: Mode remains active until clarification completes
9. Reflective pause: Include "reconsider" option for complex intent clarification
10. Escape hatch: Always allow user to provide their own phrasing