How to Draft Technical Specs Without Leaving Your Editor

Context dies when a spec lives in a different app from the code. You sketch a design in Notion, implement in the editor, then discover the Notion page drifted. One fix is cultural (update the doc). The other is mechanical: draft the first version of the spec in the same place you open the repo.

This is a Mac-oriented workflow for writing technical specs beside the code, then publishing outward only when the shape is stable.

Put the spec in the repo from day one

Create docs/spec.md (or docs/rfcs/0007-short-name.md) in the branch that will implement the change. Same PR can carry the first implementation and the doc. Reviewers see both.

Minimal skeleton:

# Title

Status: Draft | Accepted | Superseded
Author:
Last updated: 2026-10-24

## Problem
## Goals / non-goals
## Proposal
## Alternatives considered
## Rollout / migration
## Open questions

Non-goals earn their section. Most bad specs fail by trying to solve three products at once. If a stakeholder keeps adding scope, point at non-goals instead of rewriting the proposal in chat.

Write in the editor you already use

• VS Code / Cursor / Zed: open docs/spec.md in a split next to the code you are probing.
• Neovim: same idea with a vertical split; use spell and markdown preview if you want.
• Prefer Markdown over a proprietary doc format until stakeholders demand otherwise.

If someone needs Notion or Google Docs for comments, paste a frozen export after the engineering review—not before. Early comments in a rich doc encourage wordsmithing over deciding. Keep the canonical path in git so git blame still works six months later.

A 45-minute first draft loop

1. 10 min — Problem and goals. Write from the bug report or the customer quote. No architecture yet.
2. 15 min — Proposal as bullets. Interfaces, data shape, failure modes. Link to files that will change (app/auth/session.ts).
3. 10 min — Alternatives. List two you rejected and why. This prevents the "did you consider X?" drive-by.
4. 10 min — Open questions. Anything you still do not know. Assign owners if you can.

Ship that as a draft PR description or a Draft status RFC. Perfect prose is optional; clear tradeoffs are not. If you cannot finish in 45 minutes, the problem statement is probably too big—split the RFC.

Language helpers that stay out of your way

Spec writing is still writing: tightening goals, turning notes into sentences, fixing tone so it does not sound like a chat log. Cloud assistants are fine when the spec has no secrets. When it names customers, infra, or unreleased strategy, keep text local.

DraftKey provides on-device AI autocomplete and rewrite inside Mac apps ($4.99 lifetime, up to 3 Macs, macOS 14+, Apple Silicon, about 1.12 GB model, no trial). Disclosure: I built DraftKey. Use it—or any local helper—while the draft still contains things you would not paste into a random chatbot.

From editor draft to team artifact

Stage	Where it lives	Who comments
Rough	docs/*.md on a branch	You + one peer
Proposed	PR or RFC label	Eng review
Accepted	Merged on main	Linked from the issue tracker
Stakeholder copy	Notion/Docs export	PM / partners

Link the merged path in Linear or GitHub Issues so the tracker points at the source of truth, not a stale paste. When the implementation ships, add a one-line "Shipped in vX.Y" note at the top so readers know the doc is not aspirational.

Habits that keep specs alive

• Update the Last updated date when behavior changes—not only when you rewrite the whole doc.
• If implementation diverges, add a short Amendment section instead of silent drift.
• Delete or mark Superseded when a newer RFC wins. Zombie specs confuse new hires.
• Link related ADRs or RFCs; do not paste them inline.

Draft beside the code, review as engineering text, export only when needed. Your future self, reading docs/ six months later, is the primary audience.

What "good enough" looks like in review

Ask reviewers for decisions, not copy edits:

• Does the problem statement match the issue they feel?
• Are non-goals actually non-goals, or polite fiction?
• Is the rollout reversible?
• Which open question blocks implementation?

If feedback is mostly tone and commas, the spec was already clear enough—merge and move the prose polish to a follow-up. Conversely, if reviewers argue about the problem, stop coding; fix the Problem section first.

Pairing specs with tickets

Every Accepted RFC should have:

• One parent issue or epic in Linear/GitHub.
• Child issues for rollout steps that are not "obvious."
• A link back from the issue to docs/rfcs/... on main.

Without that loop, the beautiful Markdown file becomes archaeology. The editor-first workflow only works if the tracker still points at git as source of truth.