João Salavisa
59 lines
2.7 KiB
Markdown
59 lines
2.7 KiB
Markdown
---
|
|
status: shipped
|
|
created: 2026-08-13
|
|
owner: cfl
|
|
---
|
|
|
|
# Clarification Shared Context
|
|
|
|
## Why
|
|
|
|
Agents can provide shared background with `ask_user_question_kandev.context`,
|
|
but operators currently see only the individual question fields. Questions
|
|
that depend on that background can therefore appear incomplete or confusing.
|
|
|
|
## What
|
|
|
|
- A pending clarification bundle with non-empty shared context displays that
|
|
context once above the active question card.
|
|
- Shared context uses normal text presentation with spacing above it. It has no
|
|
bordered, padded, or filled container.
|
|
- Shared context remains visible while the operator moves between questions in
|
|
a multi-question bundle.
|
|
- Task chat, Quick Chat, and other surfaces that use the shared clarification
|
|
overlay display the same context behavior on desktop and mobile.
|
|
- Omitted or whitespace-only context does not create an empty context region.
|
|
- The UI preserves line breaks in the agent-authored context and allows long
|
|
text to wrap within the clarification surface.
|
|
- Agents can provide multiline shared background as explicit context
|
|
paragraphs. The backend joins those paragraphs with blank lines while
|
|
preserving the legacy single context string verbatim.
|
|
|
|
## Scenarios
|
|
|
|
- **GIVEN** an agent submits a multi-question clarification with non-empty
|
|
shared context, **WHEN** the pending clarification appears, **THEN** the
|
|
operator sees the context exactly once above the active question card.
|
|
- **GIVEN** a visible multi-question clarification with shared context,
|
|
**WHEN** the operator navigates to another question, **THEN** the same single
|
|
context region remains visible.
|
|
- **GIVEN** an agent omits context or sends only whitespace, **WHEN** the
|
|
pending clarification appears, **THEN** the UI renders no context region and
|
|
preserves the existing question layout.
|
|
- **GIVEN** a pending clarification with shared context on a phone viewport,
|
|
**WHEN** the operator views the question, **THEN** the context is visible,
|
|
wraps inside the overlay, and does not introduce horizontal page overflow.
|
|
- **GIVEN** an agent submits multiple explicit context paragraphs, **WHEN** the
|
|
clarification is stored and displayed, **THEN** the operator sees those
|
|
paragraphs separated by blank lines.
|
|
- **GIVEN** an agent submits a legacy context string containing literal escape
|
|
syntax, **WHEN** the clarification is stored and displayed, **THEN** the
|
|
literal text remains unchanged.
|
|
|
|
## Out of scope
|
|
|
|
- Changing the `ask_user_question_kandev` schema or backend message metadata.
|
|
- Repeating shared context inside every question card.
|
|
- Adding shared context to resolved clarification messages in chat history.
|
|
- Changing clarification answer, skip, timeout, or carousel behavior.
|