uttrflow / uttrflow/uttrflow-swift
Six sentences in the dictation and shortcut documents contradict the code, two of them in a table marked verified
- 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
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