uttrflow / uttrflow/uttrflow-swift

Five documents name types and functions that no longer exist: persistedSaved, HeldModifierMonitor, CleanupPrompt and Verification.attestingKinds

Open Beginner friendly
#649 0 comments 0 reactions 0 assignees View on GitHub
area:general documentation good first issue P2
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.