uttrflow / uttrflow/uttrflow-swift

Six sentences in the dictation and shortcut documents contradict the code, two of them in a table marked verified

Open Beginner friendly
#651 0 comments 0 reactions 0 assignees View on GitHub
area:dictation documentation good first issue P2
Dominant language
Swift
Stars
4
Forks
17
Avg merge
3h 32m
Merged PRs (30d)
277

Description

## What happens

| Document | Says | Code |
|---|---|---|
| `Docs/definition-of-done.md:22` (row 14, marked "✅ verified") | "`FocusedTextField` exposes exactly one mutating operation, `replaceSelection(with:)`" | two: `replaceSelection(with:)` and `replaceSelection(replacing:with:)`, `Sources/UttrflowInput/FocusedTextField.swift:6,9` |
| `Docs/definition-of-done.md:23` (row 15, "✅ matches") | `DictationState`: `idle`, `recording`, `transcribing`, `tidying`, `inserted`, plus `failed` | also `inserting`, `Sources/UttrflowPipeline/DictationState.swift:91` |
| `Docs/ux-settings-model.md:45-46` | "audio is never written to disk, so there is nothing about a recording for the user to set" | `Sources/UttrflowAudio/RecordingStore.swift` keeps a recording for a day when it could not be turned into text; Settings says so (`Sources/UttrflowUX/SettingsPresenter.swift:579-581`); `Docs/recordings.md` describes it |
| `Docs/quitting.md:6` | "Nothing is written to disk until the words land" | the audio is written while the key is held (`Docs/recordings.md:3`); only the transcript waits |
| `Docs/shortcuts.md:108-114` | "`CarbonHotkeyMonitor` stays for ⇧⌘V … most are observed through the tap, and one is claimed through Carbon" | three are `.claimed`: clipboard, paste last transcript, copy last transcript (`Sources/UttrflowUX/ShortcutRegistry.swift:38,43,48`) |
| `Docs/core-hotkeys.md:54` | "`isUsable` answers only the first" (a shortcut with no modifier) | it also refuses a modifier on its own: `&& !isBareModifier`, `Sources/UttrflowCore/Protocols/HotkeyMonitoring.swift:59` (line 36 of the same document says so) |

## Why it matters

`definition-of-done.md` is the table a contributor checks a change against, and two of its rows are marked verified while being out of date. The recordings sentence is a privacy statement, and it is the wrong way round.

## Acceptance criteria

- Each sentence matches the code as listed. For the two table rows, keep the claim's spirit (insertion can only replace the selection, or what it has confirmed is in front of the caret; the states the interface draws) and update the facts.
- `make docs-audit` passes.

## Where to start

- The five documents above, and the source lines cited for each.
- Read [CONTRIBUTING.md](https://github.com/uttrflow/uttrflow-swift/blob/main/CONTRIBUTING.md) first, and say on this issue that you are taking it.
- Before pushing, run `make verify` (with `DEVELOPER_DIR` pointing at Xcode 26.6 or later). It is the same command CI runs.

**Size:** S, about 1 hour.

Contributor guide

Open the contributing guide

Research direction

Read CONTRIBUTING.md first, then inspect the five cited documents alongside the referenced Swift sources and Docs/recordings.md. Update the six contradictory statements while preserving the intended claims, then run `make docs-audit`; before pushing, run `make verify` with the required Xcode version. Done means every sentence matches the cited code and both checks pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
91/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.