Writing Specs & Designs
Good specs and designs bridge the gap between vision and execution. The best specs provide enough clarity that engineers know exactly what to build, while leaving room for creative problem-solving. In the AI era, the emphasis is shifting from detailed written documents to functional prototypes that show rather than tell.
The Guide
5 key steps synthesized from 7 experts.
Draw badly on a whiteboard first
Before any formal spec or high-fidelity design, sketch rough ideas on a whiteboard. Draw badly on purpose. This invites collaboration and gets you to a shared vision faster than polished wireframes. When someone says 'No, no, it doesn't work that way. Give me the pen,' you've succeeded in creating engagement.
Featured guest perspectives
"I just found if I got on the whiteboard and drew really badly... Somebody else will go, 'No, no, no, it doesn't work that way. Give me this pen,' and start doing it. And it gets you so fast to a shared vision... I know designers spend all this time making wireframes and I'm like, that's the lamest use of time ever."— Christina Wodtke
"In a shaping session, you can't collaborate on something so high fidelity. So we need also some ways to collaborate... like breadboarding and fat marker sketching. These are tools to help us express an idea very, very clearly in detail."— Ryan Singer
Shape the spec to show the moving pieces
A well-shaped spec is a low-fidelity diagram that provides technical and functional clarity without over-specifying UI details. Aim for a level of detail where the team can see the 'electricity in the walls' - they understand the technical feasibility and the core interactions. Usually this means describing 10 or fewer moving pieces.
Featured guest perspectives
"The output of the shaping session is... some kind of drawing or diagram where engineers, product, and design are all looking at that and they're saying, 'We understand that. I know exactly what to go build.'"— Ryan Singer
"I would suggest learn how to sketch, learn Balsamiq. Having that ability to think at a conceptual level about how UI and UX works is I think a critical part of being a product manager."— Ravi Mehta
Prototype in code, not just mocks
Static mocks and walkthroughs can only take you so far. Move to real software prototypes as quickly as possible, even if the code is messy and you'll throw it away. You need to 'live and touch and smell the software' to understand how it really feels. A mock can't tell you what an interaction actually feels like.
Featured guest perspectives
"We stopped spending so many cycles on design explorations of static mocks or walkthroughs and said, 'How quickly can we get into prototyping the path in real software, even if it's messy and you throw it away,'... You got to live and touch and smell the software. You can't just look at it."— Noah Weiss
"The thing that I learned from him the most was the power of prototyping. And that even though he was such a great product thinker, he would always say, 'I can't tell you if this is going to work. I have to feel it. I have to try it. And a mock-up doesn't tell you what it's going to feel like.'"— Tamar Yehoshua
Own the pixels in zero-to-one work
For new products, every tap and interaction matters enormously. Users will bounce quickly if the experience doesn't immediately provide value. The product lead must be deeply involved in the granular design details - the hierarchy, the flows, the specific copy. Products live and die in the pixels.
Featured guest perspectives
"Every tap on a mobile app is a miracle for you as a product developer because users will turn and bounce to their next app very quickly... Every tap that you get, every single one is so scarce that you should be optimizing everything."— Nikita Bier
"You should be designing the hierarchy, the pixels, the flows, everything. That's on you. And products live and die in the pixels."— Nikita Bier
Create throwaway code infrastructure
Build a prototyping infrastructure that's separate from production code. This lets you crank out experiments much faster because you're not worried about maintainability or edge cases. Hire 'design engineers' who focus on speed over production-grade code. The goal is learning, not shipping.
Featured guest perspectives
"If you're doing it right, it'll be faster and you need to have an engineering infrastructure that enables prototyping... you write code that is never going to make it to production so you can just crank it out much faster and then you can see what works and then you build the production code."— Tamar Yehoshua
Common Mistakes
- Spending weeks on high-fidelity wireframes before getting team alignment on the core concept
- Writing specs so detailed that engineers have no room for creative problem-solving
- Relying on static mocks when only a real prototype can validate the interaction feels right
- Delegating all design work to designers when zero-to-one products need PM involvement in pixel-level decisions
- Treating 'temporary' design shortcuts casually - they often become permanent product legacies
Signs You're Doing It Well
- Engineers say 'I know exactly what to build' after reading your spec
- You move from idea to clickable prototype in days, not weeks
- Whiteboard sessions generate energy and collaboration rather than silent nodding
- Stakeholders can experience the product vision rather than just read about it
- Your prototyping velocity is fast enough to test multiple approaches before committing
All Guest Perspectives
Deep dive into what all 7 guests shared about writing specs & designs.
Christina Wodtke
"I just found if I got on the whiteboard and drew really badly... Somebody else will go, "No, no, no, it doesn't work that way. Give me this pen," and start doing it. And it gets you so fast to a shared vision... I know designers spend all this time making wireframes and I'm like, that's the lamest use of time ever."
- Draw 'badly' on a whiteboard to invite others to participate and correct the vision.
- Use simple shapes (squares, circles) to represent complex systems during early design discussions.
Nikita Bier
"Every tap on a mobile app is a miracle for you as a product developer because users will turn and bounce to their next app very quickly... Every tap that you get, every single one is so scarce that you should be optimizing everything."
- Optimize every single tap in the user flow to ensure it provides immediate value
- Watch users interact with their phones to understand the frequency of app-switching
"You should be designing the hierarchy, the pixels, the flows, everything. That's on you. And products live and die in the pixels."
- Take ownership of the information hierarchy and user flows rather than delegating them entirely to a separate design org
Noah Weiss
"We stopped spending so many cycles on design explorations of static mocks or walkthroughs and said, 'How quickly can we get into prototyping the path in real software, even if it's messy and you throw it away,'... You got to live and touch and smell the software. You can't just look at it."
- Move from static mocks to real software prototypes as quickly as possible.
- Use 'messy' throwaway code to test the 'feel' of an interaction early.
Ravi Mehta
"I would suggest learn how to sketch, learn Balsamiq. Having that ability to think at a conceptual level about how UI and UX works is I think a critical part of being a product manager. And if it's a skill that you don't have today, there's great resources to be able to work on that skill."
- Use low-fidelity tools like Balsamiq to quickly iterate on product concepts.
- Focus on the conceptual layout and user flow rather than high-fidelity visual design.
Ryan Singer
"The output of the shaping session is... some kind of drawing or diagram where engineers, product, and design are all looking at that and they’re saying, 'We understand that. I know exactly what to go build.'"
- Aim for a level of detail where the team can see the 'electricity in the walls' (technical feasibility).
- Ensure the spec describes the 'moving pieces' of the solution (usually 10 or fewer).
"In a shaping session, you can’t collaborate on something so high fidelity. So we need also some ways to collaborate... like breadboarding and fat marker sketching. These are tools to help us express an idea very, very clearly in detail. We’re going to hit this button and from this button, go to here. This calculation runs, then we get this answer."
- Use 'fat marker sketches' to prevent getting bogged down in UI details like colors or exact spacing.
- Focus on the 'affordances' (buttons, inputs) and the 'connections' (where they lead) to define the system.
Tom Conrad
"I'm not sure what the point of this story is other than maybe it's something about, I think we all do this as designers and product people. We take these shortcuts that we think that we'll go back later and clean up. Sometimes, it's literally been 30 years that little design detail lingers three implementations later and now it's just a part of the way that these Apple products work."
- Be mindful that 'temporary' UI/UX decisions may last decades
- Recognize that early implementation details can define long-term user expectations
Tamar Yehoshua
"The thing that I learned from him the most was the power of prototyping. And that even though he was such a great product thinker, he would always say, 'I can't tell you if this is going to work. I have to feel it. I have to try it. And a mock-up doesn't tell you what it's going to feel like.'"
- Push for prototypes that use real data to truly test the user experience.
"If you're doing it right, it'll be faster and you need to have an engineering infrastructure that enables prototyping... you write code that is never going to make it to production so you can just crank it out much faster and then you can see what works and then you build the production code."
- Build a layer of abstraction in your tech stack that allows for rapid UI experimentation.
- Hire 'design engineers' or prototypers who focus on speed over production-grade code.
Install This Skill
Add this skill to Claude Code, Cursor, or any AI coding assistant that supports Agent Skills.
Download the skill
Download SKILL.mdAdd to your project
Create a folder in your project root and add the skill file:
.claude/skills/writing-specs-designs/SKILL.md Start using it
Claude will automatically detect and use the skill when relevant. You can also invoke it directly:
Help me with writing specs & designs Related Skills
Other Product Management skills you might find useful.
Defining Product Vision
Product vision in media should center on the core content (journalism) enhanced by a user experience...
View Skill → →Problem Definition
Directly experiencing the product as a user or provider reveals fundamental flaws in problem definit...
View Skill → →Prioritizing Roadmap
Growth roadmaps must be sequenced based on the underlying growth model and available resources rathe...
View Skill → →Setting OKRs & Goals
Avoid 'toddler soccer' (everyone chasing the same metric) by detangling goals into specific input me...
View Skill → →