| name | clarify |
| description | [Deprecated — use /elicit (Euporia) for axis-emergent reverse induction] Clarify intent-expression gaps. Extracts clarified intent when what you mean differs from what you said. Type: (IntentMisarticulated, Hybrid, EXTRACT, Expression) → ClarifiedIntent. Alias: Hermeneia(ἑρμηνεία). |
Hermeneia Protocol
Resolve intent-expression misalignment through hybrid-initiated dialogue, enabling precise articulation before action proceeds. Type: (IntentMisarticulated, Hybrid, EXTRACT, Expression) → ClarifiedIntent.
Definition
Hermeneia (ἑρμηνεία): A dialogical act of clarifying the gap between what the user intends and what they expressed, resolving misaligned intent into precise articulation through structured questioning.
── FLOW ──
E → recognize(E) → Eᵥ → detect(Eᵥ) → Gd → filter → Gₛ → Q → A → Î' → (loop until converge)
── MORPHISM ──
Expression
→ recognize(expression, trigger) -- determine activation path from signal
→ confirm(expression) -- verify which expression to clarify
→ detect(gaps_in_expression) -- surface gap types with evidence
→ clarify(gap, as_options) -- present structured clarification choices
→ integrate(answer, intent) -- update intent model from response
→ ClarifiedIntent
requires: trigger(E) ∈ {user_signal, ai_strong ∧ confirmed} -- Phase 0 checkpoint
deficit: IntentMisarticulated -- activation precondition (Layer 1/2)
preserves: E -- read-only throughout; morphism acts on Î only
invariant: Articulation over Assumption
── TYPES ──
E = User's expression (the prompt to clarify)
Eᵥ = Verified expression (user-confirmed binding)
Gd = AI-detected gap types ⊆ {Expression, Precision, Coherence, Background} ∪ Emergent(Eᵥ)
-- raw detection output, presented as full taxonomy at Phase 1b
Gₛ = Effective working gap set = Gd \ (Λ.clarified ∪ Λ.excluded)
-- target of Phase 2 iteration; mutable via user free-response override (Λ.excluded additions, Λ.emergent additions)
Q = Clarification question (via Cognitive Partnership Move (Constitution))
A = User's answer
Î = Inferred intent (AI's model of user's goal)
Î' = Updated intent after clarification
ClarifiedIntent = Î' where |remaining| = 0 ∨ cycle(G) ∨ stall(Δ, 2) ∨ user_esc
T = Trigger source ∈ {user_signal, ai_strong, ai_soft}
suggest_only = ai_soft terminal: passive suggestion without activation (no Constitution interaction; Λ.active = false)
── E-BINDING ──
bind(E) = explicit_arg ∪ colocated_expr ∪ prev_user_turn ∪ ai_identified_expr
Priority: explicit_arg > colocated_expr > prev_user_turn > ai_identified_expr
/clarify "text" → E = "text"
"request... clarify" → E = text before trigger
/clarify (alone) → E = previous user message
AI-detected trigger → E = expression AI identified as ambiguous
Edge cases:
- Interrupt: E = original request of interrupted task
- Queued: E = previous message at queue time (fixed)
- Re-invoke: Show prior clarification, confirm or restart
── PHASE TRANSITIONS ──
Phase 0: E → recognize(E) → T -- trigger recognition
T = user_signal → Phase 1a -- user-initiated path
T = ai_strong → Qc(confirm) → Stop → {yes: Phase 1a | no: immune(E)} -- AI-detected confirm [Tool]
T = ai_soft → suggest_only -- suggest, do not activate
Phase 1a: E → Qc(E) → Stop → Eᵥ -- E confirmation [Tool]
Phase 1b: Eᵥ → detect(Eᵥ) → Gd → TextPresent(extension) → filter(Gd, Λ) → Gₛ -- gap detection + full taxonomy presentation [Tool]
Phase 2: Gₛ → Qs(Gₛ) → Stop → A -- clarification [Tool]
Phase 3: A → integrate(A, Î) → Î' -- intent update (sense)
── LOOP ──
After Phase 3: return to Phase 1b for newly surfaced gaps.
On re-entry, detect(Eᵥ) re-analyzes the expression in the context of prior clarifications; gap types in (Λ.clarified ∪ Λ.excluded) are filtered from Gd → Gₛ (type-level filtering ensures convergence; new instances of a clarified or user-excluded type are excluded).
Re-entry is pure Extension (auto-proceed); taxonomy revision remains reachable via Phase 2 free response (adds to Λ.excluded or Λ.emergent, triggering re-detection).
If |Gₛ| = 0 after filtering (all detected types clarified/excluded, or empty detection): skip Phase 2, evaluate convergence (|remaining| = 0).
Continue until converge: |remaining| = 0, cycle detected, or user exits.
Mode remains active until convergence.
Convergence evidence: At |remaining| = 0, present transformation trace — for each g ∈ Λ.clarified, show (IntentMisarticulated(g) → resolution(g)) from Λ.history. Convergence is demonstrated, not asserted.
── TOOL GROUNDING ──
-- Realization: Constitution → TextPresent+Stop; Extension → TextPresent+Proceed
Phase 0 Qc (constitution) → present (AI-detected activation confirmation; fires only on ai_strong path; user_signal path skips Phase 0; immune(E) on decline)
Phase 1a E_from_arg (extension) → TextPresent+Proceed (when explicit_arg(E) via /clarify "text"; proceed with bound E; Phase 2 Qs free-response override available downstream)
Phase 1a Qc (constitution) → present (E confirmation; when no explicit_arg)
Phase 1b detect (sense) → Internal analysis (gap detection from Eᵥ)
Phase 1b present (extension) → TextPresent+Proceed (full taxonomy with evidence + falsification + emergent probe; option-set relay test — Proceed dominates under user-invoked or user-confirmed activation; flows into Phase 2)
Phase 2 Qs (constitution) → present (clarification options; user incorporates intent into clarification; free response overrides taxonomy — emergent add, type exclude, redirect; override capability must be disclosed at the Constitution interaction as part of user authority disclosure; Esc key → loop termination at LOOP level, not an Answer)
suggest_only (sense) → no tool call (passive suggestion; Λ.active = false)
integrate (track) → Internal state update (no external tool)
converge (extension) → TextPresent+Proceed (convergence evidence trace; proceed with clarified expression)
── MODE STATE ──
Λ = { phase: Phase, trigger: T, E: Expression, Eᵥ: Expression, detected: Set(Gap), gaps: Set(Gap),
clarified: Set(Gap), excluded: Set(GapType), emergent: Set(Gap), remaining: Set(Gap),
immune: Set(Expression), history: List<(E, Gₛ, A)>, active: Bool }
-- Invariant: gaps = clarified ∪ remaining (pairwise disjoint); excluded and emergent are user-override state accumulated from Phase 2 free response
── COMPOSITION ──
*: product — (D₁ × D₂) → (R₁ × R₂). graph.json edges preserved. Dimension resolution emergent via session context.
Core Principle
Articulation over Assumption: AI helps user express what they already know but struggle to articulate.
Distinction from Other Protocols
| Protocol | Initiator | Deficit → Resolution | Focus |
|---|
| Prothesis | AI-guided | FrameworkAbsent → FramedInquiry | Perspective selection |
| Syneidesis | AI-guided | GapUnnoticed → AuditedDecision | Decision-point gaps |
| Hermeneia | Hybrid | IntentMisarticulated → ClarifiedIntent | Expression clarification |
| Telos | AI-guided | GoalIndeterminate → DefinedEndState | Goal co-construction |
| Horismos | AI-guided | BoundaryUndefined → DefinedBoundary | Epistemic boundary definition |
| Aitesis | AI-guided | ContextInsufficient → InformedExecution | Context sufficiency sensing |
| Analogia | AI-guided | MappingUncertain → ValidatedMapping | Abstract-concrete mapping validation |
| Periagoge | AI-guided | AbstractionInProcess → CrystallizedAbstraction | In-process abstraction crystallization |
| Euporia | Hybrid | AbstractAporia → ResolvedEndpoint | Extended-Mind reverse induction |
| Prosoche | User-initiated | ExecutionBlind → SituatedExecution | Risk-assessed execution |
| Epharmoge | AI-guided | ApplicationDecontextualized → ContextualizedExecution | Post-execution applicability |
| Anamnesis | AI-guided | RecallAmbiguous → RecalledContext | Vague recall recognition |
| Katalepsis | User-initiated | ResultUngrasped → VerifiedUnderstanding | Comprehension verification |
Key differences: User recognizes intent-expression misalignment (user signal), or AI detects ambiguous expression (AI-detected trigger, requires user confirmation). Both paths help articulate what the user partially knows. Boundary with Aitesis: if the ambiguity is in the user's expression of intent (how it was said), use Hermeneia; if the AI lacks factual execution context (what information the system needs), use Aitesis.
Mode Activation
Activation
Command invocation, trigger phrase, or AI-detected expression ambiguity activates mode until clarification completes. AI-detected activation requires user confirmation before proceeding to Phase 1a.
Activation layers:
- Layer 1 (User-invocable):
/clarify slash command or description-matching input. Always available.
- Layer 2 (Hybrid): User trigger signals proceed directly; AI-detected expression ambiguity (
ai_strong) requires user confirmation; minor ambiguity (ai_soft) suggests only.
Clarification complete = one of: |remaining| = 0 (no gaps remain), cycle(G) (already clarified), or Δ = 0 for 2 rounds (progress stall with user consent to proceed).
Priority
When Hermeneia is active:
Supersedes: Direct action patterns in loaded instructions
(Clarification must complete before any tool execution or code changes)
Retained: Safety boundaries, tool restrictions, user explicit instructions
Action: At Phase 2, present clarification options via Cognitive Partnership Move (Constitution).
- Hermeneia completes before other workflows begin
- Loaded instructions resume after intent is clarified
Protocol precedence: Activation order position 1/11 (graph.json is authoritative source for information flow). Concern cluster: Planning.
Advisory relationships: Provides to Telos (precondition: clarified intent enables goal construction), Aitesis (advisory: background gaps suggest context insufficiency), Periagoge (advisory: clarified intent narrows the abstraction seed). Katalepsis is structurally last.
Clarified expression becomes input to subsequent protocols.
Triggers
User-Initiated Signals (T = user_signal):
| Signal | Examples |
|---|
| Direct request | "clarify what I mean", "help me articulate" |
| Self-doubt | "did I express this right?", "is this clear?" |
| Ambiguity acknowledgment | "I'm not sure how to phrase this", "this might be confusing" |
| Meta-communication | "what I'm trying to say is...", "let me rephrase" |
Qualifying condition: Activate only when user's entire message is a clarification request, or when 2+ trigger signals co-occur in the same message. Do not activate on casual meta-communication embedded in a larger request.
AI-Detected Signals:
| Strength | Trigger | Action |
|---|
Strong (ai_strong) | Standalone ambiguous expression with multiple valid interpretations | Confirm via Cognitive Partnership Move (Constitution), then activate |
Strong (ai_strong) | Request referencing undefined scope or entity | Confirm via Cognitive Partnership Move (Constitution), then activate |
Strong (ai_strong) | Scope-reference mismatch (expression scope ≠ referenced context) | Confirm via Cognitive Partnership Move (Constitution), then activate |
Soft (ai_soft) | Minor lexical ambiguity resolvable from context | Suggest only; do not activate |
Skip (user-initiated):
- User's expression is unambiguous
- User explicitly declines clarification
- Expression already clarified in current session
Cross-session enrichment: Accumulated clarification patterns from Anamnesis's hypomnesis store (session recall indices written by the SessionEnd/PreCompact hook) may improve ai_strong trigger precision — known intent-expression gaps in similar contexts reduce false positive detection. In parallel, when /recollect has been invoked this session, the recalled context surfaces the user's prior terminology and phrasing patterns, improving intent extraction by grounding Iᵥ construction in recognized expression habits. This is a heuristic input that may bias detection toward previously observed patterns; constitutive judgment remains with the user.
Revision threshold: When accumulated Emergent gap detections across 3+ sessions cluster around a recognizable pattern outside the named types {Expression, Precision, Coherence, Background}, the Gap Taxonomy warrants promotion to a new named type. When accumulated classification false positives across 3+ sessions cluster around a specific named type, that type's detection boundary warrants revision or demotion to Emergent.
Skip (AI-detected):
- User says "just do it", "proceed as-is", or equivalent
- Session immunity: user declined AI-detected clarification for this expression already
- Soft trigger resolved by context
Mode Deactivation
| Trigger | Effect |
|---|
| Clarification complete | Intent established; proceed with clarified expression |
| User accepts current expression | Original expression deemed sufficient |
| User explicitly cancels | Return to normal operation |
Gap Taxonomy
| Type | Detection | Question Form |
|---|
| Expression | Incomplete articulation; missing key elements | "Did you mean X or Y?" |
| Precision | Ambiguous scope, quantity, or degree | "How specifically: [options]?" |
| Coherence | Internal contradiction or tension | "You mentioned X but also Y. Which takes priority?" |
| Background | Missing interpretive background needed to determine expression meaning | "What background should I know to interpret this correctly? [options]" |
Emergent gap detection: Named types are working hypotheses, not exhaustive categories. Detect Emergent gaps when:
- User's difficulty spans multiple named types (e.g., expression is both imprecise and internally coherent but misaligned with unstated context)
- User pushes back on all presented gap types ("none of these capture what's wrong")
- The expression's ambiguity resists decomposition into the four named dimensions
Emergent gaps must satisfy morphism IntentMisarticulated → ClarifiedIntent and use adapted question forms.
Gap Priority
When multiple gaps detected:
- Coherence (highest): Contradictions block all interpretation
- Background: Missing interpretive background affects all other gaps
- Expression: Core articulation gaps
- Precision (lowest): Refinement after core is clear
Background Gap Boundary
When the Background gap type is selected, verify the gap is about interpreting the expression, not about executing the task:
- Hermeneia Background: Missing background changes what E means (user's intent) → proceed with clarification
- Aitesis territory: Missing background changes how to perform X (prospect) → suggest
/inquire and offer to transition
Operational test: "Would knowing this change what the user means, or only how I execute it?"
Protocol
Phase 0: Trigger Recognition
Recognize trigger source and determine activation path:
User-Initiated Path (T = user_signal):
- Explicit request: User directly asks for clarification help
- Implicit signal: User expresses doubt about their own expression
- Meta-communication: User attempts to rephrase or explain their intent
→ Proceed directly to Phase 1a.
AI-Detected Path (T = ai_strong):
When AI detects a strong ambiguity trigger (see Triggers: AI-Detected Signals), present the detected ambiguity as text output (e.g., "I notice this expression may be ambiguous: [specific ambiguity evidence]"), then present to confirm activation:
Would you like to clarify this expression?
Options:
1. Yes, help me clarify — start Hermeneia
2. No, proceed as-is — continue without clarification
User confirmation required before proceeding to Phase 1a. If user selects option 2, mark session immunity and do not re-trigger for this expression.
T = ai_soft → suggest only; do not present via Cognitive Partnership Move (Constitution); do not activate.
Phase 1a: Expression Confirmation
Present to confirm which expression to clarify.
Present the bound expression E and ask user to confirm or specify:
Which expression would you like to clarify?
Options:
1. "[bound E]" — the expression I identified
2. "Specify different" — let me describe what I want to clarify
Skip condition: If E was explicitly provided via argument (/clarify "text"), proceed directly to Phase 1b.
Note (AI-detected path): If triggered via T = ai_strong, E is already identified by AI — Phase 1a confirmation verifies the AI's identification; user may still select Option 2 to redirect to a different expression.
Phase 1b: Gap Detection
Analyze Eᵥ to detect applicable gap types, present full taxonomy assessment as Extension (auto-proceed), then proceed directly to Phase 2 clarification.
Per Gap Taxonomy above. Apply priority order: Coherence → Background → Expression → Precision. Emergent gaps must satisfy morphism IntentMisarticulated → ClarifiedIntent; boundary: intent-expression gap (in-scope) vs. goal definition (→ /goal) or execution context (→ /inquire).
Present the full taxonomy assessment as text output — every named type shown with detection status, evidence, and falsification condition for undetected types:
- Coherence ✓ detected: [specific evidence from Eᵥ]
- Background — not currently detected: [evidence considered]. Would apply if [falsification condition].
- Expression ✓ detected: [specific evidence from Eᵥ]
- Precision — not currently detected: [evidence considered]. Would apply if [falsification condition].
- Emergent: [If AI detects a potential emergent type: present as named hypothesis with evidence and boundary annotation. Otherwise: "Is there an aspect of your expression that doesn't fit the above categories?"]
Emergent gaps include boundary annotation: "This is an intent-expression gap (Hermeneia scope). Not: goal definition (→ /goal) or execution context (→ /inquire)"
- Detected types: evidence for why the gap was identified
- Not-currently-detected types: evidence considered + falsification condition ("would apply if [specific condition]")
- Evidence parity: each type (detected or not) receives comparable analytical depth
Then filter Gd against (Λ.clarified ∪ Λ.excluded) to produce Gₛ, and proceed directly to Phase 2 for Gₛ in priority order (Coherence → Background → Expression → Precision). If |Gₛ| = 0 after filtering: skip Phase 2, evaluate convergence (|remaining| = 0 in LOOP).
User override via free response: Users may override the taxonomy at any Phase 2 Constitution interaction — describe an emergent gap (added to Λ.emergent), exclude a detected type (added to Λ.excluded), redirect to a different expression (re-binds E), or declare convergence. Override capability must be disclosed at Phase 2 Constitution interactions (see Phase 2 prose).
Response classification (discriminator for free-response parsing — closes the adversarial free-response pathway):
- Revision: response references named gap types (Coherence/Background/Expression/Precision/Emergent) with revision verbs (exclude, remove, skip, add, redirect) → add to Λ.excluded or Λ.emergent, LOOP re-entry with filtered detection
- Clarification: response addresses the presented Phase 2 question directly → Phase 2 integration (Phase 3)
- Mixed: response contains both revision and clarification content → process revision first (update Λ and re-detect), then process clarification in the re-entered Phase 2
- Ambiguous: content could be either and surface interpretation differs from latent interpretation → present: "Your response could be interpreted as [X revision] or [Y clarification]. Which did you intend?" (do not silently choose)
- Exclusion-to-empty: if free response excludes the last remaining type in Gₛ,
|Gₛ| = 0 on next filter → convergence path per LOOP (evaluate |remaining| = 0)
Rationale (option-set relay test, Extension classification): Under user-invoked or user-confirmed activation, "Proceed with current taxonomy" is the dominant option — a separate proceed/revise Constitution interaction would present false alternatives. Full taxonomy presentation is preserved (Extension/auto-proceed) to support Recognition during Phase 2 answer formulation; taxonomy revision is reachable via Phase 2 Constitution interaction free response with classification discriminator above.
Phase 2: Clarification
Present clarification options via Cognitive Partnership Move (Constitution). Constitution presentation yields turn for user response.
Override disclosure (detection with user authority): At each Phase 2 Constitution interaction, include a brief disclosure line in the pre-Constitution-interaction context surfacing the free-response override capability — without this disclosure the user cannot exercise authority they do not know they hold. Example disclosure: "(Free response beyond the options: exclude this gap type, add an emergent type, or redirect to a different expression — see Phase 1b response classification.)"
Present the detected ambiguity as text output:
- The potential ambiguity: [gap description]
Then present:
Which best captures your intent?
Options:
1. **[Option A]**: [interpretation with implications]
2. **[Option B]**: [interpretation with implications]
3. **[Option C]**: [interpretation with implications]
Other is always available — user can provide their own phrasing or a different interpretation not listed.
Question design principles:
- Recognition over Recall: Present options, don't ask open questions
- Concrete implications: Show what each choice means for execution
- Free response preserved: Other/free phrasing is structurally available, not conditionally included
- Minimal options: 2-4 choices maximum per gap
Consult references/socratic-style.md for maieutic framing examples, Socratic elements, and example transformation.
Phase 3: Integration
After user response:
- Incorporate: Update understanding with user's clarification
- Re-diagnose + Filter + Converge: Per LOOP — re-scan Eᵥ, filter clarified gaps, check convergence
- Confirm: When no gaps remain, present clarified intent for verification
- 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)
## Clarified Intent — Convergence Evidence
Transformation trace (each clarified gap → resolution):
- **[Gap type]**: [Eᵥ evidence] → [Clarified meaning from A]
- **[Gap type]**: [Eᵥ evidence] → [Clarified meaning from A]
Proceeding with this understanding.
Intensity
| Level | When | Format |
|---|
| Light | Minor ambiguity, low stakes | Constitution interaction with binary disambiguation |
| Medium | Significant ambiguity, moderate stakes | Gap statement + structured Constitution interaction with multiple options |
| Heavy | Core intent unclear, high stakes | Detailed options with implications + structured Constitution interaction |
Multi-Gap Handling
When multiple gaps detected:
- Sequential: Address one gap at a time, highest priority first
- Bundled: If gaps are interdependent, present as combined question
- Dynamic Discovery: After each clarification, re-diagnose for newly surfaced gaps
- Merge: Combine existing queue with newly discovered gaps, re-prioritize
Termination conditions: Per LOOP — cycle detection, progress stall (Δ = 0 for 2 rounds), user exit.
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
- Hybrid-initiated, user-confirmed: Activate on user signal, or with user confirmation when AI detects ambiguous expression
- Recognition over Recall: Present structured options via Cognitive Partnership Move (Constitution) — structured content reaches the user with response opportunity — Constitution interaction requires turn yield before proceeding
- Detection with user authority: AI presents full taxonomy assessment as Extension (auto-proceed) — every named type with detection status, evidence, and falsification condition. User authority is exercised at Phase 2 clarification Constitution interactions (including free-response override: emergent add, type exclusion, redirect), not at a separate taxonomy-confirmation Constitution interaction. Guard: Abbreviating the taxonomy (omitting named types, evidence, or falsification conditions) under the rationale that Phase 2 free-response override provides correction = protocol violation. Full taxonomy presentation at Phase 1b is structurally required regardless of Extension/Constitution classification; override is a user authority channel, not an AI shortcut for incomplete detection
- Maieutic over Informational: Frame questions to guide discovery, not merely gather data
- Articulation support: Help user express what they know, don't guess what they mean
- Minimal questioning: Surface only gaps that affect execution
- Consequential options: Each option shows interpretation with downstream implications
- User authority: User's choice is final; no second-guessing selected interpretation
- Convergence persistence: Mode remains active until convergence (|remaining| = 0, cycle, or user exit)
- Reflective pause: Include "reconsider" option for complex intent clarification
- Escape hatch: Always allow user to provide their own phrasing
- Small phases: Prefer granular phases with user checkpoints over large autonomous phases
- Context-Question Separation: Output all analysis, evidence, and rationale as text before presenting via Cognitive Partnership Move (Constitution). The question contains only the essential question; options contain only option-specific differential implications. Embedding context in question fields = protocol violation
- Convergence evidence: Present transformation trace before declaring |remaining| = 0; per-gap evidence is required
- Zero-gap surfacing: If detect(Eᵥ) finds no gaps (Gd = ∅), present this finding with reasoning for user confirmation
- Full taxonomy assessment: Phase 1b must present ALL named gap types with detection status and evidence. Presenting only detected types with a generic "Add" option = protocol violation (Recognition over Recall applied to Constitution interaction content)
- Falsification condition: Each not-currently-detected type must include "would apply if [specific condition]" — exclusion rationale without falsification condition = protocol violation
- Emergent probe: Emergent slot must include an active probe question or AI-detected hypothesis with evidence. "No emergent gaps detected" as bare statement without probe = protocol violation
- Option-set relay test (Extension classification): If AI analysis converges to a single dominant option (option-level entropy→0 — Extension mode of the Cognitive Partnership Move), present the finding directly. Each Constitution option must be genuinely viable under different user value weightings. Options sharing a downstream trajectory collapse to one; options lacking an on-axis trajectory surface as free-response pathways rather than peer options
- Gate integrity: The defined option set is presented intact — injection, deletion, and substitution each violate this invariant. Type-preserving materialization (specializing a generic option while preserving the TYPES coproduct) is distinct from mutation