Don't waste time on specs: /prototype instead

The problem with spec-driven development

00:00There's something that a lot of people do when they're working with AI to create code that totally drives me crazy and it's sort of something that I've been railing against for a while now. The thing that I've noticed is people tend to think I need to create a spec for AI.

00:15I need to create a plan, right? Plan mode, spec driven development. I need to put all of my efforts into making this extremely detailed spec so that when I get some outputs from the AI, those outputs are going to look like the spec. I'm going to have specified everything up front so that I can just perfectly nail it.

00:32And in this impulse, what they forget to do is they forget they can actually write code. You can write code while you're working towards a spec. Prototyping and spikes are things that we've had around since the days of agile, right? I mean, I suppose these are still the days of agile.

00:48Agile is still extremely popular, still extremely influential, but people just aren't prototyping anymore. And so, as part of my skills repo, I'm trying to turn this around. I have a prototype skill. A prototype is throwaway code that answers a question.

01:02Everyone is saying that code is cheap. And it's partially true and partially I hate that phrase. But the thing that is cheap is the cost of producing code has gone way, way down. So producing prototypes, producing quick kind of throwaway spikes has never been cheaper and never been a more effective tool.

01:20In this video, I'm going to introduce this prototype skill. I'm going to talk about when you should use it, what it can be used for, and also how it fits into my new wayfinder

Understanding fidelity in design

01:29skill. But first, I want to explain the concept of fidelity, high fidelity and low fidelity. Whenever you're talking about designing something, you're going to have questions in your mind that need to be resolved somehow. Some of the questions are going to be really basic like the basic frame of the thing you're building.

01:46When the modal opens up, it should have a cancel button and a confirm button. Simple stuff. With simple stuff like that, you don't need a lot of highfidelity stuff to answer the question. That can just be resolved in discussion really. But let's say that the modal when it opens up under some circumstances, it needs to show some data.

02:02You might need to go a little bit of higher fidelity on that. How would you display the data? It's often hard when you're planning out a spec to figure out exactly how things should look and how things should look, how they should behave under certain circumstances.

02:15Making sure that you've road tested all of this idea in kind of semiworking code, that means you need a higher fidelity. Some questions really can only be answered by prototyping. And because producing these prototypes is now cheaper than it ever has been before, I tend to want more of my discussions at a higher fidelity.

02:37Obviously, the basic stuff I'm going to just resolve through discussion. So, the agent is going to ask me some questions, probably through a grilling session, and then I'm going to say, "Okay, yeah, this sounds good." But then, as soon as we get anything that I think, "Oh, I really need to see this in action.

02:49I need to feel it in action, look at it working," I'm going to ask for a prototype.

Prototyping in Wayfinder

02:55Prototyping is a part of my new wayfinder skill, which is a skill that allows you to plan a huge chunk of work. There's a future video coming on Wayfinder. Now, Wayfinder, what it does is it tackles a huge chunk of work and it splits it up into different planning sessions.

03:10And all of these planning sessions get their own ticket. And there should be somewhere in here ticket types just here that tells it exactly what different ticket types there are. The two that we're looking at here are the grilling type. So, it's using the grilling skills and the prototype ticket type.

03:28The default case here is the grilling type. So, where you're chatting with the agent, figuring out the basic scope of the thing you're building. But when you need to raise the fidelity of the discussion, making a cheap rough concrete artifact to react to an outline, a rough take, a stub or UI logic code via the prototype skill, links the prototype as an asset.

03:44Use when, how should it look, or how should it behave is the key question. Whether you're using Wavefinder or not, this gives you a really clear criteria for when you should reach for a prototype.

Building a search bar prototype

03:57So, I'm sure you're dying to see it in action. And here it is. This is what it's done. I've been using Wavefinder to extend my diagramming app here, which is built on TL Draw. And I wanted a way to search through old diagrams. And the data model here is quite complicated.

04:12There's like diagrams and then snapshots of the diagram through time. And so, I wanted to build a search bar, but I wasn't sure how it should look or behave. So I ran prototype here. And what it did is it created this little uh picker at the bottom here.

04:25And this picker, if I go between it, it has three different options. So that's option B and that's option C. And each one encodes a few design decisions that I can then react to and iterate on. So let's start by looking at A. I've just generated this.

04:40I've not actually looked at it yet. So I get to search the diagrams and see what comes up. And this one. Okay, it's reflow in place grouped rows. So, it's grouping the snapshot by the name of the diagram. I really like the placing of the search box up here.

04:56But this grouping doesn't feel right to me. So, let's see what B is. Let's search again inside model here. And okay, now on the left we have grouping for or it can filter down. Okay, that's quite nice. What happens if I search for something else and it's already Okay, so the filter resets at that point.

05:15Now, that's okay, but I wonder what C looks like. I really don't like this search diagrams thing at the top. That doesn't look nice. But let's see what this looks like. So, let's search for model and ooh. Okay, so now it's everything in line, no filters.

