A pull request description should explain the final change to a reviewer who has not heard the conversation. Dictate the problem, resulting behaviour, and relevant evidence, then check every technical and validation claim against the actual work.
Do not let cleanup turn intended tests into completed tests or a hypothesis into a measured result. The description is part of the review evidence.
Speak from the implemented behaviour
Start with the concrete trigger and before-and-after outcome. Add the mechanism only where it helps the reviewer assess correctness, then name executed checks, remaining limits, and material risks.
Use the verified diff and actual command or review results as references. Preserve file names, identifiers, versions, and error strings exactly where they matter rather than relying on recognition alone.
Draft a fictional stale-form repair
Suppose a change prevents an old form from overwriting a newer customer record. Dictate that submitting a stale revision now produces a reviewable conflict while preserving the user's draft.
Explain the version-check boundary and the relevant cases actually verified in the fictional scenario: independent edits, same-field conflict, permission loss, and interrupted confirmation. In a real PR, include only checks that were genuinely executed and record untested cases explicitly.
Review the cleaned text for changed action, overbroad guarantees, invented benchmarks, and missing limitations. A phrase such as prevents all concurrency problems would exceed the scope of one stale-form repair.
Keep the description aligned with the final diff
If implementation scope changes, rewrite the title and description around the final result. Remove abandoned approaches unless they explain an important tradeoff. The reviewer needs the delivered change, not a transcript of the development session.
Check that the description does not include private customer records, credentials, internal conversations, or unverified claims. Use authorised issue references and harmless examples where useful.
The tradeoff is fast spoken explanation versus precision. Voice can help articulate why a change matters, while the final evidence still needs deliberate checking. Measure total preparation effort before claiming that dictation saves time.
Do not automatically submit or publish a description merely because recognition finished. Keep the final human review and the normal repository workflow intact.
The Mac dictation workflow guide discusses controlled insertion, and StackSpeech's portfolio entry provides voice-product context. This stale-form PR is fictional and includes no executed code or test claim.
Questions about dictated PR descriptions
Should cleanup add tests that would be useful?
It can suggest a separate checklist, but the description must distinguish suggestions from verification actually completed.
Is the full implementation story necessary?
Usually only the problem, resulting behaviour, useful mechanism, validation, and limits belong in the final description.
What should be checked before posting?
Compare the text with the final diff and real evidence, then review technical strings and private data. Bring uncertain claims to a technical review discussion.