# 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:

```markdown
# 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](https://getdraftkey.com) 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.