05:29So, I do actually really like this, but there are a few things that I don't like. I don't like these current things. It looks like this is a really technical weird thing, but the the current one is showing with the diagram snapshot. So, I've got some kind of feedback that I want to give to the prototype.

05:46This prototyping session took about 100,000 tokens. So, I'm actually going to compact and say we're going to do some more QA on this. Compacting at this point makes sense to me because we kind of need to retain all of the information about the prototype, need to retain all the design decisions that went into it, but we just need to give it some feedback.

06:04So, we just need to continue the conversation in the same place in the codebase. I should definitely do a video about the design tree that I use for when I've got compact versus clear versus handoff, but you know, that's one for another time.

Iterating on the prototype

06:16Okay, now I'm going to give some feedback. I really like the search box of A and I like the layout of C. Okay, so I've just dictated in some more feedback and I'm going to send it off. So the idea of this session is I'm iterating on this prototype.

06:28I'm not just saying, okay, this is the best one. I'm going to actually create some design decisions here, create a super rich asset. All of these design decisions are then going to be encoded into the prototype and I'm going to save the prototype probably on a throwaway branch.

06:43That means that when the thing actually goes to implement it, it's not only got a spec, it's actually got real front-end code that it can usually copy and paste out of it. Now, creating these prototypes does take some time, right? The higher fidelity you go, the more token cost there is.

06:57If we were to try to resolve this in a discussion, we'd be at a lower fidelity. So the answers would be less useful, but we'd also be spending fewer tokens. And we can see it's now starting to give me a D version here, which is kind of what I've been iterating towards.

07:11One note here is that this is actually uh integrated with the live page. So it's not doing this on a throwaway route. You can do that if you want to, but I really like seeing it actually plugged into the live route because then it just gives you so much more flexibility.

07:28like it's a more honest representation of how the code is actually going to work. All right, looks like it has now created D. So let's see what that looks like. Yes, we have the box from A. And if we search in here with model, then we can see that everything I asked for actually got done.

07:46Before we had a duplicate of this one, but now there's only one. And in theory, if I click this, I'm not sure if this will actually work. I don't know whether this is part of the prototype. Yes, it works. Oh, beautiful. So there we go. Loads of this functionality.

07:59Looks like it is now just done. And so

From prototype to production

08:01you might ask, what is the next step after this? Well, now I consider the prototype to be complete. That was a pretty quick one. Usually I'm kind of in here doing a lot more. Um, I would pass this off to an AFK agent to plug in everything, delete the old prototype code, and just make sure that it was uh compliant with the original spec.

08:18And as you can imagine, the results here are incredible because we've had such highfidelity discussion because we've been able to look at a live running version of it, give our feedback based on that. That feedback is so invaluable and it's already baked into a throwaway branch that our implement can actually just go and reference.

08:39So many times I see people saying, "Well, the thing didn't build what I wanted. I created this big beautiful spec and it just did something totally weird." you probably just weren't having discussions at a high enough fidelity and you probably

Prototyping beyond frontend

08:53should have been prototyping. Finally, I don't want you to walk away thinking this is only for UI or front-end stuff. Front end definitely benefits a lot from prototypes because how should it look? What should it look like is a really key question that's really hard to answer during the discussion phase.

09:08However, when you're doing more complicated stuff, especially backend work, then a question like does this logic, does this state model feel right? If you're building anything reasonably complex or that needs to work in the real world, then you're going to run into these questions all the time.

09:23And often the best way to get around these kind of questions, to build something that kind of serves the needs of your users, especially on something complex, is to build a prototype. Now, it doesn't need to be a UI prototype. And what I've got here is build a tiny interactive terminal app that pushes the statement machine through cases that are hard to reason about on paper.

09:44In other words, a pure logic prototype. And I've had tons of feedback from folks saying that this is such a nice little feature. Both of these branches have their own reference docs here which tell it exactly how to do each one. So if it's building a logic prototype, it looks here.

10:00If it's building a UI prototype, it looks like

Why higher fidelity matters

10:03this. So I beg of you, have your discussions at a higher fidelity. As agents get better at working with canvases, working with design tools, I'm sure that wireframes will definitely make a comeback as well. And the key point is this. The leap from discussion and spec to production ready code is really big.

10:19Whereas if you have a working prototype, turning that into production is pretty simple. I want to give a quick shout out to Shape Up by Ryan Singer, which is an extremely good book and very very influential on me. I read this I think in 2019 or something and it totally changed the way that I built applications for people.

10:37It is totally free online and I will drop a link in the description. If you want to keep up to date with my skills, then my skills newsletter is the place to be. I am shipping, shipping, shipping, constantly thinking about these skills, how I can make them better, and you can benefit from that the day that I make the changes.

10:52But folks, thank you so much for watching. It's been a pleasure as always bringing you one of my skills and I will see you very