Product Management 7 guests | 10 insights

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.

1

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
2

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
3

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
4

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
5

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 1 quote
Listen to episode →
"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."
Tactical:
  • 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.
View all skills from Christina Wodtke →
Nikita Bier 2 quotes
Listen to episode →
"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."
Tactical:
  • 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."
Tactical:
  • Take ownership of the information hierarchy and user flows rather than delegating them entirely to a separate design org
View all skills from Nikita Bier →
Noah Weiss 1 quote
Listen to episode →
"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."
Tactical:
  • Move from static mocks to real software prototypes as quickly as possible.
  • Use 'messy' throwaway code to test the 'feel' of an interaction early.
View all skills from Noah Weiss →
Ravi Mehta 1 quote
Listen to episode →
"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."
Tactical:
  • 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.
View all skills from Ravi Mehta →
Ryan Singer 2 quotes
Listen to episode →
"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.'"
Tactical:
  • 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."
Tactical:
  • 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.
View all skills from Ryan Singer →
Tom Conrad 1 quote
Listen to episode →
"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."
Tactical:
  • Be mindful that 'temporary' UI/UX decisions may last decades
  • Recognize that early implementation details can define long-term user expectations
View all skills from Tom Conrad →
Tamar Yehoshua 2 quotes
Listen to episode →
"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.'"
Tactical:
  • 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."
Tactical:
  • 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.
View all skills from Tamar Yehoshua →

Install This Skill

Add this skill to Claude Code, Cursor, or any AI coding assistant that supports Agent Skills.

1

Download the skill

Download SKILL.md
2

Add to your project

Create a folder in your project root and add the skill file:

.claude/skills/writing-specs-designs/SKILL.md
3

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