uttrflow / uttrflow/uttrflow-swift
Five documents name types and functions that no longer exist: persistedSaved, HeldModifierMonitor, CleanupPrompt and Verification.attestingKinds
- Dominant language
- Swift
- Stars
- 4
- Forks
- 17
- Avg merge
- 3h 32m
- Merged PRs (30d)
- 277
Description
## What happens
Each symbol below has zero matches in `Sources/` and `Tests/` (`git grep -w`), and each document describes it in the present tense:
| Document | Says | Now |
|---|---|---|
| `Docs/clipboard-store.md:59` | "This is why `persistedSaved` exists." | `savedOnDisk`, `Sources/UttrflowClipboard/ClipboardStore.swift:25-26` |
| `Docs/stuck-recording.md:16` | "`HeldModifierMonitor` watches `NSEvent` monitors…" | removed; holds go through `SystemKeyboard` and `ActivationMonitor`, as `Docs/shortcuts.md` describes |
| `Docs/ai-context-line.md:4` | "`CleanupPrompt` tells the model what to do with it" | `Sources/UttrflowAI/PromptBuilder.swift`, `PromptContract.swift`, `PromptBlocks.swift` |
| `Docs/cleanup-design.md:195` | "Today's `CleanupPrompt.instructions`" | as above |
| `Docs/predict-agent.md:22`, `:69` | `Verification.attestingKinds(for:)` | `attests(...)` and `isClosedVocabulary` in `Sources/UttrflowPredict/Verification.swift` |
Also in `Docs/stuck-recording.md`: the heading at line 9 says "There are two causes", and the page then lists three (lines 11, 44, 93).
`Scripts/docs_audit.sh` checks that backticked *paths* resolve, but not backticked Swift symbols, which is why these survived.
## Why it matters
A newcomer searching for the named type finds nothing and has to work out from history what replaced it.
## Acceptance criteria
- Each row above names the current symbol, or is rewritten in the past tense where the document is explaining history.
- The `stuck-recording.md` heading matches the number of causes.
- `make docs-audit` passes.
- Optional, and fine as a separate pull request: `docs_audit.sh` gains a check that a backticked UpperCamelCase token followed by `.` or `(` either exists in `Sources/`/`Tests/` or is on a short allowlist of Apple and dependency API names.
## Where to start
- The five documents above.
- `Scripts/docs_audit.sh` section 1 shows how the path check is written, if you take the optional part.
- 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:** XS for the documents, S with the check.
Contributor guide
Research direction
Read CONTRIBUTING.md, then review the five documents named in the issue and compare each outdated symbol with the current Swift symbols and related documentation cited there. Update the names or historical wording, correct the stuck-recording heading, and run make docs-audit and make verify; the optional Scripts/docs_audit.sh check can be handled separately.
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
- 88/100