Version. 0.1
Date. 2026-05-11
Status. Forward-looking design-space scoping. Drafted by Claude.ai. Operator: Marvin Percival. Companion to loomworks-phase-56-scoping-note-v0_3.md. Not a Phase 56 deliverable; input to future phase scoping.
A scoping document for the explain affordance — the recovery surface for comprehension gaps that survive plain-terms-discipline on Loomworks product surfaces. Surfaces the design space without committing to a particular shape. Preserves alternatives. Inputs to a future phase (likely Phase 57+) where the affordance's first trigger mode gets scoped and built.
The principle this affordance instantiates is discipline-plus-recovery — plain-terms-discipline reduces comprehension-gap incidence; an explain affordance handles the irreducible residue. The principle is named in docs/voice-principles-v0_1.md (authored at Phase 56 Step 1) with forward-reference to this document.
Phase 55 shipped the conversational engagement creation surface. Phase 56 scopes voice work on that surface: per-field elicitation prompts authored in plain language; terminal-turn affordance language revised. The discipline reduces the chance that an Operator hits a Companion question whose vocabulary they don't share.
But discipline doesn't eliminate the gap. Even with plain language, an Operator can encounter a question where the concept is unfamiliar. The Companion may ask "what should this sound like — what should someone feel when they read it" in plain words, and the Operator may still not be sure how to answer. The vocabulary is not the issue; the what-is-being-asked is. That residue is what the explain affordance addresses.
The Operator surfaced this during Phase 56 scoping: "I can see from this finding that the interface with the operator is going to need an 'explain' option, as everyone may not fully understand the response or request from the Companion. The explanation could be via voice or on form button."
The observation is correct in principle and reaches beyond Phase 56's scope. Phase 56 names the principle; this investigation scopes the affordance's design space; a future phase builds it.
The Operator's framing identified two ways to trigger an explain request: spoken aloud, or via a form button. These are distinct affordances with different substrate dependencies, but they both route to the same composition path. The affordance is one concept; the trigger paths differ.
The Operator clicks an "explain" affordance attached to a Companion message. The Companion composes an inline explanation; the explanation renders in the conversational surface (either as a new Companion message, an inline-expandable panel, or a modal — surface options below).
Substrate dependencies. None beyond Phase 55's text-conversation surface. The button is a UI element on the OL converse view; the explanation composition path runs through the existing Companion dispatch.
Buildable now. Phase 57+ candidate.
The Operator says "explain" (or "what does that mean" or similar) out loud. The system recognizes the speech; routes the recognized request into the same Companion composition path as the button mode.
Substrate dependencies. Speech-to-text into the converse channel. Possibly:
Voice-modality substrate is a new arc. Adjacent to but not subsumed by the queued mobile presence direction (queued directions v0.10). Voice-input on the desktop OL surface is one variant; voice-input on a mobile surface is another; they share substrate but the UX differs. The mobile presence investigation document (loomworks-mobile-presence-investigation-v0_1.md) does not currently scope voice modality; the two threads may merge or stay parallel.
Not buildable now without prior voice-modality substrate. Likely Phase 60+ or later; depends on the voice-modality arc's overall scoping.
Both trigger modes route to the same composition path. Surface options (per-message, persistent, modal) and composition strategies (LLM-at-request, pre-authored, voice-templated) apply identically regardless of trigger. Splitting the affordance across two phases is a substrate-imposed sequencing, not a conceptual split.
How does the explanation render once triggered? Four options:
The right choice depends on how often the gap is hit (per-message-new-message scales poorly if explanations are frequent; inline-expand scales better) and on whether explanations should be conversational artifacts (per-message-new-message captures them as Memory; the others don't by default).
How is the explanation text produced when triggered? Three options:
Hybrid is likely: LLM-composed by default; pre-authored for the most-encountered explanation triggers; voice-templated scaffolding to keep LLM composition on-discipline.
| Component | Button mode | Audible mode | |---|---|---| | OL UI surface | Existing converse view + button element | Existing converse view + microphone permission + audio capture UI | | Speech-to-text | N/A | Required (service integration, latency, accuracy considerations) | | Wake-word / push-to-talk | N/A | Required (privacy, false-positive control) | | Composition dispatch | Existing Companion dispatch | Existing Companion dispatch (same path; trigger differs) | | Voice templates | New explain-affordance voice template family | Same as button mode | | Persistence | Optional — Memory event capture on explanation | Same as button mode (audio-derived text routes the same) | | Text-to-speech | N/A (unless explanation is also spoken back) | Optional — separate decision |
Button mode is text-substrate only. Audible mode adds at minimum speech-to-text + audio capture + activation gating.
Three candidate shapes for how the affordance lands in future phases:
Strengths. Delivers the affordance's value (button mode covers most comprehension-gap cases on desktop) before voice substrate exists. Voice-modality arc gets full scoping space without being pulled into the explain affordance's narrow shape. Lowest sequencing risk.
Weaknesses. Two phases instead of one for what conceptually is one affordance. The audible mode waits — possibly long.
Strengths. One coherent phase. The affordance is built once with both modes. Voice-modality substrate is shared across multiple use cases (explain, quick capture, possibly Companion-speaking output).
Weaknesses. Comprehension gaps go unhandled in the interim — months or longer. Phase 32 calibration evidence may reveal high gap frequency, in which case the wait is painful.
Strengths. Both modes land closer in time. Voice-modality substrate is bootstrapped from a narrow use case (the recognition surface only needs to handle a small command vocabulary, not full free-form speech).
Weaknesses. The lightweight substrate is throwaway — when full voice-modality arrives, the explain-mode integration likely refactors. Browser-native speech APIs are inconsistent across platforms.
Candidate A is the most conservative; Candidate B is the most architecturally clean; Candidate C is the most aggressive. Selection depends on how urgent the affordance feels after Phase 32 calibration evidence lands.
Phase 56 ships the voice principles document with the discipline-plus-recovery principle named. The principle becomes the anchor for the affordance's eventual scoping. Phase 56 also produces 2–3 persona calibration transcripts; those transcripts may already surface candidate comprehension-gap questions (persona reactions to the per-field elicitation prompts). If they do, the affordance's pre-authored or LLM-composition strategy benefits from concrete examples.
Phase 32's calibration evidence (the marketing engagement creation) will further inform: how often does the gap surface in real use; which questions are most likely to trigger it; whether the gap is concentrated on specific elicitation stages.
The investigation document is updated to v0.2 after Phase 32 calibration evidence lands, before the explain-affordance phase scoping opens.
DUNIN7 — Done In Seven LLC — Miami, Florida Loomworks Explain Affordance Investigation — v0.1 — 2026-05-11