Specify tag behavior for independent implementers

Two plausible implementations differ because behavior is underspecified. Agreement alone would also be inconclusive: both could share the same default or defect.

Follow-up 1 · A third implementation

A third engineer uses a different framework. What do you compare?

Follow-up 2 · The product rule changes

Users now need case-preserving display with case-insensitive uniqueness. Which field changes?

Record the evidence and limitations

Build in three stops: reproduce the small case and baseline failure. Implement the protected boundary. Then replay both changed requirements with captured outputs. Record commands, fixtures, and observed results in your implementation README. A diagram is a prediction until those checks run.

Supply a behavioral disagreement and the exact sentence that resolves it. Additional lead scope: Own spec versions and compatibility between released clients. Completion demonstrates practice evidence. It does not establish interview readiness or multi-team delivery experience.

Detailed implementation and AI-assisted prompts

You end up with a specification two fresh sessions turned into nearly the same system, and a diff showing exactly where it leaked.

Build

One specification for one small, real feature — tagging from Stage 1 reading-list is the right size. Hand the identical document to two fresh sessions with no other context, let each build it, and compare what comes back. The spec is the deliverable. The two builds are its test.

The thought process

The first decision is what gets pinned and what stays free. The rule: if two correct implementations could differ on it and nobody would notice, leave it out. If the difference would reach a user or a caller, pin it. Pin everything and the spec is code in worse syntax. Pin nothing and it is a wish.

Second: what "the same" means, because you cannot diff source — variable names are not disagreement, behaviour on the same input is. So you fix the probes before the first build: the empty tag, the duplicate, the 200-character one, two users tagging one item. And when the builds diverge anyway, that is not the model guessing badly — it is a question you left open, answered by coin flip, twice, differently. Every difference is a missing sentence: add it, run a third stranger, watch the fan close.

How to organise the prompts

1 — the holes, before you pay for them.

Read this specification. Do not build it.

List every question you would have to answer yourself because the
spec does not. Split them: ones where any answer is fine, and ones
where I would care which answer you picked.

The second list is your fan-out, visible before it costs anything. Fix the cheap holes before anyone builds.

2 — the build, verbatim, to two fresh sessions.

Build exactly what this specification says. Where it is silent,
choose reasonably, and record every choice in ASSUMPTIONS.md: the
question, your answer, the nearest alternative.

Stop when it runs and the spec's examples pass.

Fresh means fresh — no shared history, no memory — and each session must end with something that runs plus a non-empty ASSUMPTIONS.md.

3 — the comparison.

Here are two builds' answers to the same probes, and both
ASSUMPTIONS.md files. List every behavioural difference, and for
each write the one sentence missing from the spec that would have
prevented it. Pin behaviour, not implementation.

Accept or reject each sentence yourself. The check is a third stranger, who must not reproduce the differences you fixed.

On AWS

The stranger must actually be a stranger, and a chat app is not one — it carries memory and custom instructions you have stopped seeing. A pinned model id behind an API is the clean subject. Amazon Bedrock and provider APIs may offer overlapping model families, with different versions, regions and capabilities. Bedrock earns it when your work already lives in AWS — IAM credentials you already have, invocation logging, cost next to the rest of the bill. Otherwise the direct API is simpler. Nothing else here needs AWS: the artefact is a text file, and git is its home.

What productionising it means

The convention outlives the afternoon: silent choices always land in ASSUMPTIONS.md, and a changed spec gets a fresh stranger run, because specs rot the way tests do. On a team this becomes spec review before code review — a sentence is cheaper to argue about than the four hundred lines that answered it wrong.

The learning

Some implementation differences reveal questions left open. Others are plain implementation errors. Compare each result against the written contract before calling the specification incomplete. And precision stops being a feeling — it is measurable, as the distance between two strangers.

How you would know it is wrong

• The builds agree on unspecified behavior. Check for shared defaults or leaked context. Agreement alone does not establish specification completeness.
• Remove one important sentence and rerun its distinguishing probes. Agreement may reflect a shared default. Introduce a deliberate contrary behavior to verify that the probes can distinguish it.
• The third stranger diverges where you already fixed. Your sentence pinned an implementation detail, not the behaviour.
• An empty ASSUMPTIONS.md. The recording failed. It does not mean the spec was complete.

Back to the ordered project index