Gain access
← Blog

SpecsCoding agentsProduct

Specs with no gaps: why we built Tinkerbee

Coding agents fill every gap in a Spec with a guess. Tinkerbee grills the Spec against your code until no gap is left, then hands your agent the answers.

Karthik and the Skcript R&E team

4 min read

A coding agent never says "I don't know". Give it a Spec with a hole in it and it fills the hole with something that compiles. Sometimes the guess is right. Often it is plausible, and wrong in a way you find two days later in review.

We built Tinkerbee because we kept paying for those guesses. This post explains the problem, what we mean by a Spec, and the one idea the whole product rests on, the Grill.

The gap is the bug

Here is a Spec line we have all written:

Support can refund part of a captured payment from the order page.

It reads as complete. It is not. Can a refund exceed the captured amount? Who is allowed to issue one? Does a refund to store credit count? What happens to the fee? An engineer who has worked on the payments code for a year asks these questions out loud before writing a line. An agent asks none of them. It picks an answer for each, quietly, and moves on.

The problem is not that the agent is careless. It works from the text it gets, and the text is missing the answers. Every missing answer becomes a decision someone made without knowing they made it.

So the fix is not a smarter agent. The fix is a Spec with the answers in it.

What a Spec is

In Tinkerbee, a Spec is a plain-words description of something you want built, with an ID like SPEC-12. It lives with its repo. It starts as a Draft, rough on purpose, and moves through four states:

  • Draft. You write and rewrite. Anyone with access can comment.
  • Ready. Signed off. Every Open Question is answered or deferred on purpose, and the Spec is pinned to a commit.
  • Ticketed. Cut into tickets. Frozen and final.
  • Shipped. The PRs are merged and someone said so.

A Spec is not a ticket and not a design doc. It is the one place where what you meant gets written down, argued over, and settled before code exists.

The Grill

The Grill is the heart of Tinkerbee. Press it on a Draft and Tinkerbee reads two things, your Spec and your code. Then it asks what is missing.

Each gap comes back as an Open Question, and each Open Question comes with options and a recommended pick:

Can a refund exceed the captured amount?

  1. No, cap it at the captured amount (recommended)
  2. Yes, with owner sign-off

You answer in one click, or write your own answer. The answer becomes a Decision. The next grill round reads the Spec and every Decision so far, and asks about what is still open. You keep going until nothing is.

Two things make this work better than a chat window.

It reads the code. A question like "refunds already exist in payments/refund.rs, should this extend them?" only comes from reading the repo. Questions grounded in your code are questions you can answer quickly.

Answers are kept. A Decision has a name, an author and a reason. It shows on the Decisions tab. Change it later and its question reopens, so a changed mind is visible instead of silent.

When nothing is left to ask, the Grill greys out and Tinker ✨ appears. Tinker rewrites the Spec from your Draft and your Decisions, so the text reads as one clean Spec instead of a draft with a pile of answers stuck to it.

Words that mean one thing

Half of the gaps we found were not missing answers. They were the same word meaning two things. "Account" was a login in one Spec and a billing entity in another. "Refund" covered both money back and store credit.

Every repo in Tinkerbee has one Glossary. Each term has a definition and the words to avoid. Every grill round also runs a domain-modeling pass that proposes new terms and flags words that clash. When a Decision is hard to reverse, surprising without context, and a real trade-off, Tinkerbee proposes an ADR for it.

When you connect a repo, Tinkerbee imports your GLOSSARY.md and ADR folder if you have them. If you do not, it suggests a Glossary and ADRs from the code, and the repo's owner approves or dismisses each one.

Getting it to the agent

A Ready Spec is worth little if your agent never reads it. Tinkerbee cuts a Ready Spec into thin tickets, and a read-only MCP server lets Claude Code, Cursor or Codex pull the Spec, its Decisions, its Glossary terms and its ADRs while it works. We wrote about that half in How Tinkerbee turns a Spec into tickets your agent can read.

We grilled Tinkerbee with Tinkerbee's method

Before we wrote any code, we ran the same process on our own one-paragraph goal. It took three days and produced 99 Decisions, 8 ADRs, a Glossary, a Spec with 166 user stories and 21 tickets. Then a group of coding agents built the first version from those tickets in an evening. That story, with what broke, is in Built in a day by a swarm of agents.

The agents did not have to guess much. That was the point.

Try it

Tinkerbee is in beta, and it is a Skcript R&E project. Sign in with GitHub to request access, and we approve every account by hand. If you would rather talk first, email us at business@skcript.com.

Write Specs with no gaps.

Gain accessBeta access. We approve every account by hand. Or email us