Files
kandev/docs/specs/ui/settings-prompt-editor.md
T
2026-08-21 16:40:58 +01:00

107 lines
6.6 KiB
Markdown

---
status: shipped
created: 2026-08-20
owner: Kandev
---
# Settings Prompt Editor
## Why
Prompt fields in Settings use different editors and completion rules. Users cannot reliably discover placeholders or reference saved prompts across these fields.
## What
- Kandev provides one shared prompt editor for prompt-authoring fields in Settings.
- The editor stores plain text and preserves each existing settings and save contract.
- Typing `{{` shows only the placeholders that the current prompt context supports.
- Selecting a placeholder inside an existing `{{...}}` pair replaces only the
placeholder name and preserves the pair's closing braces. Selecting a
placeholder after an unfinished `{{` adds exactly one closing pair.
- Typing `@` shows saved prompts when the runtime resolves saved-prompt references for that field.
- Typing a name prefix after `@` keeps saved prompts whose names match that
prefix available for selection.
- Prompt names may contain spaces. The active mention starts at a
whitespace-bounded `@`, and the full text after it remains part of the
filtering range while the user types.
- A selected saved prompt inserts its `@name` reference. The editor does not inline or copy the saved prompt content.
- The saved-prompt list updates when a prompt is added, edited, or removed.
- A custom prompt can reference other saved prompts. Its editor does not suggest the prompt that is currently open.
- Keyboard, pointer, and touch users can open, filter, and select completion items.
- The editor keeps completion providers scoped to their editor model. One open editor cannot show completion items from another editor.
- Each field keeps its existing dirty state, validation, reset behavior, save coordinator, and persisted text format.
- Desktop and mobile settings routes provide the same completion functions.
### Settings surfaces
| Surface | Placeholder completion | Saved-prompt completion |
|---|---|---|
| GitHub, GitLab, Jira, and Azure DevOps quick actions | Provider placeholders | Yes |
| GitHub, GitLab, Jira, Linear, Sentry, and Azure DevOps watch prompts | Provider placeholders when available | Yes |
| Workflow prompt | Workflow placeholders | Yes |
| Workflow step prompt | Step placeholders | Yes |
| Automation instructions | Trigger placeholders | Yes |
| Custom prompt content | None | Yes, excluding the open prompt |
| Utility agent prompt | Utility template variables | No |
Utility prompts run through the sessionless utility template engine. That engine does not resolve saved-prompt references.
The shared editor does not replace script, query, JSON, or description fields. Those fields have different languages and completion contracts.
## Failure modes
- If saved prompts fail to load, placeholder completion continues to work. The `@` menu shows no saved prompts.
- If a field has no configured placeholders, `{{` shows no placeholder items.
- If Monaco loads slowly, the field shows the existing localized editor loading state. The controlled draft remains unchanged.
- If two prompt editors are mounted together, each editor uses only its own placeholders and saved-prompt rules.
- Concurrent mounted editors share one in-flight saved-prompt request. A
failed request cannot replace a successful result from another editor.
## Persistence guarantees
This feature adds no new persistence. Each settings surface continues to store its current plain-text value through its current API.
Selecting a completion item changes only the local draft. The existing settings save action remains the persistence boundary.
## Scenarios
- **GIVEN** a saved prompt named `review-helper`, **WHEN** a user types `@rev` in a GitHub quick action, **THEN** the editor offers `@review-helper`.
- **GIVEN** that suggestion, **WHEN** the user selects it, **THEN** the draft contains `@review-helper` and no save starts.
- **GIVEN** a GitHub quick action editor, **WHEN** a user types `{{`, **THEN** the editor offers `{{url}}` and `{{title}}`.
- **GIVEN** an editor contains `{{}}` with the cursor between the brace pairs,
**WHEN** the user selects `{{task_prompt}}`, **THEN** the draft contains
exactly `{{task_prompt}}` with no duplicated closing braces.
- **GIVEN** an editor contains an unfinished `{{` token, **WHEN** the user
selects `{{task_prompt}}`, **THEN** the draft contains exactly
`{{task_prompt}}` with one closing brace pair.
- **GIVEN** an editor contains `{{ta_prompt}}` with the cursor after `ta`,
**WHEN** the user selects `{{task_prompt}}`, **THEN** the partial name and
its existing suffix are replaced and the draft contains exactly
`{{task_prompt}}`.
- **GIVEN** a saved prompt named `changes-walkthrough`, **WHEN** a user types
`@c`, **THEN** the completion list keeps `@changes-walkthrough` available.
- **GIVEN** a saved prompt named `Daily Summary`, **WHEN** a user types
`@Daily `, **THEN** the completion list keeps `@Daily Summary` available
and selecting it inserts the complete mention.
- **GIVEN** two open editors with different placeholder lists, **WHEN** a user types `{{` in either editor, **THEN** only that editor's placeholders appear.
- **GIVEN** an open workflow prompt, **WHEN** another route adds a saved prompt, **THEN** the next `@` list includes it.
- **GIVEN** a custom prompt named `release`, **WHEN** the user edits `release` and types `@`, **THEN** the list omits `@release` and includes other saved prompts.
- **GIVEN** a utility agent prompt, **WHEN** the user types `{{`, **THEN** utility variables appear and no saved-prompt completion is offered.
- **GIVEN** a failed saved-prompt request, **WHEN** the user types a supported placeholder prefix, **THEN** placeholder completion still works.
- **GIVEN** an unsaved prompt edit, **WHEN** the user leaves the route, **THEN** the existing settings navigation guard still handles the draft.
- **GIVEN** GitHub quick actions on a phone, **WHEN** the user selects both completion types, **THEN** no horizontal page overflow occurs.
- **GIVEN** a saved quick action that contains a placeholder and saved-prompt reference, **WHEN** the page reloads, **THEN** the editor shows the same stored text.
## Out of scope
- Rich-text formatting, Markdown preview, or Tiptap document storage.
- Changes to saved-prompt expansion, placeholder interpolation, or backend APIs.
- Prompt composers outside Settings, such as task creation and task chat.
- Completion for scripts, WIQL, JQL, JSON, descriptions, or confirmation fields.
## Implementation plan
See [`../../plans/settings-prompt-editor/plan.md`](../../plans/settings-prompt-editor/plan.md).
The completion regression repair is tracked in
[`../../plans/settings-prompt-completion-regressions/plan.md`](../../plans/settings-prompt-completion-regressions/plan.md).