The Spec That Travels With the Work

The first two problems with most specs are well understood: nobody reads them, and they go stale. The third problem gets less attention — the spec and the work are never in the same place to begin with.

Your canvas is in one tab. Your document is in another tool, in another folder, linked somewhere in the ticket description if you remembered to paste it. The card and the context are physically separate. By the time work starts, that distance is already doing damage.

The chip on the card

When a document is linked to a canvas card, a small chip appears directly on that card: View Detail →. Hovering it shows a preview of the document’s opening text. No switching tabs. No searching.

This sounds minor. It isn’t.

The problem with most documentation workflows is that the spec has to be sought out. Someone has to decide to look for it, remember where it is, and open it. Most of the time, across a long sprint, they don’t. Not because they’re lazy — because they’re focused, the question doesn’t feel urgent enough to justify the interruption, and they’ll ask you on Slack instead.

When the document is one hover away from the card they’re already looking at, the friction is low enough that it actually gets consulted. The context is where the work is. That’s the whole thing.

The relationship is bidirectional too. Inside the document, a backlinks chip lists every canvas card that references it. So a spec written before the canvas is fully built still knows where it belongs once the cards are linked.

The card doesn’t know when the spec is wrong

The harder problem: the canvas can change and the document won’t.

Scope gets cut. A dependency shifts. An engineer discovers a constraint in week two that invalidates three paragraphs of the spec. The canvas is updated, because the canvas is right in front of you. The document — somewhere else — gets a mental note you’ll get to later.

This is the stale spec problem, and it’s structural. It happens when the gap between the canvas and the document is wide enough that updating one doesn’t create any pressure to update the other.

When they’re linked, the pressure is physical. You’re looking at the card. The document chip is right there. You open it, notice it’s out of date, and edit it while you’re in it — not because you’re disciplined, but because the alternative is clicking away from something that’s staring at you.

Feedback that stays close to the sentence

The other thing that travels with the work: the questions.

The usual pattern: an engineer reads the spec, gets confused about one sentence in the acceptance criteria, pings you on Slack. You answer. The question and the answer are now in Slack, separated from the passage that caused the confusion. A month later, a new engineer has the same question.

Inline comments live on the text they refer to — an amber highlight on the specific passage, a thread attached to it. Anyone who opens the document after that sees the annotation, the question, and the answer. The reasoning accumulates in the document instead of evaporating in chat history.

When a thread is resolved, the highlight disappears. Open threads are visible in a review panel that lists every unresolved question across the document. For a spec mid-review, that panel is a complete picture of what’s still unsettled.

The document as trail

After the feature ships, the document stays linked to the card. Version history keeps a snapshot of every published revision — who changed it and when.

This is what a decision log actually looks like in practice. Not a separate document someone maintains manually. Just the version trail of a spec that was kept current as the work progressed. Six months later, when someone asks why a specific thing was cut or changed, the answer is in the history — not in a Slack search, not in the memory of whoever was in the room.

The spec isn’t done when you publish it. It’s done when the work is done. And if it traveled with the work the whole way, it should look different at the end — marked up, revised, resolved — not identical to the version you wrote before anyone touched the code.

That difference is evidence of a document that actually did its job.