# Stoa - Full Content
> Multiplayer room for product teams who ship with agents. Live video, in-room AI agent that builds code, decision capture, runnable prototypes. Local-first. By SpecStory, Inc. App: https://meet.withstoa.com
---
# The jig is back
> Skilled craftspeople have always built jigs - small tools for one job in one shop. In software that cost a day or two, too much for a one-off. Agents change the math.
Published: 2026-05-19 - Author: nate - URL: https://withstoa.com/blog/the-jig-is-back
Agents are good at writing code. They're worse at the parts you have to see to judge, especially when there's no template, and what you want isn't on a Pinterest board or in another product's UI.
I was building the hero animation for [withstoa.com/sharelocalhost](https://withstoa.com/sharelocalhost) ... a paper plane that flies along a curve from the Share button at the top of the page down into the install steps below. The plane's flight path is an SVG cubic Bézier, which is a string of numbers that defines a curve. The agent wrote the first few versions by hand:
```ts
const PLANE_PATH =
"M 545 70 C 720 95, 720 270, 525 295 S 285 385, 165 470";
```

We weren't converging. I wanted the plane to loop through the headline and land in a particular spot, and the curves kept coming out wrong, and we'd be guessing - adjust some numbers, reload, look, adjust again. Cubic Béziers are weird. Small numeric changes produce big shape changes, and you can't predict what looks good without seeing it.
What I noticed after a while was that the agent and I were stuck for the same reason. The agent could write the path. I could see the result. But the loop between writing it and seeing it had a round-trip in it - me, reloading the page, eyeballing the curve, telling the agent what felt off. With each round we were both guessing. Neither of us could see what we were doing while we did it.
The obvious move was Illustrator - draw the path in a vector tool with handles, copy the `d` string out, paste it back into the source. That would have closed the loop for me, but it would have done less than I needed. Illustrator doesn't know about my easing curve, my motion ramp at takeoff, my plane-rotation logic, my dotted trail. What I was actually designing wasn't a static curve. It was the motion of a plane along the curve. And it would have taken the agent out of the loop entirely - every iteration becomes a handoff, the agent waiting at the end of each pass.
## I asked the agent for a tool instead
> can you code a tool that allows me to edit and view the path live in the localhost hero and then copy something for you to see?
It built one in about 5 minutes. A path editor as a React component that took over the hero when I added a URL parameter. Drag handles for anchors and control points, with dashed tangent lines back to their anchors. A live plane animating along the current path so I could see the motion at full speed while I edited. A textarea with the current `d` string and a Copy button so I could paste paths back to the agent.

The thing that mattered most: the editor and the production hero shared the same animation code. The editor wasn't a model of production. It *was* production, with drag handles on top. The motion I saw while editing was the motion that would render in the real page. We were back to designing the actual thing.

## The jig
Skilled craftspeople have always made tools for jobs the off-the-shelf ones couldn't handle. A woodworker making chairs builds a jig to cut the same compound angle six times. A photographer rigs a piece of cardboard onto a light to shape a shadow. A blacksmith makes tongs for the specific shape they're forging. The jig isn't fancy. It's not for sale. It exists for one job in one shop. That's the point.
In software, building a small project-specific tool has cost a day or two - too much for a problem you only had once. The default has been to reach for the closest off-the-shelf product, accept the friction, and move on.
Agents change that math. A lot of small tools that didn't quite justify themselves before now do. Custom debug overlays for the specific state shape of an app. Project-local scripts to reproduce a stubborn bug. Eval rigs tuned to the exact behavior a team is trying to verify in an LLM. Path editors for paper-plane animations. The category is wide and most of these tools never leave the project. They don't need to. They exist for one job in one project. That's the point.
---
---
# Remote Collaboration is becoming Multiplayer: What AR VR teaches us about AI-Native Work
> AR, VR, and MR research reframes remote collaboration as shared environments, presence, interaction, and now agency.
Published: 2026-05-08 - Author: antaripa - URL: https://withstoa.com/blog/remote-collaboration-ar-vr
Remote collaboration has improved a lot, but it still feels oddly flat. We can talk, share screens, write docs, and record meetings. Yet the actual feeling of building together often gets lost across tabs, transcripts, tickets, and follow-ups.
The paper "[A Survey on Synchronous Augmented, Virtual and Mixed Reality Remote Collaboration Systems](https://arxiv.org/abs/2102.05998)" is useful to visit. It reviews AR, VR, and MR collaboration systems and the interesting part is this paper does not treat remote collaboration as one category. Instead, it breaks these systems into three things:
- Environment: where the work happens
- Avatars: how people show up
- Interaction: what people can do together

This is a better model than the usual "remote work equals video calls" framing. A good collaboration system is not just a communication layer. It is a room. And a room is valuable because it creates shared context where people can point, react, decide, sketch, and move together.
The paper’s first idea, environment, is the most important one. Every tool creates a place, whether it is a Zoom grid, a Figma canvas, a GitHub PR, or a VR room. The quality of collaboration depends on how useful that place is. Can everyone see the same thing? Can the work and the conversation stay connected? Can decisions survive after the call ends?
The second idea, avatars, is really about presence. In AR and VR, this might mean hands, bodies, gaze, or spatial position. But the broader point is that collaborators need to be legible to each other. You should know where someone’s attention is, what they are reacting to, and what they are doing.
That becomes even more interesting with AI agents. What is the **avatar** of an agent? Not a cartoon face. Its avatar is its visible work. The team should know what the agent is editing, what context it is using, what it changed, and why.
The third idea, interaction, is where most remote tools fall short. Many tools let teams talk about work. Fewer let them actually do the work together. The gap between **great discussion** and **someone needs to turn this into something** is where momentum dies.
This is where the paper connects to AI-native collaboration. It gives us three layers, but today we need a fourth: agency.
So the stack becomes:
- Environment: where we work
- Presence: how humans and agents show up
- Interaction: what we can do together
- Agency: what the system can do with us
That is the direction we care about at **Stoa**. Remote collaboration is moving from communication to production. The meeting should not just create a transcript. The room should help create the spec, capture the decision, update the artifact, and let agents act on the shared context.
The big takeaway from the paper is simple: remote collaboration is not about making distance disappear. It is about designing better shared contexts. AR, VR, and MR tried to rebuild the room visually. AI-native collaboration makes the room active.
The next generation of remote tools will not just connect people.
They will give teams a multiplayer space where people and agents can think, decide, and build together.
---
Try https://withstoa.com for saving meeting context in an agent-friendly way.
---
# Measuring Decision Lag, the New Long Pole
> When agents can ship in hours, the slow part is deciding what to build. Intent Lead Time measures the gap between a product decision and the first implementation commit.
Published: 2026-05-05 - Author: isaac - URL: https://withstoa.com/blog/intent-lead-time-audit
When agents can ship in hours, the bottleneck is the decision. Most teams know when code landed. They do not know how long the decision sat before anyone wrote the first implementation commit.
A shipped change has a commit timestamp. The work before that commit is harder to see. When did the team decide to make the change? Stoa defines that gap as [Intent Lead Time](https://withstoa.com/guides/intent-lead-time): the time from product decision to first implementation commit.

We measured it by tracing recent Stoa work through four points: idea, decision, artifact, and first commit. Tracing a single decision back to its origin could take up to an hour of manual review across transcripts, docs, and git history. Even then, we still were not sure we had found the earliest signal.
## 1. Start With a Commit
The audit started with commits because Git gives the timestamp, message, and patch. The harder endpoint is the decision, which might live in a meeting transcript, meeting note, topic summary, Claude Code agent log, design doc, Slack thread, or nowhere structured at all.
`Intent Lead Time = first implementation commit - captured product decision`
The endpoints rarely sit next to each other. Some decisions never become commits, and some commits trace back through several earlier discussions.
To diagnose bottlenecks, each record tracked four dates:
- When was the idea first mentioned?
- When did we first decide to pursue the idea?
- When did the first tangible artifact, such as a design spec or prototype, get created?
- When was the first commit?
## 2. Pull Together the Sources
Each trace drew from four source groups:
1. Conversations. We exported sessions, transcripts, topics, meeting notes, summaries, and metadata from our database into local files.
2. Git history. We pulled commit metadata, changed files, and patches from the Stoa repo so implementation evidence could be inspected next to meeting evidence.
3. Design docs. We collected specs, prototypes, and other planning artifacts.
4. Slack and other side channels. We left these out of scope for this pass.
No source maps cleanly to one stage. A discussion may introduce the idea, record the decision, sketch a prototype, or only hint at the work. A prototype may follow a decision or start as the loose idea. A commit may implement the feature or preserve an experiment before the team has decided to pursue it.
The audit had to separate four kinds of evidence:
- intent evidence
- decision evidence
- design-doc evidence
- implementation evidence
## 3. Build Records From the Evidence
A record ties several artifacts to the same piece of work. A valid record might include:
- this meeting note introduced the idea
- this meeting transcript is where we decided to act
- this doc defined the approach details
- these commits implemented it
The initial target was the last week of work. The workspace grew beyond that because recent work pointed back to earlier docs and meetings. The current corpus covers a broader April window:
- 1,156 ingested commits
- 583 indexed docs
- 1,530 extracted doc items
- 94 current intent records
- about 1,000 evidence objects
Of the 94 records, 48 currently link to implementation commits, 42 are design-doc-only, and 4 have no commit found. Most records are still medium or low confidence.
## 4. Audit Whether the Records Are True
One feature, the starter-space template, showed why manual audit mattered.
New users should land in a prepared starter space when they first create an account, with files and examples already waiting in the workspace.
The first pass traced the decision to an April meeting. The team discussed how onboarding should copy the canonical starter space into a new org and decided to publish the files into Supabase/S3.
Manual audit found an earlier transcript: new users landed in Stoa without enough context. Several looser conversations circled the same fix: give users hands-on examples after signup. The implementation had a longer lead-in than the first trace showed.
The trace became:
1. Transcript: activation problem identification
2. Transcript: comment that we should give users a warm start
3. Transcript: discussion about pre-loaded use cases for new users
4. Transcript: explicit assignment to an individual
5. Design doc: onboarding flow
6. Implementation commits
Even with search and agents, this chain took manual audit. Slack was out of scope, so the trace may still miss earlier decisions.
## 5. Fix the Other Failure Modes
The same source-order problem appeared in another record. The first pass pointed to an April 22 implementation doc, but manual review found April 13 meeting evidence for the same work.
A second record failed differently: it used broad, noisy evidence and an April 14 decision timestamp that looked like follow-up context. The better source was an April 6 doc that described the idea before the later discussion.
If the source is wrong, the lead time is wrong. If the record combines several pieces of work, the number is a blend. If a follow-up note is treated as the original decision, the lead time stops meaning anything.
In both cases, the number changed only after manual review.
## 6. Use Semantic Search for Candidates
Semantic search helped because names drifted across systems. The same work might appear as `starter teammate` in a commit, `Theo` in a doc, and a first-meeting experience in meeting notes.
Agents seeded searches from commits, docs, and extracted meeting-note items. They expanded those searches with exact phrases, keywords, and semantic matches.
An agent reviewed the large candidate pool and clustered the candidates into possible records. Starting with candidates gave the agent evidence to verify, but manual audit still found missed links.
The pass produced 2,289 proposal files:
- 14 commit-first seeds
- 108 doc-first seeds
- 167 doc-item seeds
- 2,000 meeting-item seeds
Since most proposals required review, this workflow held up best:
1. Seed searches from commits, docs, doc items, and meeting items.
2. Use exact, keyword, and semantic search to gather possible matches.
3. Have an agent review and cluster the candidates.
4. Verify the source artifacts.
5. Apply the best-supported records.
## 7. Capture the Work Thread Earlier
The audit showed why this cannot stay a historical reconstruction exercise. We need a workspace that lets reviewers see meetings, docs, transcripts, and commits together, then inspect proposed links and missing pieces. A record needs auditable evidence that the artifacts describe the same work.
We also need to capture intent, decisions, docs, and implementation as work happens, so the trace exists before the audit starts.
We built 94 records, and most are still medium or low confidence. A single feature trace could touch six or more artifacts across four systems. Rebuilding the chain after the fact from disconnected systems is too fragile for an ongoing business metric.
Intent Lead Time has to be captured inside the way the team already works.
---
# AI Broke the Spec Handoff
> AI makes implementation move faster than traditional spec handoffs can carry context. Teams need to build the spec and prototype together.
Published: 2026-04-29 - Author: isaac - URL: https://withstoa.com/blog/ai-broke-spec-handoff
A PM can sketch a feature in the morning. By lunch, an agent-backed engineer can turn it into a working version with tests and docs. If the spec hides an assumption, the team finds out after it's done.
That changes what a spec has to be. A spec can't stay a handoff that one person writes and another person interprets later. The people who understand the product, design, and system constraints need to build the spec with the prototype together.
## The Old Loop Assumed Work Was Slow
Software teams reduce risk by moving slowly in small steps.
```
Spec
↓
Engineering review
↓
Design review
↓
PM finalization
↓
Engineering build
↓
QA
↓
Customer reaction
↓
Adjust
↺ back through the loop
```
Sprints, demos, and backlog reviews all assume the team can learn from mistakes before any bad ideas spread too far. Small steps helped with this product uncertainty, and that worked well because implementation took enough time that small steps is all you could do.
The tail of implementation (testing, hardening) is still real. But work can get much further before the next check-in, which means a small misunderstanding can turn into an implemented pattern that work is being built on top of in a day.
## Handoffs Leak Judgment
A good spec saves wasted motion. I like specs.
A spec usually travels as a handoff. The PM clarifies the problem, the engineer reads the document later, and the document is implemented in the product. On complex work, design and product review add more passes, and each pass loses a little context. A document can record decisions but it cannot carry all the judgment behind them.
The PM remembers which user quote mattered most. The engineer knows which service is about to change, which means we should sequence differently. The designer sees where a flow will confuse people. Those details shape the spec, but not every consideration is transferred with the spec.
For example, an engineer might make a small implementation choice to simplify implementation of the spec. To the PM, it removes future flexibility that they wanted to build toward but needed more customer feedback first. Writing and better specs help, but the leak wasn't a big deal when the loop was slow.
## The Leak Costs More Now
It's very easy for a document or an idea meant as a conversation starter can become a working flow before the PM realizes it was interpreted as direction. You can just build it. A small engineering shortcut can have tests, docs, and UI assumptions before the person rebuilding a server has time to review and say, "We have to reverse this next week".
These divergences can be in several repos in hours, and untangling them may take longer than creating them. And frustrating to the team. The team followed the process, interpreted the artifact in front of them, and then were told they didn't have the full picture and have to revert it. Demoralizing.
The team needs to catch these leaks while the work is being shaped, before it is customer ready work people are proud of.
## Build the Spec With the Prototype
With AI it's possible to build the prototype together with all the people who understand the problem (engineer, PM, designer, etc). Before that would be a live call where everyone waits for an engineer to code, which is miserable for everyone (especially for the engineer). An agent can build and change the prototype in seconds so everyone can stay in the discussion.
The PM is going to have things they learned from user interviews in mind. The designer is figuring out how to make it so a understandable and without footguns that will surprise the user. The engineer is pointing out which decisions require a huge change or new infrastructure, which let's the PM weigh how important that piece would be to users. All of this makes the prototype and the spec that comes from it sticky. The mental model for this feature was built together, and the spec is just solidifying details.
That is the point of a shared agent in a shared workspace. Everyone needs to see the same artifact and steer it while the spec is still forming. By the end there will be some artifact that is the first phase of work (not notes, but maybe a spec, a prototype, or whatever the point of the meeting was)
## A Meeting Can Be Engineering Work
I say this as an engineer because my instinct has always been to build first. I used to write code to understand the problem, and a lot of that happened in Jupyter notebooks because the code and visual feedback lived in the same place.
Shared agents move that loop into a room with everyone else on my team. The PM and designer do not have to wait for me to return with an interpretation. They can watch the interpretation form, build prototypes with me, and when I go build the final feature I don't have to guess what the PM/Designer had in mind on all the small implementation decisions that come up as I go.
And PMs often feels like pulling an engineer into a room feels like taking time away from code. That worry is often right. I would often be frustrated with high level notes and decisions. I know there's many layers of product decisions in the implementation details, but when I talk about implementation details I feel like nobody is interested and just want to talk general direction. I end up noting these as things to make a video about when I have a prototype or V1 built, because I can't seem to get the point across otherwise.
I am blocked until I have these discussion with others which means I know I will need another meeting to get the info I actually need. I've been so annoyed at this that, I've done toastmasters speaking clubs and hired communication coaches to try to communicate better so I can get my point across.
But building the whole prototype and getting into those details that's part of my implementation work live in the meetings solves all of that for me. And when the meeting ends I just continue building.
## Keep the Reasoning With the Work
The co-built spec only helps if the reasoning stays attached. In many companies, the spec is in Google Docs, prototype in github, debates in Slack, call notes in granola, tasks in linear/jira. That's...normal? Nobody searches five systems well to reconstruct one decision, and the coordination and syncing between all those systems gets skipped.
If you do try to keep all those systems up to date, and update them whenever any of them changes then you've rebuilt the handoff problem. The context cannot split across tools. The next person or agent needs the spec and decision trail in one place, because things will be missed otherwise.
## Scaling Without Putting Everyone in the Room
Fifty people cannot sit in every conversation. Some teams avoid coordination by staying tiny. Some let one person make all the taste calls. Some give each person a separate area. These choices work for a while, but they turn into bottlenecks with scale. If adding people feels scary because of management overhead, the team has not solved coordination yet.
Scaling means everything is together for the next person to join later. The prototype, transcript, agent session, spec all stay together. People can read a summary first, then ask their agent to dig into the source material when they need the details.
AI makes the work move faster. The reasoning has to move with it.
---
# Distance Still Matters: Why Context Slips Away in Remote Teams
> Why remote teams lose shared context faster, and how treating decisions as first-class artifacts can keep alignment intact.
Published: 2026-04-27 - Author: antaripa - URL: https://withstoa.com/blog/distance-still-matters-why-context-slips-away-in-remote-teams
In 2000, the paper [*Distance Matters*](https://doi.org/10.1207/S15327051HCI1523_4) made a point that still feels uncomfortable today. No matter how good our tools get, working at a distance comes with a cost that does not fully go away.
Back then, the concern was email and early video calls. Today teams run on Slack, Zoom, shared docs, and a growing layer of AI tools. Communication is constant. Everything is recorded somewhere. But that does not automatically mean teams are aligned.
## What Actually Breaks When Teams Move Apart
What the paper gets right is that collaboration is not just about exchanging information. It is about maintaining a shared understanding of what is happening and why. When people sit together, that understanding forms almost without effort. You overhear decisions, pick up context, notice when something is unclear, and resolve it quickly. Most of that never gets written down, but it keeps everyone moving in the same direction.
Once that environment disappears, nothing moves by default. Context has to be reconstructed, decisions have to be captured, and alignment has to be actively maintained. That is usually where things begin to drift.
This is what the paper was really pointing to. Remote work does not fail outright. It starts to strain in specific ways:
- teams lose shared context more easily
- tightly connected work becomes harder to coordinate
- tools help, but do not replace informal awareness
- processes can fix some gaps, but add overhead
- staying aligned simply takes more effort at a distance
None of this sounds dramatic on its own. But together, it explains why things start to feel slower, less clear, and harder to track as teams grow remotely.
## Where It Shows Up Today
You can see the same pattern in how teams describe their own setups today.

One founder laid it out bluntly. Their work was spread across Slack, Notion, Linear, Figma, GitHub, and more. Everything existed somewhere, but nothing was easy to track. So even though, all information were available but scattered, so people still felt lost.
In another discussion, the problem shows up even earlier.

A SaaS founder described how things start to break around ten people. At some point, with enough information moving around, you stop knowing who knows what. And once that happens, alignment becomes slower and more fragile.
This is the modern version of what Distance Matters described as a loss of common ground.
## The Problem Isn’t the Tools
The tricky part is that most tools are doing exactly what they are supposed to do. Messages are captured, documents are stored, code is tracked, but they do not stay connected. The reasoning behind a decision, the conversation that led to it, and the final implementation often live in different places.
Over time, that gap shows up in small ways. A decision gets revisited because no one remembers why it was made. A new team member struggles to understand how things evolved. A discussion moves forward without realizing that part of the context is missing. None of this feels like a major failure, but it slows everything down.
For smaller remote teams, this tends to show up early. There is less structure to absorb the gaps, so alignment depends heavily on shared context. When that context is scattered, progress starts to depend on reconstruction instead of momentum.
That is the lasting insight from Distance Matters. The real issue is not communication. It is the effort required to keep context intact as teams work apart.
## A Simple Shift That Helps
There is no single tool that fixes this. But there is a simple shift teams can make.
**Treat decisions as first-class artifacts.**
Decisions are not something that lives inside a meeting, or a thread, or someone’s memory. It should be captured, connected, and easy to find later.
In practice, this can be as simple as:
- writing down decisions as they happen, not after
- linking them to the work they affect
- making them visible to the team by default
It sounds small, but it changes how teams stay aligned. Instead of reconstructing context later, they carry it forward.
Although that does not remove the cost of distance, but it makes the cost visible, and easier to manage.
### Reference
- Olson, G. M., & Olson, J. S. (2000). Distance Matters. *Human-Computer Interaction*, 15(2-3), 139-178. https://doi.org/10.1207/S15327051HCI1523_4
---
[Try Stoa](https://meet.withstoa.com/sign-up) for saving meeting context in an agent-friendly way.
---
# The PRFAQ Is Dead. Long Live the Product Landing Page.
> The PRFAQ was a breakthrough in working backwards from the customer. But plain documents drift toward internal language and feature lists. A Product Landing Page keeps you honest.
Published: 2026-04-17 - Author: jake - URL: https://withstoa.com/blog/the-prfaq-is-dead-long-live-the-product-landing-page
The PRFAQ is one of the most influential product frameworks ever created.
Amazon popularized it. Colin Bryar and Bill Carr codified it in [*Working Backwards*](https://workingbackwards.com/resources/working-backwards-pr-faq/), and thousands of product teams adopted it. The core idea to write a press release and FAQ before you build anything is genuinely brilliant. It forces you to work backwards from the customer. To use their language. To articulate the benefit before you spec the feature.
I've written dozens of them. I've read hundreds more. And I've watched them miss their marks over and over again.
Not because the idea is wrong. Because the format is.
------
## What the PRFAQ Gets Right
Before we bury it, let's honor what it got right.
The PRFAQ's core insight is that **alignment starts with the customer's perspective, not your roadmap**. By forcing a team to write a something an outsider would read (i.e. a press release) it pulls you out of the internal bubble. You stop talking about "system capabilities" and start talking about what someone actually gets.
The FAQ section does something equally important: it surfaces the hard questions early. Pricing. Competitive positioning. Technical constraints. The stuff that usually gets deferred until it becomes a crisis.
When it works, a PRFAQ gives everyone across engineering, design, sales, leadership a single document to rally around. They all can read it and understand what you're building and why.
That's powerful. That's worth preserving.
## Where the PRFAQ Breaks Down
Here's where it goes wrong in practice.
**The press release itself is an anachronism.** When Amazon invented this process, press releases were how products reached the world. That hasn't been true for a long time. Most product managers today have never written a real press release and couldn't tell you what makes one good. The format is a relic of an era when journalists were the gatekeepers of attention. Today, customers discover products through landing pages, search results, social posts, and word of mouth. Asking a team to write a press release in 2026 is like asking them to draft a telegram. The working-backwards principle is timeless, but the container it shipped in is showing its age.
**Internal language creeps in.** And because nobody actually knows what a press release should read like, the format offers no natural resistance to internal drift. The document says "press release" at the top, but it's circulated internally. Reviewed internally. Revised internally. Within two rounds of feedback, the customer language is gone. You're back to phrases like, "leverage our platform to deliver seamless experiences". Thease are things that no customer has ever said or wanted to read.
**Features overwhelm benefits.** The press release format nudges you toward announcing what the product *does*. But customers don't care what it does. They care what it does *for them*. A PRFAQ that lists features without grounding each one in a specific customer outcome is just a spec dressed up in marketing clothes.
**It's missing half the product.** A PRFAQ typically covers the what and the why. But it says nothing about pricing, packaging, visual design, information hierarchy, or how the product actually *feels*. These aren't cosmetic details; they're core to whether the product succeeds. A product with the right features and the wrong pricing page fails. A product with a brilliant value proposition and a confusing layout fails. The PRFAQ is silent on all of this.
## What a PRFAQ Should Be in 2026
The insight that you should work backwards from your customer is more important than ever. Software development is faster. AI compresses the build cycle. The bottleneck has shifted from "can we build it" to "should we build it" and "are we building the right version of it."
Alignment is the new constraint. And alignment requires something richer than a document.
**It requires a Product Landing Page.**
## The Product Landing Page: A PRFAQ You Can See
A Product Landing Page (PLP) is exactly what it sounds like: a real landing page for a product that doesn't exist yet. Not a mockup in Figma. Not a wireframe. A web page, with a headline, subhead, feature/benefit sections, pricing, FAQ, testimonials, and a call to action.
And yes, you should put it on the internet. Before the product is ready. This isn't radical. It's what Y Combinator tells every batch to do. It's what lean startups have done for fifteen years. Ship the page, collect signups, learn what resonates. Your landing page can be your first experiment product experiment. Nothing drives alignment like outside feedback.
Here's why a PLP succeeds where a PRFAQ stalls:
**It forces outside-in thinking automatically.** When you're designing a web page, you instinctively think about the visitor. What do they see first? What do they need to understand in five seconds? What would make them scroll? You don't have to remind yourself to use customer language becayse the format demands it. Nobody writes "leverage our platform capabilities" on a landing page. They write "Ship faster with fewer meetings."
**It makes you commit to positioning.** A headline is a position. A subhead is a promise. A landing page doesn't let you hedge. The PRFAQ lets you bury your positioning in a paragraph halfway down the document while the PLP puts it in 60-point type at the top of the page. If your team can't agree on the headline, that's a signal you haven't converged on what the product actually is.
**It includes what the PRFAQ leaves out.** Pricing. Packaging. Visual hierarchy. The information architecture of how you present your product to the world. A PLP makes these first-class concerns, not afterthoughts. When you draft a pricing section, you're forced to answer: who is this for? What do they pay today? What's the anchoring? These questions surface months earlier than they would in a traditional PRFAQ process.
**It's tangible.** A document is abstract. A page is concrete. When your engineering lead looks at a PLP, they don't just understand the product, they can *see* it (or at least squint at it). When your CEO looks at the page, they can react to the actual framing, not a description of the framing. This collapses feedback cycles and improves the quality of the feedback you receive.
## How to Write a PRFAQ as a Product Landing Page
The PLP isn't a rejection of the PRFAQ's principles. It's a better container for them. Here's how the pieces map:
**The press release becomes the hero section.** Your headline is the one-sentence version of what this product does for the customer. Your subhead is the expanded benefit. Your hero section is the press release distilled and sharpened, with no jargon.
**The customer quotes become testimonials.** In a PRFAQ, you write imaginary customer quotes. In a PLP, you write imaginary testimonials and you place them on the page where they'd actually appear. This small change is surprisingly powerful. A testimonial on a landing page has to sound like something a real person would say. A quote in a document just has to sound plausible to the PM who wrote it.
**The FAQ stays an FAQ.** This is the one piece that transfers directly. Keep it. Put it at the bottom of the page where FAQs live. But now it sits in the context of everything above it so the questions and answers are sharper.
**The feature list becomes benefit sections.** Instead of bullet points in a document, you design sections with headlines, descriptions, and visuals. Each section has to earn its place on the page. If a feature doesn't warrant its own section with a clear benefit headline, maybe it's not a headline feature.
**Visuals go on the page, not in a separate deck.** This is where the PLP pulls furthest ahead of a document. Add wireframes, rough prototypes, screenshots of a prototype, short videos, animations or whatever gives the product visual bones. You're not building the product yet, but you're showing what it could look and feel like. AI makes this fast. You can generate a helpful product wireframe in an hour or two, drop it into a hero image or feature section, and suddenly the page *feels* like a real product. A PRFAQ with an attached Figma link is two artifacts fighting for attention. A PLP with visuals inline is one coherent story.
**Pricing gets a section.** You don't need final pricing. But you need a pricing *shape*. Free tier? Per-seat? Usage-based? Enterprise? Putting a pricing section on the PLP forces this conversation early, which is exactly when you want to have it. Pricing shapes the product, not the other way around.
## The Ideal Customer Testimonial Test
Here's a technique that works especially well in the PLP format.
Write three testimonials from your ideal customers. Not real quotes but aspirational ones. The testimonial you'd *want* to earn after the product ships.
Then look at them honestly:
- Do they describe outcomes, or features?
- Would a real person say this, or does it sound like marketing?
- Do they represent different use cases or customer segments?
- Does the rest of your page actually deliver on what these testimonials promise?
If your ideal testimonial says *"We cut our planning cycle from six weeks to two"* but nothing on your page explains how, you've found a gap. If your testimonial sounds like something only a product manager would say, you've drifted back inside.
The testimonials are your compass. They tell you what the page should prove.
## Why This Matters More Now
The pace of software development has changed. AI-assisted development means a small team can build in weeks what used to take months. The constraint now isn't speed, it's direction.
When you can build fast, building the wrong thing is more expensive than ever. Not in dollars, but in opportunity cost. Every day spent on the wrong feature is a day you could have spent on the right one. And the teams that win aren't the ones that ship the most code, but ones that align the fastest on what to build.
A Product Landing Page creates alignment that a document can't. It's visual, so designers engage with it. It's concrete, so engineers can respond to it. It has pricing, so business stakeholders can react to it. It uses customer language, so everyone is oriented around the same outside-in perspective.
It's a PRFAQ you can see. And seeing is aligning.
## Getting Started: PRFAQ to Product Landing Page in Practice
You don't need a designer. You don't need a developer. You need a tool that lets you draft a real page.
1. **Start with the headline.** Write ten versions. Pick the one that a stranger would understand in five seconds. That's your product.
2. **Write the subhead.** One sentence that expands the headline into a promise.
3. **Draft three benefit sections.** Each one gets a headline, a two-sentence description, and an imaginary screenshot or wireframe. If you can't describe the benefit in a headline, it's a feature not a benefit.
4. **Add a pricing section.** Even if it's rough. Especially if it's rough. The arguments you have about pricing now are arguments you won't have in month four.
5. **Write the FAQ.** Steal this straight from the PRFAQ playbook. What would a skeptical customer ask?
6. **Write three ideal testimonials.** Then check: does the page above actually deliver on what these testimonials claim?
7. **Share it.** Not as a doc. As a published web page. Send the link. Watch people react to it like a real product page.
------
The PRFAQ was built for a world where writing a document was the fastest way to align a team. That world has changed but the principles haven't. Work backwards, use customer language, surface the hard questions early.
A Product Landing Page preserves everything that made the PRFAQ great and adds everything it was missing: visual design, pricing, information hierarchy, and the automatic outside-in discipline that comes from building something a customer might actually see.
Your next product spec shouldn't be a press release.
It should be a landing page.
If you're not yet ready to build a PLP - if you're still pressure-testing whether the opportunity is real - start one step earlier with a [Lean Canvas](https://www.leanfoundry.com/books/running-lean). It forces you to articulate your problem, solution, unfair advantage, and revenue model on a single page. Once that canvas feels solid, you have everything you need to draft a Product Landing Page that brings it to life.
The Lean Canvas gives you a one-page snapshot of your product opportunity - problem, solution, key metrics, unfair advantage, and revenue streams. Fill it out before you write a single headline.
Download the Lean Canvas (SVG)
---
# Sharing the Thinking Behind the Thinking
> AI makes human reasoning invisible. Four practices to close the new communication gap.
Published: 2026-03-29 - Author: jake - URL: https://withstoa.com/blog/sharing-the-thinking-behind-the-thinking
Here's a scene playing out in thousands of teams right now:

Two AI calls. Zero thinking transferred. A perfectly efficient system for communicating almost nothing.
------
We laugh, but the joke lands because we've all been on one side of it. And the real problem isn't the wasted tokens, it's what's missing from the middle.
The author had *reasons* for those three bullets and depth behind each. They knew which one mattered most. They knew the second one was controversial. They had context from a customer call that shaped the third. None of that made it into the polished doc even though the document looked done.
The recipient, reading something that looked done, treated it as if it were authored with human intent. They didn't push back, didn't ask questions, didn't engage with the thinking because the artifact presented no thinking to engage with. Just conclusions, wrapped in confident prose that a machine wrote and a human sort of endorsed.
This is the new communication gap. It's not a lack of clarity; it's a lack of *provenance*. The person reading your work doesn't know what's yours and what's the machine's. They don't know what you wrestled with, what you rejected, or where your judgment actually shaped the output. And without that, they can't do their job, which is to bring their own context and judgment to the thing you made.
------
### The ironic inversion
Here's what's strange about this moment: AI reasoning is becoming *more* visible while human reasoning is becoming *less* visible.
Models now ship with chain-of-thought, reasoning traces, "thinking" blocks. You can literally watch the machine show its work.
But the human? The person who chose this framing over that one, who rejected the first approach because they knew something about the system the AI didn't, who re-prompted a dozen times before the output matched what they actually meant? Their thinking has no artifact. No format. No convention. No place to live.
The AI's reasoning is now more recoverable than the human's. If someone ships code and the model used chain-of-thought, you can at least reconstruct some of the AI's path. The human's twelve prompt iterations and the approach they rejected? Gone.
We've arrived at a world where the machine shows its work and the person doesn't.
------
### Why this breaks teams
For solo work, the invisible thinking problem is fine. You remember your own reasoning. You were there.
For teams, it's corrosive. And it compounds.
Solo AI works because context is unified in one head. The person *is* the memory layer. Teams break because the faster individuals move with AI, the more invisible their reasoning becomes to everyone else. AI-generated output accelerates this because it looks *finished*. Polish forecloses the questions that rougher work would naturally invite.
When you get a half-formed sketch from a teammate, you naturally ask: "What are you thinking here?" When you get a polished document, you assume the thinking is done. You might disagree with the conclusion, but you engage with it as a conclusion and not as a draft of someone's reasoning that needs your input.
The fastest approach (for an author) is to just copy the AI output, and throw it over the wall. It's tempting because the output looks finished. The code compiles. The doc is well-structured. BUT there's no obvious signal that the person who sent it spent three minutes with it or three hours.
When you send too quickly, you're not just skipping your own quality check, you're transferring the cognitive burden to everyone downstream. Someone else now has to figure out whether this thing is good, whether it fits, whether the assumptions behind it hold. You had that context. You just didn't share it.
And here's the trust spiral: once people get burned by polished-but-hollow work a few times, they stop engaging carefully with *any* AI-assisted output. The team's collective quality bar drops, not because the AI got worse, but because nobody trusts the human layer anymore.
------
### What to do about it
This isn't a problem you solve with a policy memo. It's a set of small habits that change how your team communicates. Here are four that work:
**1. Label the provenance.**
Start marking your internal docs and artifacts as AI-generated, human-generated, or human-edited. It sounds almost too simple, but try it for a week. What changes is how your team *reads*. When people know a doc was AI-assisted, they bring more skepticism to the structure and more attention to whether the reasoning holds. When they know it was human-written, they trust that there's intention behind it and can engage more deeply. The label doesn't slow anything down. It just restores a signal that AI quietly removed.
A lightweight version: just add a line at the top. "Drafted with Claude, edited and restructured by me. The recommendations in section 3 are mine; the market analysis is mostly AI-generated."
**2. Annotate your reasoning, not just your output.**
The opposite of slinging slop isn't perfecting, it's annotating. When you share AI-assisted work, include a few lines about your decisions:
- "I asked for three approaches and picked this one because X"
- "The AI suggested including Y but I cut it because we tried that last quarter and it didn't move the needle"
- "I'm least confident in the pricing section; that needs someone with more context on enterprise deals"
This takes sixty seconds and transforms how the next person engages. They're no longer evaluating a finished artifact, they're joining a conversation about decisions, with enough context to add their own judgment.
**3. Share the intent, not just the conclusion.**
Write your plans before your implementations. Not a polished spec but a working doc. The problem you're solving, the approaches you considered, the one you picked and why. Put it next to the code or presentation. Share it before you start building.
If you already do this, try giving each other feedback on these docs before jumping to implementation. You'll be surprised how much misalignment surfaces in five minutes of reading someone else's reasoning.
**4. Make "show your work" a team norm, not a personal virtue.**
"Show your work" used to mean math class. Now it means: show the decisions you made on top of what the AI gave you. This only works if it's a team norm, not something one conscientious person does.
In practice: PRs include a sentence about which parts were AI-generated and what the human shaped. Design docs have a "decisions made" section. Slack threads about AI-generated analysis include what the person checked and what they didn't.
The format doesn't matter. What matters is the habit of making human judgment visible alongside the AI output. Because your teammates need *your* thinking to do their jobs.
------
### The team that shares thinking compounds
Here's the payoff for getting this right: the team that shares thinking compounds its intelligence. Every artifact carries context. Every handoff includes reasoning. The next person doesn't start from zero; they start from where you left off, with enough understanding to build on your judgment instead of just reacting to your output.
The team that shares only output stays flat. Each person re-derives the context. Each handoff loses information. The AI gets better every month, but the team's collective understanding doesn't improve because nobody's thinking is making it into the shared record.
You have three bullet points. Instead of inflating them into a polished doc, you share the bullets, with a line about why each one matters, what you're not sure about, and what you need from your team.
Your team reads it in two minutes instead of twenty. They respond with their own context. A real conversation happens.
No AI required.
(This article was generated using Claude against a corpus of draft ideas and transcripts of conversations and monologues I've had over the past year. I did 4 passes of prompting on the overall doc, and 4 passes of prompting on the comic image. I then read and hand-edited the entire document.)
---
# Turning a White-Glove Process Into a Self-Serve Workflow
> Denise is CEO and co-founder of Variata, an AI-powered testing platform. Her product lets teams validate their websit...
Published: 2026-03-24 - Author: jake - URL: https://withstoa.com/blog/turning-a-white-glove-process-into
Denise is CEO and co-founder of Variata, an AI-powered testing platform. Her product lets teams validate their websites and apps by describing what they want tested instead of writing brittle, step-by-step automation scripts. Variata AI figures out how to navigate the site, run the flows, and report what broke.
It works. Enterprise customers love it. But there's a catch: every new customer goes through a white-glove onboarding where Denise's team manually authors the test scenarios alongside them. They identify the highest-value flows, tune the inputs to the right level of specificity, and build a working setup that would've taken weeks for in-house QA teams to develop in just a day's time.
That process produces great outcomes and teams are already saving lots of time with Variata. But now Denise is thinking about scale.

So she set out to build the self-serve version including an authoring tool that would help users create their own test scenarios without her team in the room. She's done discovery across paying customers, free trial users, and casual evaluators. She's identified a spectrum of user inputs ranging from "just test my site" to granular click-by-click scripts. She's built three prototype classifiers to guide users toward the sweet spot.
These are all the pieces. The question is how they fit together.
Denise and I help each other as founders, and this month we used her self-service challenge as the topic of our conversation. It gave me a chance to work through a real product planning scenario that will help us build Stoa (our conversational planning tool) and it gave her an outside perspective. This session led us past some strong product principles so I decided to write it up and share it.
---
## **The Spectrum Problem**
Here's the tension Denise was staring at. Variata's AI works best when it gets input at a middle level of abstraction -- milestones and expected outcomes, not pixel-level instructions. "Verify the sign-up flow works and the user lands on the dashboard" is better than "click the email field, type test@gmail.com, click the password field, type abc123, click Submit." The specific version latches onto details that change constantly. The milestone version is durable.
But users don't naturally land in that middle zone. QA engineers tend to over-specify. Product managers and executives tend to under-specify. And the "just test my site" crowd gives almost nothing to work with.
So the question Denise was trying to answer: how do you build an AI-assisted authoring experience that nudges users toward the level of detail that actually produces reliable tests?
She'd prototyped three approaches. (1) A binary gate that gives a simple yes/no depending on whether your test prompt is sufficient. (2) A gap coach that shows you specifically what's missing. And (3) a clarifying Q&A coach that asks questions until it has enough to work with.
Before evaluating any of them, though, there's a more fundamental question we decided to tackle.
---
## **Whose Problem Is This?**
It's easy to describe this challenge in system terms: *how do we ensure users provide input that maximizes Variata's success rate?* That framing is accurate. It's also a trap, because it centers the product's needs rather than the user's.
Flip it around. What's the user actually trying to do?
Denise described a Product Leader she'd spoken with- someone who manually runs twenty user flows every morning. An hour of clicking through their own site with a coffee, testing that the promo codes work, the checkout completes, the filters behave. Not because it's in their job description. Because they feel personally responsible for their site.
That person's problem isn't "I need to author test scenarios at the right level of abstraction for an AI system." Their problem is: *I have a process that works, I want it to keep working, and I'd like my morning back.*
That reframe matters because it changes what success looks like. The authoring tool isn't asking users to learn a new skill. It's asking them to hand over something they already do and trust that it'll be done right.
> **Reframe the problem from the user's side before designing solutions.** "How do we get better input for our system" and "how do I get my morning back" lead to very different products.
---
## **Who Exactly Are You Building For?**
Denise had mapped out several personas: QA testers, product managers, developers, enterprise buyers, self-serve evaluators. She'd segmented by release cadence and personal risk. The users who keep coming back are the ones who have to sign off on revenue-driving releases at least monthly.
But "people who sign off on releases" is still a broad group. And a self-serve product can only have one front door.
The narrowing question: who, specifically, is going to try this tool on their own, fall in love with it, and then fight to get it adopted inside their company?
Not the QA engineer; at least not at first. Some will resist a tool that automates their core job. The person who will champion Variata from the bottom up is the product leader or VP who does QA out of intrinsic motivation. They're doing it because nobody else will, they care about quality, and they'd happily hand it off to a system they trust.
That person also happens to have the organizational leverage to push deals forward from below while the Variata sales team works with executives from above.
> **Pick the champion, not the job title.** The user most likely to adopt and evangelize your self-serve product isn't always the one whose role most obviously matches your category. Look for intrinsic motivation plus organizational influence.
---
## **What Already Works**
Here's where the conversation got interesting. Before evaluating the three prototypes, it's worth asking: what happens in the manual version that works so well?
When Denise's team onboards a new customer by hand, what does the session actually look like? What's on the screen? Where does the input come from?
Her answer was surprising. Users don't typically pull up their live product and walk through it together. Instead, they show up with requirements documents from Jira tickets, specs, runbooks, and email attachments describing features they need tested. Sometimes the features don't even exist in a live environment yet. The user is working from a written description of something they didn't build and may never have seen running.
So Denise's team takes that document and, sitting alongside the user, translates it into testable scenarios at the right level of abstraction. They author a few together so the user can see the pattern. Then they send the user off to do the rest as homework.
That's the workflow. And it reframes the entire product challenge into one sentence: **help people turn their requirements documents into testable scenarios.**
Not "build a chatbot that asks smart questions." Not "create a test recorder that watches you click." Just: take the artifact the user already has and transform it into something Variata can run.
> **Study your manual process before automating it.** The best self-serve products don't invent new workflows. They bottle the proven ones. If your team already knows what works in the white-glove version, the product's job is to encode that, not reimagine it from scratch.
---
## **The Case Against Questions**
Back to the three prototypes: (1) a pass/fail binary gate on your testing inputs, (2) a coach that shows you the gaps between your input and expected structure, and (3) a Q&A workflow. With the problem compressed to "requirements in, testable scenarios out," each approach looks different.
The binary gate is clearly too blunt. Telling someone "not enough detail, try again" when you have an LLM that can reason about exactly what's missing is, as Denise put it, "a little bit lazy."
The clarifying Q&A flow is more sophisticated. It mimics the experience of Claude Code or Codex- thinking, then surfacing questions like "What's the expected outcome of a successful sign-up?" with selectable options. It feels smart.
But there's a structural problem with questions: how do you know when to stop asking them? There's a fine line between "your questions are helpful" and "your questions are annoying," and that line moves depending on the user's patience and context. Ask too few and you don't have enough to work with. Ask too many and the user gives up.
More importantly, questions don't teach. If the AI asks clarifying questions today, it'll have to ask clarifying questions again tomorrow. The user never learns what a good testable scenario looks like. Instead they just get walked through one instance.
The gap coaching approach does something different. It shows the user a target that lets them build a mental model; here's what a complete, well-formed scenario looks like. This, along with highlights of the specific gaps in what they provided can be powerful. Instead of an interrogation, it's a progress bar toward a visible standard.
That means the user learns the shape of a good scenario. Next time through, they need less help. The product is building user capability, not user dependency.
> **Show what good looks like instead of interrogating toward it.** A coaching UI that reveals the target teaches users to self-serve over time. An open-ended Q&A creates a recurring dependency on the system. The best onboarding doesn't just get users through -- it makes them better.
---
## **The Bigger Pattern**
Denise walked into this conversation with a clear picture of Variata's overall story and ROI journey. All we did together was zoom into one specific moment in that journey and get concrete about who's there, what they're holding, and what they need next.
The pieces were all present in her research. The Product Leader with the morning coffee ritual. The requirements docs that users show up with. The white-glove process that already works. The insight that coaching beats interrogation.
Sometimes product work isn't about generating new ideas. It's about compressing what you already know until the next move becomes obvious.
---
Want a workspace to have your own product clarity sessions? Try [https://somehow.sh](https://somehow.sh)
---
# Solo AI Keeps Getting Better. Team AI Keeps Getting Worse.
> The problem isn't the tools - it's context fragmentation. Solo productivity is up, team coherence is down.
Published: 2026-03-20 - Author: jake - URL: https://withstoa.com/blog/solo-ai-keeps-getting-better-team-ai-keeps-getting-worse
Solo AI keeps getting better. Every month the tools improve with faster models, better context windows, smarter agents. A single person with a clear idea can turn it into working software in an afternoon. That loop is getting tighter and tighter, and there's no ceiling in sight.

Team AI keeps getting worse. Not because the tools are bad, but because the faster individuals move, the more visible the gaps between them become. Decisions get made in private sessions. Context lives in one person's head. The team's shared understanding fragments a little more every week. AI didn't create this problem, but it's accelerating it.
------
Here's what we've been sitting with at SpecStory.
A tight team should beat a solo operator. Not because of more hands but because of more angles on the same problem. Greg talked to users the others didn't. I have context from sales calls that never made it into a doc. Sean knows which part of the system will buckle under a particular design choice. No one has the full picture. Everyone has a piece. And even though we're all coding, we need to align on something higher level than the code.
That diversity of context is a genuine multiplier if it can actually be harnessed. Right now, it can't. It's trapped in people's heads, scattered across Slack threads, buried in meetings that ended without a record. The conversations where the real thinking happened are gone by the time anyone needs them.
So what happens instead? Each one of us tries to hold it all together. We become the memory for our team, trying to preserve every insight, tradeoff, and decision. When it was just three of us, that worked (barely). Now it's breaking as we approach ten. And while all we want to do is build and sell, we're now spending half our time revisiting or re-explaining context we've already built up but just can't find anymore.
------
A lot of people reach for "new workflows" as the answer. More check-ins. Better handoff docs. Daily standups with AI on the agenda. We resist these reflexively.
These help at the margins. But they're treating the symptom rather than the cause: the intent that produced the work was never captured as a shared artifact in the first place.
The habit shift that actually matters is treating intent as something the whole team owns.
Not just prompts, whole conversations. The sync where someone pushed back on the original approach. The design review where a tradeoff got made. The customer call that reframed the whole problem. That context exists. It just evaporates the moment a meeting ends, inaccessible to the next person who needs it and invisible to the agents that could use it.
One concrete thing we do to mitigate this is to **write our plans in markdown and share them.** Just a working doc, not a polished spec. The problem we're solving, the approaches we've considered, the one we picked and why. Then we show it to each other. This is an easy habit to adopt, and if you already have, try going one step further and give each other feedback on these docs (not as an implementation gate, just as a way to build shared understanding and improve). You'd be surprised how much misalignment surfaces in five minutes of reading someone else's reasoning.
------
As we started doing this, we noticed a related trust problem that snuck up on us.
As more of our output, including these plans, were written with AI assistance, reading became not only a bottleneck but also required a new lens. Is this doc the product of an hour of thinking, or sixty seconds of prompting? Did someone shape this, or just ship it? The artifact often looks the same either way. And when we couldn't tell, we started discounting each others' work (or worse, we stopped reading with care).
A simple fix if you're hitting this same problem: **label your internal docs as AI-generated, human-generated, or both.** Give some indiction of how much time and effort you spent iterating on them. It sounds almost too simple, but try it for a week. What changes is how your team *reads*. When people know a doc was AI-generated, they engage with it differently by bringing more skepticism to the content and more attention to whether the reasoning holds. When they know it was human-written, they trust the judgment (or at least the intent) behind it more. The label doesn't slow anything down. It just restores a signal that AI quietly removed.
------
The team AI problem isn't a tools problem. It's a context problem. How do you make the distributed knowledge of a team like reasoning, tradeoffs, and context available to the people and agents doing the work?
We don't have a complete answer yet. But we're increasingly convinced the path runs through intent. Not capturing what got shipped, but why. Conversations as a team resource. Context as something you manage deliberately, the way you manage code.
Solo AI is simple. One person, one mental model, clean execution.
Team AI is harder. Multiple people, distributed intent, conversations that need to compound instead of evaporate.
That's the frontier we're building toward. See more at https://withstoa.com
---
# Please Review the Safety Card Before Airdropping Your Prototype
> At a recent product and engineering leadership roundtable, a PM director said: \"I built a prototype that shows exactl...
Published: 2026-03-16 - Author: jake - URL: https://withstoa.com/blog/please-review-the-safety-card-before
At a recent product and engineering leadership roundtable, a PM director said: "I built a prototype that shows exactly what I want, with more clarity than any PRD I've ever written and my engineers weren't excited. They were *resistant*."
Then a long debate followed about changing roles and AI code quality and the shifting job market. But I don't think any of that was the real reason for resistance. I asked a simple question: "when did you share your prototype?"
A confused look and then a hesitant, "after I finished building it."
And there was the problem: **what feels like resistance is actually an ask for inclusion.**
Not "give me a more detailed specification", not "fix your prototype's broken code", but "bring me along for the ride".

---
Think about what happens when a PM drops a fully-formed prototype on an engineer's desk. The PM has spent hours, maybe days, in conversation with an AI tool, exploring options, hitting dead ends, making tradeoffs, arriving at a solution that feels *right* to them. They've weathered the whole storm of the creative process.
Then they hand over the sunny outcome and say: "Here. Build this."
The engineer looks at it and feels... something. Not excitement. Something more like being airdropped into the eye of someone else's brain storm. The air is calm here, but they can see the wreckage of decisions they weren't part of. Why this data model? Why this flow and not the obvious alternative? What got tried and rejected? What tradeoffs were made, and who decided?
The prototype answers "what." It doesn't answer any of the "whys." And without the "whys," the engineer can't do their job because engineering is the art of making good local decisions when you hit unexpected constraints, and you can only do that if you understand the *intent* behind the thing you're building.
**Nobody likes to be airdropped into the middle of someone else's storm.** But everyone loves a good story -- a clear sequence of thinking they can follow, with a beginning, a middle, and a chance to shape the ending.
---
Every great PM already knows this. It's why the best PRD reviews have never been signoff sessions. They're conversations where the team pokes at the solution together: "What happens when the user doesn't have an account?" "What if the API call fails mid-flow?" "This edge case seems ambiguous; can we nail it down right now?"
Traditionally we justified this discussion in terms of cost. Clarifying questions, surfaced in a review, cost an hour to resolve. The same questions surfaced after engineering is underway cost a week. Surfaced in QA? A month. Now, with the cost of rework plummeting, it feels like these tradeoffs no longer hold. But there was another subtler reason for these meetings.
The PRD review worked because the document *felt* open. It was words on a page. It was clearly a draft of thinking, not a finished product. People felt invited to push back, ask questions, and shape the direction. The document said, implicitly: "This is what I'm thinking. Help me think better."
A working prototype sends the opposite signal. It looks *done*. It runs. It has buttons that click and screens that flow. Even if the PM knows it's held together with duct tape and AI hallucinations, the engineer sees something that looks finished and hears: "I've already decided. Just make it production-ready."
That's the resistance. It's not about the prototype. It's about being handed a conclusion without the reasoning.
---
So what do you do? You don't stop prototyping. The ability to express product thinking as working software is a genuine superpower that we shouldn't lose.
But you **turn over your thinking in stages**, even if those stages happened quickly.
At SpecStory, we've been working on this problem, and we call the practice an **intent review**. It's distinct from a code review. A code review asks: "Did we build it right?" An intent review asks: "Are we building the right thing and does everyone understand *why*?"
Here's what that looks like in practice:
**Share the problem before the solution.** Before anyone sees the prototype, share the customer insight or the problem statement that motivated it. Give the team the same starting point you had. Let them sit with the problem for even a few minutes before you show them your answer.
**Show your exploration, not just your conclusion.** What did you try that didn't work? What tradeoffs did you make? What alternatives did you consider? This is the "story" part -- the sequence of thinking that makes the conclusion make sense. If you explored three approaches and chose one, show all three. Let the engineer see *why* this one won.
**Name your confidence level.** There's a huge difference between "this is what I think we should build" and "these are two approaches I'm deciding between" and "this is an initial exploration, let's iterate." Naming where you are changes how people engage with what you're showing them.
**Invite the storm, don't shelter people from it.** The messiness of the creative process isn't a bug, it's where the best engineering input happens. When an engineer sees the problem space, not just the solution, they bring constraints and possibilities that make the product better. That's not resistance. That's collaboration.
---
Our new tools don't change our humanity. AI can collapse the time between idea and prototype from weeks to hours, but it can't collapse the human need to understand *why* before committing to *what*. An engineer who understands the intent behind a prototype will make a hundred good decisions during implementation that you never anticipated. An engineer who's just been handed a thing to rebuild will ask you about every single one.
The fastest path to production isn't a better prototype. It's a team that shares your understanding of the problem.
So the next time you're excited to show your team something you built (and you should be), pause for just a moment. Don't airdrop them into the eye of your storm.
Tell them the story of the storm first. Then show them where you landed. Then ask them where *they* think you should go.
That's not slower. That's how you get there together.
---
# Why Your Product Decisions Keep Getting Relitigated
> Relitigated decisions stem from mixing divergent and convergent thinking. Name the mode before you start.
Published: 2026-03-10 - Author: jake - URL: https://withstoa.com/blog/why-your-product-decisions-keep-getting-relitigated
I just ended a team meeting with that familiar, slightly hollow feeling.

Everyone talked. A lot.
We'd spent over an hour together. Slack will no doubt soon show another dozen follow-ups. Someone must've taken notes, right?
And yet I couldn't answer the one question that mattered:
Did we actually decide anything?
Nobody said it out loud, but you could see it on people's faces as the call ended. The subtle hesitation before leaving the Zoom. The quiet, "okay… talk later."
It's the feeling of motion without progress.
I've seen this pattern enough times to recognize it now. It isn't about personalities, and it isn't even really about meeting facilitation.
It's about something much simpler.
We were mixing two completely different kinds of thinking in the same conversation.
In the language of design thinking, we had a divergence / convergence problem.
------
Every productive conversation moves through two distinct phases, and they're not compatible with each other.
**Divergent thinking** opens things up. It asks: what are we missing? What alternatives haven't we considered? What does the person who disagrees with us see that we don't? This mode is generative. It requires psychological safety, patience, and a willingness to sit with ambiguity.
**Convergent thinking** closes things down. It asks: given what we know, what's the best path forward? It requires criteria, tradeoffs, and the courage to leave good options on the table in service of a decision.
Great teams move between these modes intentionally. Most teams blur them together and wonder why nothing sticks.
The tell is in the friction. When someone pushes back with a new idea during what the leader thought was a decision moment, that's divergent energy colliding with a convergent expectation. When someone asks "so what are we actually deciding?" in the middle of an open brainstorm, that's convergent pressure crashing into a divergent space. Neither person is wrong. They're just in different modes, and nobody said which mode the room was in.
------
The fix isn't complicated, but it requires intentionality.
**Name the mode before you start.** Before any agenda item, say out loud which phase you're in. "For the next fifteen minutes, I want us to think expansively. Nothing is decided yet, all options are on the table." Or: "We've done the exploration. Now I want to converge on a recommendation." These aren't magic words, but they orient the room. People stop fighting the current when they know which direction it's flowing.
**Signal the transition and acknowledge the shift.** Most meetings have a natural inflection point where the conversation wants to move from exploration to decision. Most facilitators miss it and let the meeting drift. The better move is to name it out loud: "I think we have enough on the table. Let's converge." But the transition is also the moment some people feel unheard, so a small acknowledgment goes a long way: "We've heard the concerns. Let's hold those and move toward a recommendation."
**Match your mode to the stakes.** Not every topic deserves a full divergent phase. Small decisions don't need open-ended exploration - jumping straight to convergence is efficient and appropriate. But big decisions that haven't had a real divergent phase are dangerous. You're choosing between options someone already filtered, without knowing what got left out. The bigger the decision, the more intentional you need to be about earning your convergence.
**Write to converge.** When you think the room has landed somewhere, don't just say it. Write it. Share your screen or open a shared doc and try to put the convergence into words in real time: what did we decide, and what's the reasoning? This does two things. It exposes gaps immediately, and it creates a record that everyone can push back on before the meeting ends, rather than relitigating it over Slack three days later. The goal isn't a polished document. It's a single sentence or two that the room can read and say "yes, that's what we decided." If you can't write it, you haven't converged yet.
------
There's a deeper reason this matters.
When a team doesn't distinguish between modes, two bad things happen over time. The people who are naturally divergent start to feel like the deciders run everything. The people who are naturally convergent start to feel like exploration is performative - that the real decision was made before the meeting started. Both perceptions corrode trust. Both are avoidable.
The goal isn't to rush through exploration or drag out decisions. It's to make each phase feel real. When people believe the divergent phase actually influenced the outcome, they commit more fully to the convergent one. When they trust the convergence is real, they explore more freely before it arrives.
That's the rhythm. Open, then close. Expand, then decide. Not once in a meeting - sometimes two or three times, as you work through different agenda items or surface new information that reopens a question.
The best meeting facilitators I've seen don't just manage time. They manage energy. They read the room, feel when it wants to open up and when it wants to close down, and they name it. Not with elaborate ceremony - with a simple sentence.
"Let's explore this for a while."
"Okay. Let's converge."
That's it. That's the whole practice.
Try it in your next meeting. Name the mode. Signal the shift. Watch what happens to the energy in the room.
The conversations won't feel shorter. But they'll feel like they went somewhere.
---
# The Rise of the Producing Manager
> What cognitive science says about managing AI coding agents. Developers are becoming producing managers.
Published: 2026-02-08 - Author: jake - URL: https://withstoa.com/blog/the-rise-of-the-producing-manager
### What Cognitive Science says about Managing AI Coding Agents

------
### Executive Summary
Modern developers managing AI coding agents are engaged in a fundamentally new type of cognitive work-one that combines elements of people management with technical deep work in ways that have no historical precedent. This analysis synthesizes research from cognitive psychology (dual-task performance, bottleneck theory), management science (span of control, nature of managerial work), and emerging empirical studies on AI-assisted development to understand the implications for productivity, team structure, and tool design.
The central finding: managing AI agents creates a workflow that oscillates between two cognitively distinct modes-a shallow "dispatch" mode amenable to parallelization and a deep "review" mode that is strictly serial and bottleneck-bound. Success depends on recognizing this duality and building systems that externalize intent across parallel workstreams.
------
### Part 1: The Nature of Managerial Work
### Mintzbergs Foundational Insight
Henry Mintzberg's *The Nature of Managerial Work* (1973) fundamentally challenged assumptions about what managers actually do. Through direct observation, he found that managerial work is characterized by:
- **Brevity**: The median time spent on any single issue was shockingly short
- **Variety**: Managers handle many different types of issues in rapid succession
- **Fragmentation**: Work is constantly interrupted; sustained focus is rare
- **Preference for verbal communication**: Managers favor live interaction over written documents
- **Reactive orientation**: Responding to immediate demands rather than strategic contemplation
Tengblad's 2006 replication study, conducted 30 years later, found the basic pattern held-managers still worked at an unrelenting pace through brief, varied activities. The main differences were more emphasis on group interactions with subordinates and somewhat less extreme fragmentation.
### Why This Matters for Cognitive Load
Mintzberg's description maps directly onto what cognitive scientists call "supervisory cognition"-a mode of processing that draws on verbal communication, social judgment, and rapid task-set reconfiguration. Critically, for most managerial interactions, the depth of novel problem-solving is relatively low. Asking "what's blocking you?" and responding "try X, loop in Y if that doesn't work" engages working memory briefly, makes a pattern-match to prior experience, and moves on.
In terms of the Problem State Bottleneck (Borst et al., 2010), most managerial interactions don't deeply engage the problem-state slot. This is why managers can handle many brief interactions without catastrophic performance degradation-each interaction is relatively self-contained and draws on practiced schemas rather than requiring novel problem construction.
------
### Part 2: Span of Control and Employee Experience Level
### The Core Finding
The span of control literature converges on a critical insight: the key variable isn't the raw number of direct reports-it's the **cognitive demand per report**. The factors that determine appropriate span of control include:
- **Task complexity**: Routine, standardized work allows wider spans; complex, judgment-intensive work requires narrower spans
- **Employee experience level**: Senior staff need less oversight; junior staff need more
- **Manager role**: "Producing managers" who do their own technical work can supervise fewer people than pure managers
### Junior vs. Senior Staff: Fundamentally Different Cognitive Loads
**Managing junior staff** typically requires a narrow span of control (4-6 direct reports) because juniors demand:
- Frequent directive interactions (not just answering questions, but framing problems)
- Detailed review of output (more errors, missed edge cases, need for architectural guidance)
- Heavy context loading for each interaction (cannot assume they've considered relevant factors)
In cognitive terms: reviewing a junior's work engages the problem-state bottleneck heavily. The manager must load full context, mentally simulate execution, and check for issues at multiple levels.
**Managing senior staff** allows a much wider span (10+ reports) because seniors require:
- Occasional strategic check-ins (they self-direct between interactions)
- Light review of output (trust in patterns; checking for alignment, not correctness)
- Less context loading per interaction (shared mental models, shared vocabulary)
In cognitive terms: reviewing a senior's work is more like monitoring-scanning for misalignment with broader intent, which can be done with less deep engagement of the central bottleneck.
------
### Part 3: AI Coding Agents as an Unprecedented Hybrid
### Neither Junior Nor Senior Developer
Current AI coding agents present a cognitive load profile unlike any human report. They combine characteristics of both junior and senior workers in ways that create new challenges.
**Like ultra-productive juniors:**
- Need clear, specific instructions to perform well
- Produce work that requires real review (cannot be trusted implicitly)
- Don't understand broader architectural context the way a senior colleague would
- May introduce subtle bugs or misalignments that require expert detection
**Unlike any human report:**
- No 1:1s, motivation, career development, or emotional support needed
- Don't get blocked by organizational politics
- Work continuously without breaks
- Dispatch cost is minimal (typing a prompt vs. conducting a standup)
- Can be parallelized without coordination overhead between agents
### The Two-Phase Cognitive Profile
Managing AI agents breaks into two distinct phases with very different cognitive properties:
**Phase 1: Task Specification and Dispatch**
This is relatively **shallow work**. The developer translates intent into instructions, drawing on existing mental models of the codebase and problem domain. For experienced developers, this maps onto what Sarkar (2025) calls "planning-style instructions"-structured, goal-oriented prompts that leverage existing schemas.
Dispatch can be interleaved with other work because each dispatch is a brief verbal-output task that doesn't hold the problem-state slot for extended periods. Multiple agents can be dispatched in sequence without catastrophic interference. This phase resembles Mintzberg's managerial work: brief, varied, action-oriented.
**Phase 2: Output Review and Integration**
This is unambiguously **deep work**. Code review research consistently shows it's among the most cognitively demanding activities in software engineering. Baum (2019) and Bacchelli & Bird (2013) document that review requires loading someone else's mental model into working memory-their architectural choices, naming conventions, edge cases considered, and assumptions made.
One study found developers spend 58% of maintenance time simply understanding existing code before making changes. Review demands this same cognitive effort compressed into a shorter window.
This phase engages the central bottleneck fully. You cannot meaningfully review two pull requests simultaneously. The problem-state slot is occupied, and attempting to interleave review tasks will incur the full dual-task costs documented in the cognitive literature (20-40% performance degradation, increased errors, attention residue effects).
------
### Part 4: Empirical Evidence from AI-Assisted Development
### The Faros AI Study (2025)
Analysis of telemetry from 10,000+ developers across 1,255 teams found:
- Teams with high AI adoption completed **21% more tasks** and merged **98% more pull requests**
- However, **PR review time increased 91%**-the bottleneck shifted from production to review
- AI adoption was associated with a **9% increase in bugs per developer** and **154% increase in average PR size**
- Developers were interacting with **9% more tasks** and **47% more pull requests per day**
The study explicitly noted: "Historically, context switching has been viewed as a negative indicator, correlated with cognitive overload and reduced focus. AI is shifting that benchmark... developers are not just writing code-they are initiating, unblocking, and validating AI-generated contributions across multiple workstreams."
### Sarkars Higher-Order Thinking Study (2025)
Suproteem Sarkar's SSRN paper analyzing 323,589 code merges across 32 companies found:
- Software output increased **39% after agents became the default** code generation mode
- **More experienced workers accept agent-generated code 6% more often** than junior colleagues
- Experienced workers give **clearer, planning-style instructions**, improving alignment with intent
- This positive experience gradient for agents **contrasts with autocomplete**, where juniors benefit more
The study concludes: "Agents may shift the production process from the syntactic activity of typing code to the semantic activity of instructing and evaluating agents... abstraction, clarity, and evaluation may be important skills for workers."
### The 70% Problem (Osmani)
Addy Osmani's widely-cited observation captures the senior/junior divide:
- AI coding assistants can get you **70% of the way** to a solution
- For **seniors**, the last 30% is where their expertise shines-they can efficiently evaluate and complete the work
- For **juniors**, the last 30% is often **slower than writing it themselves** because they can't reliably evaluate what they're looking at
This aligns with the cognitive science of expertise: seniors have built deep schemas through years of practice that enable faster pattern-matching during review. The bottleneck is still present, but they process through it more quickly (stage shortening). Juniors lack these schemas and cannot distinguish correct-looking code from subtly wrong code.
------
### Part 5: The Producing Manager Problem
### The Hardest Role in Management
The span of control literature identifies the "producing manager"-someone who splits time between managing others and doing their own technical work-as occupying the most cognitively demanding role. When managers must also do individual contributor work:
- Span of control should be **narrower** than pure managers
- They face constant switching between **incompatible cognitive modes**
- The fragmented, reactive supervisory mode conflicts with the deep, sustained problem-solving mode
### Developers as Producing Managers of Agents
A developer managing coding agents is essentially a producing manager. They're attempting to:
1. **Do their own deep thinking**: Architecture decisions, system design, understanding user intent
2. **Simultaneously supervise autonomous workers**: Dispatching tasks, checking status, reviewing output, integrating results
The dual-tasking research predicts exactly what the empirical data shows: throughput increases, but quality pressure rises, and the bottleneck shifts from production to review and integration.
Simon Willison captured this dynamic in his Pragmatic Engineer article:
> "I was pretty skeptical about this at first. AI-generated code needs to be reviewed, which means the natural bottleneck on all of this is how fast I can review the results... Despite my misgivings, over the past few weeks I've noticed myself quietly starting to embrace the parallel coding agent lifestyle. I can only focus on reviewing and landing one significant change at a time, but I'm finding an increasing number of tasks that can still be fired off in parallel without adding too much cognitive overhead to my primary work."
This maps perfectly onto the research: dispatch is shallow work, review is deep work, and you can layer shallow tasks around a deep task if they don't compete for the same bottleneck resources.
------
### Part 6: Implications for Practice and Tool Design
### What Works: Leveraging the Two-Phase Structure
**For individual developers:**
- Recognize that dispatch and review are cognitively distinct-don't try to interleave reviews
- Batch agent dispatches during natural breaks in deep work
- Use the deep work period for the most cognitively demanding review task; dispatch to agents while reviewing output from a previous dispatch
- Senior developers should embrace agent management; juniors should be cautious about over-reliance
**For engineering managers:**
- Expect review bottlenecks to intensify as agent adoption increases
- Consider dedicated "review specialist" roles or time allocations
- Recognize that agents shift the constraint from coding speed to evaluation speed
- Junior developers may need more support, not less, in an agent-heavy environment
**For tool designers:**
- The biggest cost isn't dispatching or reviewing individual outputs-it's **maintaining coherent intent across parallel workstreams**
- Developers running 4-8 agents simultaneously need to track not just what each is doing, but how pieces fit together and what the original user need was
- Systems that **externalize intent**-preserving the "why" behind each dispatch, tracking relationships between workstreams, providing context for efficient review-fill a critical gap
- Traditional project management tools aren't built for this; the "intent layer" is missing
### What Doesnt Work: Ignoring the Bottleneck
Common failure modes include:
- **Assuming agents eliminate cognitive load**: They shift it from production to review, often intensifying it
- **Treating all agent interaction as equivalent**: Dispatch is cheap; review is expensive
- **Expecting juniors to benefit equally**: The experience gradient runs opposite to autocomplete tools
- **Ignoring review time in productivity calculations**: The 91% increase in review time is real cost that doesn't appear in "tasks completed" metrics
------
### Part 7: Future Research Questions
1. **Training effects for agent management**: Can developers be trained to review agent output more efficiently, similar to stage-shortening effects in dual-task training? Or does the novelty of each review task prevent automatization?
2. **Optimal agent parallelization**: What is the empirically optimal number of concurrent agents given human review bottlenecks? How does this vary by developer experience?
3. **Intent preservation systems**: What tool designs most effectively support intent maintenance across parallel agent workstreams? How should context be captured and presented to minimize review cognitive load?
4. **Junior developer development**: If AI handles tasks that traditionally trained juniors, how do they develop the schemas needed for effective review? What new training approaches are needed?
5. **Age effects**: Given that older adults show reduced capacity for bottleneck bypass in dual-task training, are there age-related differences in adapting to agent management workflows?
------
### Key References
### Cognitive Science: Dual-Task Performance and Bottlenecks
Borst, J. P., Taatgen, N. A., & Van Rijn, H. (2010). The problem state: A cognitive bottleneck in multitasking. *Journal of Experimental Psychology: Learning, Memory, and Cognition*, 36(2), 363-382.
Pashler, H. (1994). Dual-task interference in simple tasks: Data and theory. *Psychological Bulletin*, 116(2), 220-244.
Leroy, S. (2009). Why is it so hard to do my work? The challenge of attention residue when switching between work tasks. *Organizational Behavior and Human Decision Processes*, 109(2), 168-181.
Newport, C. (2016). *Deep Work: Rules for Focused Success in a Distracted World*. Grand Central Publishing.
### Management Science: Span of Control and Managerial Work
Mintzberg, H. (1973). *The Nature of Managerial Work*. Harper & Row.
Mintzberg, H. (2009). *Managing*. Berrett-Koehler Publishers.
Tengblad, S. (2006). Is there a "new managerial work"? A comparison with Henry Mintzberg's classic study 30 years later. *Journal of Management Studies*, 43(7), 1437-1461.
Bandiera, O., Guiso, L., Prat, A., & Sadun, R. (2012). Span of control and span of attention. *Harvard Business School Working Paper*, 12-053.
### Code Review and Developer Cognition
Bacchelli, A., & Bird, C. (2013). Expectations, outcomes, and challenges of modern code review. *Proceedings of the International Conference on Software Engineering (ICSE)*.
Baum, T. (2019). The cognitive aspects of code review. *Empirical Software Engineering*.
Mayer, R. E., & Moreno, R. (2003). Nine ways to reduce cognitive load in multimedia learning. *Educational Psychologist*, 38(1), 43-52.
### AI-Assisted Development: Empirical Studies
Sarkar, S. K. (2025). AI agents, productivity, and higher-order thinking: Early evidence from software development. *SSRN Working Paper*.
Faros AI. (2025). The AI productivity paradox research report. https://www.faros.ai/blog/ai-software-engineering
Willison, S. (2025). New trend: Programming by kicking off parallel AI agents. *The Pragmatic Engineer*.
Osmani, A. (2025). The 70% problem with AI coding assistants. *Pragmatic Engineer*.
### AI and Workforce Implications
IEEE Spectrum. (2025). AI shifts expectations for entry level jobs. December 2025.
arxiv. (2025). Coding with AI: From a reflection on industrial practices to future computer science and software engineering education. arXiv:2512.23982.
Pajo et al. (2025). Towards decoding developer cognition in the age of AI assistants. arXiv:2501.02684.
------
*Analysis prepared February 2026. Synthesizes cognitive science research on dual-task performance with management literature and emerging empirical evidence on AI-assisted software development.*
---
# Planning Work for Our Single-Threaded Brains
> When dual-tasking works, when it doesn't, and why - what cognitive science tells us about managing AI coding agents.
Published: 2026-02-05 - Author: jake - URL: https://withstoa.com/blog/planning-work-for-our-single-threaded-brains
## When Dual-Tasking Works, When It Doesn't, and Why
### The Core Architecture: Your Brain Has a Bottleneck
The foundational finding in multitasking research, replicated hundreds of times since Pashler's landmark 1994 review, is that the brain's response selection mechanism operates serially. When two tasks both need the central processor to make a decision, one waits for the other. This is the **Psychological Refractory Period (PRP) effect**: present two stimuli in rapid succession, and the response to the second one is reliably delayed by however long the first one is still occupying the central stage (Pashler, 1994; Sigman & Dehaene, 2006).
This isn't a minor lab curiosity. The PRP effect is described as "highly robust" across decades of research and is observed regardless of whether the two tasks use the same hands, different hands, voice responses, foot responses, or eye movements (Pashler, 1994). It persists even when the tasks seem completely unrelated.
But the bottleneck story is more nuanced than "you can't do two things at once." It depends critically on *what kind* of cognitive resources the tasks require.
### Wickens Multiple Resource Theory: The Key Framework
Christopher Wickens' 4-Dimensional Multiple Resource Model (1980, 2002, 2008) explains why some task pairs interfere catastrophically while others coexist relatively well. The model identifies four dimensions along which cognitive resources are differentiated:
1. **Processing stages**: Perceptual/cognitive vs. response
2. **Sensory modalities**: Visual vs. auditory
3. **Processing codes**: Spatial vs. verbal
4. **Visual channels**: Focal vs. ambient
The prediction is straightforward: two tasks that draw on *different* resource pools along these dimensions interfere less than two tasks that draw on the *same* pools. Listening to a podcast (auditory/verbal) while driving (visual/spatial/motor) works reasonably well because the tasks draw on largely separate resource pools. Reading a text while listening to someone speak (both verbal) is much harder because they compete for the same verbal processing resource.
Wickens' computational model yields high correlations between predicted and observed interference across dozens of task combinations (Wickens, 2008). This is the best empirical framework we have for predicting when dual-tasking will or won't cost you.

### The Problem State Bottleneck: Why Knowledge Work Is Different
Beyond the general central bottleneck and Wickens' resource pools, there's a more specific bottleneck that is especially relevant to knowledge work: the **problem state bottleneck**, identified by Borst, Taatgen, and van Rijn (2010).
The "problem state" is the intermediate mental representation you hold while working through a task - the current step of a multi-step calculation, the logical structure of an argument you're building, the architectural pattern you're implementing in code, the thread of reasoning in a document you're editing.
Borst et al. demonstrated experimentally that people can maintain only one active problem state at a time. When two tasks *both* require maintaining a problem state, interference is severe and "overadditive" - worse than the sum of each task's individual demands. When only one task requires a problem state (and the other is more automatic), interference is minimal.
This finding was confirmed across three experiments and validated with computational models in the ACT-R cognitive architecture. Subsequent work (Held, Rieger, & Borst, 2024) showed that working memory contention, not a general central coordinator, best explains the interference pattern in dual-task settings.
**This is the critical insight for anyone doing coding, writing, planning, or analytical work.** These tasks *all* require maintaining a complex problem state. Writing a spec requires holding the logical structure of the document. Coding requires holding the state of the implementation. Debugging requires holding a mental model of data flow. They all contend for the same limited problem-state resource.
### Salvucci & Taatgens Threaded Cognition: When Interleaving Can Work
The most sophisticated model of multitasking is Salvucci and Taatgen's **Threaded Cognition theory** (2008), which treats concurrent tasks as independent "threads" that are coordinated by a serial procedural resource and executed across other available resources (visual, auditory, motor, memory).
The key mechanism: when one thread is waiting for a slow resource (e.g., a motor response, a memory retrieval, an external event), other threads can use the procedural resource in the gap. Tasks interleave through the *idle slots* in each other's processing, not through parallel execution.
This means dual-tasking can approach zero cost under specific conditions:
- **One or both tasks have substantial idle/waiting periods** where the procedural resource isn't needed
- **The tasks use different peripheral resources** (e.g., one visual, one auditory; one manual, one vocal)
- **Neither task's problem state is disrupted** by the other task's processing
When these conditions hold, threading is efficient. When they don't - particularly when both tasks compete for the problem state resource - interference is substantial and unavoidable.
### Can Training Improve Dual-Task Performance?
A natural question follows from the bottleneck research: if the bottleneck limits dual-tasking, can practice reduce or eliminate that limit? The answer is nuanced - training can dramatically improve dual-task performance, but the mechanisms and boundary conditions matter enormously for anyone hoping to apply this to real work.
### Three Competing Hypotheses
Ruthruff, Van Selst, Johnston, and Remington (2006) tested three hypotheses about how practice reduces dual-task interference:
1. **Task integration**: Practice teaches you to efficiently coordinate a specific task pair as a unit
2. **Automatization**: Practice makes individual tasks automatic, allowing them to bypass the central bottleneck entirely
3. **Stage shortening**: Practice speeds up the bottleneck stages (response selection gets faster), but the bottleneck itself remains intact
Their transfer-of-training experiments found that for most participants, the third hypothesis - stage shortening with an intact bottleneck - fully explained the improvement. The bottleneck didn't disappear; tasks just moved through it faster. However, a minority of participants in certain conditions did show evidence of genuine automatization, bypassing the bottleneck altogether.
### The Neural Evidence: Faster Processing, Not Parallel Processing
Dux, Tombu, Harrison, Rogers, Tong, and Marois (2009) provided the clearest neural account. They trained participants daily for two weeks on two simple sensorimotor tasks while tracking brain activity with fMRI. Key findings:
- Training reduced dual-task costs by approximately 50% over two weeks
- The improvement was driven by faster, more efficient information processing in the posterior lateral prefrontal cortex (the neural locus of the bottleneck)
- Training did *not* create parallel processing pathways - the brain was still processing one task at a time
- As Dux stated: "Even after extensive practice, our brain does not really do two tasks at once. It is still processing one task at a time, but it does it so fast it gives us the illusion we are doing two tasks simultaneously."
The prefrontal cortex showed decreased and more efficient activation patterns with training, and pattern analysis revealed that neural representations of the two tasks became more distinct - the brain was sharpening its task representations rather than learning to run them simultaneously.
Verghese, Garner, Mattingley, and Dux (2016) followed up with a 100-person study showing that the volume of the left dorsolateral prefrontal cortex predicted individual training gains - meaning some people are structurally better positioned to benefit from dual-task training than others.
### Bottleneck Bypass: Possible but Extremely Narrow
While stage shortening is the dominant mechanism, genuine bottleneck bypass - where a practiced task runs in parallel with an unpracticed one - has been demonstrated under very specific conditions.
Schumacher, Seymour, Glass, Fencsik, Lauber, Kieras, and Meyer (2001) showed that after relatively modest practice (five sessions), some participants achieved "virtually perfect time sharing" on basic choice reaction tasks. Maquestiaux, Lague-Beauvais, Ruthruff, and Bherer (2008) found that after six sessions of single-task practice on a simple auditory-vocal task, 17 out of 20 young adults could bypass the bottleneck when that task was paired with an unpracticed visual-manual task.
But the conditions required for bypass are revealing:
- **The tasks must be simple sensorimotor mappings** with consistent stimulus-response associations (e.g., press left for low tone, press right for high tone)
- **Sensory-motor modality compatibility matters enormously**: bypass works best with compatible pairings (visual-manual + auditory-vocal) and fails with incompatible ones (visual-vocal) because incompatible pairings create conflicts within modality-specific working memory (Maquestiaux, Ruthruff, Defer, and Ibrahime, 2018)
- **The practiced task must not greedily recruit central resources**: even tasks that *can* run automatically will seize the bottleneck when it's available, re-creating interference (Maquestiaux et al., 2008)
- **It requires thousands of training trials on consistent mappings** - the kind of repetitive practice that has no analog in knowledge work
### Age Sharply Limits Bypass Capacity
Maquestiaux, Lague-Beauvais, Ruthruff, Hartley, and Bherer (2010) found a dramatic age difference: while the vast majority of young adults bypassed the bottleneck after training, at most 1 out of 12 older adults could do so - even with identical training. Maquestiaux, Didierjean, Ruthruff, Chauvel, and Hartley (2013) replicated this with *double* the training (10,080 trials across 12 sessions). Older adults' single-task reaction times dropped to levels identical to young adults, yet they still could not bypass the bottleneck. The ability to automatize novel tasks to the point of bottleneck bypass appears to decline with age, independent of overall processing speed.
### The Coordination Skills Hypothesis
Strobach and Schubert (2024) reviewed evidence for a "memory hypothesis" of dual-task improvement: practice doesn't eliminate the bottleneck or make tasks automatic, but instead improves the executive ability to rapidly load both task sets into working memory at the start of a dual-task trial. This coordination skill - efficiently instantiating and switching between task representations - explains why dual-task practice sometimes transfers to new task combinations that share similar coordination demands.
However, the authors explicitly note that this hypothesis has only been investigated with relatively easy component tasks. Whether it generalizes to complex tasks with high working memory demands remains unknown.
### Transfer Is Severely Limited
Perhaps the most practically important finding: dual-task training benefits are overwhelmingly task-specific.
Bender, Filmer, Garner, Dux, and colleagues (2017) trained participants on a combined visuomotor tracking and discrimination task for six sessions. Multitasking performance on the trained tasks improved substantially, but this improvement "did not generalize to a wide range of cognitive tasks that are theoretically linked to the current dual-task paradigm." The conclusion: training induces learning of task-specific coordination skills, not a general enhancement of multitasking ability.
Ewolds, Broeker, de Oliveira, Raab, and Kunzell (2021) found that even when two tasks were made individually predictable through practice, the benefits of predictability remained contained within each task - they didn't combine to reduce overall dual-task interference. Dual-task practice didn't change this.
Meta-analyses of cognitive training more broadly (Sala & Gobet, 2017; Kassai, Futo, Demetrovics, & Takacs, 2019) consistently find that training produces "near transfer" (improvement on similar tasks) but not "far transfer" (improvement on dissimilar cognitive abilities). As one review summarized: training a component did not have a significant effect on untrained components.
### One Notable Exception: NeuroRacer
Anguera, Boccanfuso, Rintoul, and Gazzaley (2013), published in *Nature*, demonstrated something unusual. Older adults (60-85) who trained on NeuroRacer - a custom 3D video game requiring simultaneous driving and sign detection - not only improved their multitasking performance beyond untrained 20-year-olds, but showed transfer to *untrained* cognitive abilities including sustained attention and working memory. These gains persisted for six months. Neural measures showed enhanced prefrontal theta power resembling patterns seen in younger brains.
The critical nuance: the researchers argued this transfer occurred because NeuroRacer enhanced general *cognitive control* processes (the ability to maintain an engaged, goal-directed state under interference), not multitasking ability per se. The game's adaptive difficulty algorithm continuously pushed participants beyond their comfort zone, preventing the automatic processing that typically limits training effects. This is more about training the executive control system than about making dual-tasking easier.
### What This Means for Knowledge Work
The training research carries a clear, somewhat uncomfortable implication for knowledge workers:
**What training \*can\* do**: Speed up processing of well-practiced, routine task components. If you process the same types of Slack messages, the same types of code review comments, or the same types of form-filling operations hundreds of times, the response selection for those tasks will get faster, leaving more room for interleaving with other work.
**What training \*cannot\* do**: Make novel, complex cognitive tasks run in parallel. You cannot "practice" your way into simultaneously writing a design doc and debugging a production issue. These tasks inherently require the problem state resource, involve novel combinations of information, and demand the kind of central executive engagement that resists automatization. The bottleneck isn't a skill deficit - it's a structural feature of how cognition works.
**What training \*might\* do**: Improve your general cognitive control - your ability to maintain focus, resist distraction, and manage interference. But this is best achieved through sustained, adaptive cognitive challenge, not through practicing multitasking itself.
### What Happens Beyond Two Tasks
Research on triple-tasking is limited but the results that exist are stark.
Stefani, Sauter, and Mack (2025) directly tested the transition from dual-task to triple-task performance. Key findings:
- Response times increased from single to dual to triple tasks, but the increase from dual to triple was only about 43% of the increase from single to dual, suggesting a non-linear (but still costly) scaling pattern
- Unlike in dual tasks where typically only one of the two responses is delayed, in triple tasks *all three subtasks* showed elevated response times
- Even with extensive dual-task training beforehand, triple-task costs persisted - preparation helped initially but the advantage diminished over sessions
- Task coordination, rather than simple stimulus-response mapping, became the dominant source of interference
Konishi, Berberian, de Gardelle, and Sackur (2021) found something arguably more alarming: triple-tasking didn't just degrade performance on the three tasks - it degraded participants' *awareness of how well they were performing* (metacognitive sensitivity). People became worse at the tasks *and* worse at knowing they were worse. This metacognitive impairment was independent of the performance cost itself, suggesting it reflects an additional resource demand that monitoring and self-evaluation place on the same limited cognitive machinery.
This means that the subjective feeling of "managing well" during heavy multitasking is itself unreliable evidence.
### The Conditions Where Dual-Tasking Actually Works
Synthesizing across the bottleneck research, multiple resource theory, threaded cognition, and the problem state findings, dual-tasking provides net benefit over mono-tasking specifically when:
**1. One task has genuine idle time that the other can fill.**
This is the throughput argument. If Task A involves 40% active cognition and 60% waiting (for a build, a query, a response from someone), and Task B can productively fill those wait periods without disrupting Task A's problem state when Task A becomes active again, total throughput increases. This is not multitasking in the popular sense - it's efficient scheduling of a serial processor.
Examples: monitoring CI output while drafting notes; reviewing a slow-loading dashboard while composing a message; waiting for a deploy while scanning a queue of simple approvals.
**2. The tasks draw on different resource pools (per Wickens).**
Listening to ambient music (auditory, no verbal processing demand) while coding (visual, verbal, spatial). Walking while having a phone conversation. These work because the tasks don't compete for the same perceptual, cognitive, or motor resources.
What *doesn't* work: reading Slack while writing a document (both visual, both verbal, both require a problem state). Reviewing code while participating in a meeting (both require verbal comprehension, both require a problem state).
**3. One task is highly automated and doesn't require a problem state.**
Tasks that have been practiced to the point of automaticity don't consume central bottleneck resources or the problem state resource. Driving on a familiar highway is automatic enough that you can carry on a conversation. Typing is automatic enough that you can focus on the content you're composing rather than the keystrokes.
But notice: for knowledge workers, the "tasks" that matter - writing, reading code, debugging, designing, reviewing - are virtually never automatic. They are inherently novel, requiring active problem state maintenance and central executive engagement. The things you can automate alongside them are relatively trivial.
**4. Context-switching cost is low because the problem state is simple or externally stored.**
If you can fully offload the problem state of Task A to an external representation (a document, a checklist, a clear stopping point) such that re-entry is cheap, then alternating between A and B becomes more viable. The cost of switching is dominated by problem-state reload time. If there's no complex mental model to reconstruct, the cost is low.
This is why alternating between two *procedural* tasks with clear checkpoints (e.g., process this form, then process that form) is much cheaper than alternating between two *creative* or *analytical* tasks (e.g., write this section of the spec, then debug this architectural issue).
### The Conditions Where Mono-Tasking Dominates
Single-task focus is unambiguously superior when:
- **The task requires deep problem-state maintenance**: Any work where you need to hold a complex mental model - writing a design doc, debugging a multi-component system, conducting a code review that requires understanding architectural intent, synthesizing research into a coherent argument.
- **Both potential tasks are cognitively demanding and share resource pools**: Two verbal-cognitive tasks, two tasks requiring visual attention and working memory. The research is unequivocal that performance on both degrades.
- **Quality matters more than throughput**: Dual-tasking doesn't just slow you down; it increases error rates. For tasks where errors are expensive (writing contracts, reviewing security-sensitive code, making strategic decisions), the quality cost of divided attention exceeds any throughput gain.
- **The task benefits from sustained attention and flow**: Csikszentmihalyi's flow state and Newport's deep work framework are consistent with the cognitive science here. The central bottleneck and problem state resource work most efficiently when focused on a single demanding task. Interruptions, even brief ones, force problem-state reloading that can take minutes for complex cognitive work (Mark, 2005, found 23+ minutes for full re-engagement after significant interruptions; Carnegie Mellon research found even brief interruptions increased task completion time by up to 23%).
### Why Multi-Tasking (>2) Is Almost Always Wrong for Knowledge Work
The research case against juggling three or more cognitively demanding tasks simultaneously is strong:
- **Triple-task costs persist even after extensive dual-task training** (Stefani et al., 2025). The skills that help you manage two tasks don't cleanly transfer to three.
- **Metacognitive monitoring degrades** (Konishi et al., 2021). You lose the ability to accurately assess your own performance, which means you can't effectively self-correct or prioritize.
- **Task coordination itself becomes a resource-consuming activity**. With two tasks, coordination is relatively simple (alternate). With three or more, the scheduling problem becomes its own cognitive burden, consuming resources that could be devoted to the actual work.
- **Error rates compound non-linearly**. Each additional task doesn't just add its own error probability - it degrades the executive control that would catch errors in the other tasks.
For knowledge work - coding, design, writing, analysis - where tasks almost universally require problem state maintenance, verbal/spatial processing, and central executive engagement, multi-tasking beyond two is a net negative on both throughput and quality.
### Practical Framework

### Key References
- Pashler, H. (1994). Dual-task interference in simple tasks: Data and theory. *Psychological Bulletin*, 116(2), 220-244.
- Wickens, C. D. (2002). Multiple resources and performance prediction. *Theoretical Issues in Ergonomics Science*, 3(2), 159-177.
- Wickens, C. D. (2008). Multiple resources and mental workload. *Human Factors*, 50(3), 449-455.
- Salvucci, D. D., & Taatgen, N. A. (2008). Threaded cognition: An integrated theory of concurrent multitasking. *Psychological Review*, 115(1), 101-130.
- Borst, J. P., Taatgen, N. A., & van Rijn, H. (2010). The problem state: A cognitive bottleneck in multitasking. *Journal of Experimental Psychology: Learning, Memory, and Cognition*, 36(2), 363-382.
- Sigman, M., & Dehaene, S. (2006). Dynamics of the central bottleneck: Dual-task and task uncertainty. *PLoS Biology*, 4(7), e220.
- Held, M., Rieger, J. W., & Borst, J. P. (2024). Multitasking while driving: Central bottleneck or problem state interference? *Human Factors*, 66(5), 1564-1582.
- Stefani, M., Sauter, M., & Mack, W. (2025). Multi-tasking costs in triple-task performance despite dual-task preparation. *Memory & Cognition*, 53(6), 1637-1655.
- Konishi, M., Berberian, B., de Gardelle, V., & Sackur, J. (2021). Multitasking costs on metacognition in a triple-task paradigm. *Psychonomic Bulletin & Review*, 28(6), 2075-2084.
- Schumacher, E. H., et al. (2001). Virtually perfect time sharing in dual-task performance: Uncorking the central cognitive bottleneck. *Psychological Science*, 12(2), 101-108.
- Ruthruff, E., Van Selst, M., Johnston, J. C., & Remington, R. (2006). How does practice reduce dual-task interference: Integration, automatization, or just stage-shortening? *Psychological Research*, 70(2), 125-142.
- Dux, P. E., Tombu, M. N., Harrison, S., Rogers, B. P., Tong, F., & Marois, R. (2009). Training improves multitasking performance by increasing the speed of information processing in human prefrontal cortex. *Neuron*, 63(1), 127-138.
- Verghese, A., Garner, K. G., Mattingley, J. B., & Dux, P. E. (2016). Prefrontal cortex structure predicts training-induced improvements in multitasking performance. *Journal of Neuroscience*, 36(9), 2638-2645.
- Maquestiaux, F., Lague-Beauvais, M., Ruthruff, E., & Bherer, L. (2008). Bypassing the central bottleneck after single-task practice in the psychological refractory period paradigm. *Memory & Cognition*, 36(7), 1262-1282.
- Maquestiaux, F., Lague-Beauvais, M., Ruthruff, E., Hartley, A., & Bherer, L. (2010). Learning to bypass the central bottleneck: Declining automaticity with advancing age. *Psychology and Aging*, 25(1), 177-192.
- Maquestiaux, F., Didierjean, A., Ruthruff, E., Chauvel, G., & Hartley, A. (2013). Lost ability to automatize task performance in old age. *Psychonomic Bulletin & Review*, 20(6), 1206-1212.
- Maquestiaux, F., Ruthruff, E., Defer, A., & Ibrahime, S. (2018). Dual-task automatization: The key role of sensory-motor modality compatibility. *Attention, Perception, & Psychophysics*, 80, 752-772.
- Strobach, T., & Schubert, T. (2024). A mechanism underlying improved dual-task performance after practice: Reviewing evidence for the memory hypothesis. *Psychonomic Bulletin & Review*, 31, 1035-1053.
- Bender, A. D., Filmer, H. L., Garner, K., Dux, P. E., et al. (2017). Dynamic, continuous multitasking training leads to task-specific improvements but does not transfer across action selection tasks. *npj Science of Learning*, 2, 14.
- Anguera, J. A., Boccanfuso, J., Rintoul, J. L., et al. (2013). Video game training enhances cognitive control in older adults. *Nature*, 501(7465), 97-101.
- Strobach, T., & Schubert, T. (2017). No evidence for task automatization after dual-task training in younger and older adults. *Psychology and Aging*, 32(1), 28-41.
- Mark, G., Gonzalez, V. M., & Harris, J. (2005). No task left behind? *Proceedings of CHI '05*.
---
# Conversation → Decisions → Strategy
> Watch a live conversation become a strategy document. Decisions with context, not just notes.
Published: 2026-01-27 - Author: jake - URL: https://withstoa.com/blog/conversation-decisions-strategy
No Google Doc.
No Notion page.
No one taking notes.
Just a live conversation in SpecStory Arena (now [Stoa](https://withstoa.com)).
And while we were talking, Arena was doing something without us asking
It was automatically extracting the **decisions we made**, grounded in the exact quotes where we made them.
The real words. The real tradeoffs. The real intent.
So by the time we finished the conversation, we didn't just have a recording.
We had a structured set of **decisions**, tied directly to *why* we made them.
Then we told an agent: **"turn this into our strategy."**

And it did.
Not from notes or bullet points.
From the actual conversation where we debated, refined, disagreed, and aligned.
Because Arena didn't capture "notes."
It captured **context**.
That's why the strategy doc it produced felt like *ours*.
It reflected:
- what we cared about
- what we ruled out
- what we were unsure about
- and why
The thinking didn't disappear after the meeting.
It became usable.
In the video below, you can literally watch us go from live discussion to a refined strategy document that we immediately started working from with the team.
This is Arena (now [Stoa](https://withstoa.com)), our alpha for what collaborative planning in the AI era should feel like.
---
# 7 Lessons Learned From 25 Years of New Product Introduction
> Find your vanguard. Find an excruciating pain. Define a platform mission. Deliver a specific solution.
Published: 2025-11-22 - Author: jake - URL: https://withstoa.com/blog/7-lessons-from-25-years-of-new-product-introduction
**Find your vanguard. Better yet, \*be\* your vanguard.**

If your vanguard is a team, get specific. Identify *people*, not groups. Teams don't make decisions - people do.
**Find an excruciating pain** for at least one of those people. Not a "nice to have." Not a "want." A *pain*.
**Define a platform mission** that:
- Aligns with who your vanguard wants to become, and
- Directly intersects with that pain.
**Deliver a specific solution** for that pain *while staying true to the platform mission.*
**Get 10 vanguard teams using your solution.**
Care deeply about the person (or people) who feel the excruciating pain. Understand the rest of the team well enough to **assuage, defuse, or win them over.**
**Sweat every detail.** Obsess over the nuances of the pain and the solution until **at least 4 out of 10** of those teams say:
> "We couldn't live without you."
(And importantly: no adjacent team members should be saying *"I can't live with this."*)
Once you reach this point, ask yourself:
**Is your solution just a point solution, or is it extensible?**
- If it's just a point solution, you drifted away from the platform mission.
- If it's extensible, **now you scale.** And *now* you grow.
---
# Mitchell Hashimoto on the AI-Assisted Future of Open Source
> What the Ghostty creator learned reviewing hundreds of AI-generated pull requests
Published: 2025-10-20 - Author: jake - URL: https://withstoa.com/blog/mitchell-hashimoto-on-the-ai-assisted
Mitchell Hashimoto wakes up early. Before his toddler stirs, before breakfast, he opens his laptop and checks what landed in the Ghostty repository overnight. Ghostty, a GPU-accelerated terminal emulator, has become one of the most active open source projects in its category. Most mornings, Hashimoto sends new GitHub issues to an AI agent for a first pass. The hit rate hovers around 10 to 20 percent. It is not perfect, but it helps him triage and spot patterns faster than he could alone.

It is a small ritual with larger meaning. Hashimoto is not fighting the rise of AI in open source. He is studying it, learning where it helps, and drawing careful lines around where it does not.
---
## A new rule for a new era
Earlier this year, Mitchell Hashimoto introduced a new requirement to the [Ghostty's contributor guide](https://github.com/ghostty-org/ghostty/pull/8289): every pull request must disclose when AI tools were used. The idea was practical. Too many submissions looked fine on the surface but fell apart under review. He could tell that some contributors had pasted AI code they did not fully understand.
> "Before AI, I might get one bad PR every six months," he said. "Now it feels like every other week."

The change was not about policing people. It was about context for reviewers who put their time and attention into a review. In the same pull request, he wrote, "The disclosure is to help maintainers assess how much attention to give a PR. While we aren't obligated to in any way, I try to assist inexperienced contributors and coach them to the finish line. But if it's just an AI on the other side, I don't need to put in that effort."
Behind the policy was a deeper frustration. He had seen an explosion of what he calls "AI slop" - code that looked plausible but lacked understanding. "There's good-intention slop and bad-intention slop," he said in his talk with us at SpecStory. "The difference is whether the person tried to understand what they were doing."
That distinction matters. Hashimoto recalled a contributor who left the community after receiving harsh feedback on a low-quality PR. "Stuff like that makes me feel bad because I think it wouldn't have happened ten years ago," he said. "Back then, I would have been more patient. But now that bad contributions happen so often, I lose my patience immediately."
Within weeks of the rule taking effect, about fifty percent of all Ghostty pull requests included an AI disclosure. The numbers confirmed what he suspected: AI had become a routine part of contribution. The question was no longer *if* it should be used, but *how*.
> **For Maintainers:** Disclosure is essential, but it is only the first step. The challenge is helping good-faith contributors without drowning in noise.
>
> **For Contributors:** Show your work. Help reviewers see your thinking, not just your diff.
Since that initial change, Hashimoto has continued to shape Ghostty's culture around transparency. In his blog post [Vibing a Non-Trivial Ghostty Feature](https://mitchellh.com/writing/non-trivial-vibing), he described how he uses tools like Amp to design and implement complex features, documenting the messy and experimental steps that most developers hide. The post captured the same philosophy that drives Ghostty's contributor policy: AI can be part of the process, but contributors should show how it influenced their work so that reviewers can understand the intent behind each change.
---
## Seeing the intent behind the code
What frustrates Hashimoto is not that people use AI, but the absence of visible reasoning.
> "As a reviewer, I do not care what the AI said. The AI output is noise. I want to see the contributor's thinking."
When he opens a PR, he looks for signs of understanding: the prompts, the decisions, the corrections along the way. Bad PRs, he said, tend to show a "slop zone" where the contributor is clearly fishing for code without comprehension. "I want to see that you understand what you're doing, or at least trying to."
Well-structured AI sessions, by contrast, build trust. They reveal thought process and intention. For Hashimoto, that trail of reasoning is what separates a responsible contributor from a careless one. The checkbox saying "AI used" is not enough. What matters is the visible proof that a human actually thought through the work.
> **For Contributors:** Don't just say you used AI. Show how you used it. Your prompts tell the story of your thinking.
---
## Learning to drive with AI
Hashimoto is not only a maintainer, reviewing AI-assisted work. He uses AI daily and experiments with different workflows. For planning and exploration, he often runs multiple coding agents side by side, comparing their results. "Usually no one agent wins," he said. "One captures the main idea. Another remembers an edge case. I pull the best parts together by hand."
This ensemble approach costs more time and compute, but it helps him triangulate solutions. It also highlights a broader truth: AI is not a single oracle, but a chorus of imperfect advisors.
When it comes to implementation, he enforces one rule on himself. "If the AI writes something I do not understand, I stop and study it," he said. "I try to recreate it myself. If I cannot reach the same diff, I need to learn more."
Despite being an experienced systems programmer, he calls himself "a very inexperienced JavaScript front-end person." When the AI generates front-end code, he reads through it line by line to understand the imports, data flow, and dependencies before committing anything.
He treats AI not as an answer machine but as a learning accelerator. It lets him build something real first, then study it deeply enough to make it his own.
> **For Contributors:** Never commit code you cannot explain. AI should help you learn faster, not think less.
---
## Better scaffolding for contributors
Rather than hope contributors discover effective workflows by chance, Hashimoto has started shipping small helper tools directly in the Ghostty repository.
One of his favourites is a [custom Amp slash command](https://ampcode.com/news/custom-slash-commands) he built that fetches GitHub issues and reformats them into clean Markdown for AI planning sessions. "I use it five times a day," he said. Commands like this give contributors a clean starting point for structured reasoning before they even begin generating code.
Hashimoto draws a line between tooling that guides good habits and tools that just generate noise. "The engagement-bait trend of massive prompt libraries," he said, "that's just noise."
Scaffolding, for him, is not about automation but about making good behavior easy and visible. The right structure helps contributors think more clearly and makes their reasoning visible to others. When the repository itself encodes these habits, people do not just read the guidelines, they practice them with every contribution.
> For Maintainers: Don't just write contribution rules or guidelines. Build and ship the actual tools that embody your project's best practices for AI-assisted contribution.
---
## The next generation of developer tooling
### Prompt blame: tracing code back to intent
Hashimoto's vision for better tooling starts with accountability. He envisions a future system where version control can tell you not just *who* wrote a line of code, but *why*.
> "It would be useful to point at a line of code and say what part generated this," he said.
He calls one idea "prompt blame," a nod to git blame. Instead of only showing who wrote a line, it would show which prompt created it and where the human stepped in. That kind of trace and visibility answers a familiar review question. Why did this change happen in the first place?
> "Current AI tools show all the machine diffs but hide the human ones," he said. "You lose the part where the human is actually thinking."
### Annotating AI sessions: the human commentary layer
For Hashimoto, visibility is not just about machine behavior but also human intent. He advocates for annotation, giving humans a way to mark parts of an AI session with notes such as: "This part was experimental. This part was me learning. This part actually informed the final PR." It's the difference between showing just your final answer and showing your thought process.. These annotations exist for the next human who reads the code.
### Interleaving human and AI edits
The other gap he points to is temporal. Most coding tools show the AI's diffs but not the developer's.
> "It shows all the AI diffs but doesn't show the human diffs," he said. "You lose the part where the human is actually thinking."
Hashimoto imagines a unified history that interleaves both, where every refactor, correction, or course change by a person sits alongside the AI's suggestions. Code review would then show a full collaboration, not a one-sided transcript.
---
## The opening beyond Git
Experience with AI-assisted reviews has pushed Hashimoto toward a larger conclusion. Traditional version control was not designed for rapid human and machine collaboration.
> "If someone wanted to invent a new version control system, this is the biggest opening since Git," he said.
Git tracks authors and commits. It does not track the reasoning or conversations that produced them.
Git was built for snapshots, not for continuous, conversational iteration between humans and machines. Hashimoto's advice to the team behind [Jujutsu](https://github.com/martinvonz/jj), where he serves as an advisor, reflects this thinking: make it agent-friendly. In his words, a modern system should "over-aggressively create commits", capturing every micro-diff so humans and agents can safely experiment, revert, and compare ideas.
The real opportunity, he says, lies in metadata. "How do you attach the prompts? How do you attach co-authorship?" Git was not built to track the dialogue that produces a change. A new system could.
---
### Intent: version control for the AI era
That question: how to attach prompts, reasoning, and co-authorship to real code history is exactly what SpecStory's upcoming project **Intent** is designed to solve.
**Intent** is a new version control system built from the ground up for AI-assisted development. It automatically captures every AI conversation, links it to code changes, and creates a searchable decision timeline. Built on **CRDTs (Conflict-free Replicated Data Types)**, it synchronizes work continuously without merge conflicts.
Where Git relies on human discipline to document changes, Intent captures context automatically. Imagine asking months later, *"Why did we choose JWT instead of sessions?"* and seeing the full conversation that led there: the alternatives discussed, the reasoning behind the choice, and the exact lines of code that came from it.
**Key capabilities include:**
- **Automatic versioning:** Every save becomes a versioned checkpoint.
- **AI conversation tracking:** Links code diffs to their originating chat sessions.
- **Conversational search:** Queries like "When did we add authentication?" return the full decision trail.
- **CRDT-based sync:** Real-time collaboration with no merge conflicts.
- **Human-in-the-loop history:** Interleaves AI-generated and human edits into one continuous timeline.
In many ways, *Intent* turns Hashimoto's wishlist: prompt blame, session annotation, human-AI interleaving into infrastructure. It makes reasoning first-class, so context never gets lost.
> **For Maintainers:** Version control should capture not just the code, but the conversations that shaped it.
>
> **For Contributors:** The best contribution is one that shows how you thought not just what you typed.
---
## The future of transparent collaboration
After hundreds of AI-assisted reviews, Hashimoto's view is clear. Open source does not have an AI problem. It has a transparency problem. The goal is not to forbid AI. The goal is to make the human judgment in the loop visible.
He imagines a norm where sharing AI sessions is as common as sharing diffs, where maintainers can check not only what changed but why, and where contributors can demonstrate the care behind their work. "If people shared their sessions, it would help a lot," he said. "I would have loved to see how my open source heroes actually built a feature."
Culture and tooling will meet in the middle. Disclosure sets expectations. Reasoning trails and richer metadata make those expectations practical. That is the direction SpecStory is betting on. When the thinking travels with the code, teams move faster, communities stay healthier, and code review becomes a conversation grounded in intent rather than guesswork.
---
# SpecStory in Action: How a Deleted Repo Was Rebuilt from History
> A coding agent deleted an entire repository. SpecStory's preserved session histories made full recovery possible.
Published: 2025-10-06 - Author: antaripa - URL: https://withstoa.com/blog/how-a-deleted-repo-was-rebuilt-from-history
AI-assisted coding is powerful, but anyone who's spent time with it knows that it's not always predictable. What looks like a productive session can sometimes take a sharp turn. For one developer, that turn meant watching a repository vanish.
This is the story of how SpecStory turned that moment from disaster into recovery.
## Building AI at Scale
One of our users, an ML Engineer at a leading LLM company, spends his days building and training large language models. His workflow involves running agent-driven coding experiments at scale - dozens of sandboxes, multiple sub-agents, and millions of tokens being processed. It's a high-output environment where mistakes are costly.
In the middle of one of these experiments, the coding agent deleted the entire repository.

## The Accident
> "In some shocking way, we had one agent running and it deleted the repo. At the same time, we had issues reading from GitHub, so we couldn't just pull it back."
It wasn't just a missing file or a bad commit. The repository was gone - and the work they had been building just vanished. GitHub recovery wasn't an option either. The codebase looked permanently lost.
For a team building foundational AI models, this was the kind of setback that could derail weeks of work.
## Recovery Through SpecStory
Instead of starting from scratch, the engineer turned to SpecStory.
> "We put in the SpecStory histories that had recorded everything and asked our AI, *Can you recreate all the code?* It actually rebuilt the whole repo. That basically saved us."
Because SpecStory had been running in the background, every AI-assisted coding session - every prompt, correction, tool call, and code output - was preserved as a Markdown history with timestamps.
Those histories weren't just records of what the agent produced. They captured the entire development flow:
- The commands and tool calls that shaped the code
- The corrections when the AI got something wrong
- The design decisions debated and accepted along the way
Those histories didn't just log the code - they logged the reasoning *behind* the code. Together, they provided enough context for the AI to regenerate the entire lost repo. What began as a simple history log became an accidental backup system.
## Continuity in Fragile Environments
For this engineer, the benefits didn't end there. His day-to-day workflow involves SSHing into GPU clusters where development pods frequently reset. Every reset wipes out Cursor's chat history, forcing developers to restart without context.
SpecStory changed that. By maintaining histories across all folders, it let him reconnect, resync, and immediately pick up where he left off. Even when the infrastructure churned underneath, SpecStory gave him continuity.
## From Logs to LLM Training Data
The most unexpected use case came when SpecStory became part of the LLM training pipeline:
- Each sandbox run generated long traces of AI reasoning and code
- After each run, SpecStory synced and captured those traces
- The logs were converted into user-assistant format and fed directly into post-training datasets for their models
What began as a convenience for developers grew into infrastructure for LLM training - providing high-quality synthetic conversations rooted in real coding tasks.
## Lessons From the Workflow
This engineer's story shows the multiple dimensions of value that SpecStory brings:
- **Disaster Recovery:** When an AI agent wiped a repo, SpecStory's preserved histories made recovery possible.
- **Persistent Context:** In unstable dev environments, SpecStory acts as a durable memory layer when other tools lose state.
- **Data Pipeline:** At massive scale, SpecStory logs double as structured training data for fine-tuning LLMs.
## The Bigger Picture
This story highlights a truth about AI-assisted coding: speed alone is not enough. Things go wrong, agents misfire, and tools fail. When that happens, the difference between starting over and moving forward depends on whether you have preserved the reasoning behind your code.
SpecStory does more than capture prompts. It records the *why* - preserving the flow of ideas, corrections, and intent. For our user, that record turned into a lifeline. For other teams, it can mean faster reviews, reproducible experiments, and protection against invisible technical debt.
As AI accelerates how we write code, understanding the choices behind that code becomes even more important. SpecStory ensures that the reasoning is not lost - and in moments like this, it can even save the code itself.
Resilience in AI coding comes from context, and that is what SpecStory preserves.
---
### Learn more
- [SpecStory Docs](https://docs.specstory.com/)
- [GitHub](https://github.com/specstoryai/getspecstory)
---
# How to be an Open Source Hero: Contributing AI-Generated Code with Care
> A guide for contributors and maintainers on responsible AI-assisted open source contributions.
Published: 2025-10-02 - Author: jake, antaripa - URL: https://withstoa.com/blog/how-to-be-an-opensource-hero
AI coding tools are now part of everyday development. They help contributors explore new codebases, draft solutions quickly, and learn unfamiliar patterns. For people opening pull requests as contributors, that makes it easier than ever to participate. For maintainers, it often means more work reviewing code that may not always be complete or reliable.
The question is not whether AI belongs in open source, it's already there. The real question is how to use it responsibly so that your contributions add value rather than create extra work.

## If You're Contributing with AI
The key to contributing responsibly is transparency. Maintainers do not need you to hide your tools, they need to understand your process.
**Always disclose what you used:** Put it directly in your pull request description. Be specific: "Used Claude Code to generate the initial algorithm, wrote tests manually." If you used AI for comments or documentation, say that too. Honesty sets the right expectations and builds trust.
**Show your process:** Sharing your chat history can be surprisingly useful. Export your conversation from Cursor or Claude Code and link it in your PR. Tools like SpecStory make this simple by automatically saving your full session. Maintainers can then see how you arrived at your solution, which makes reviews faster and also helps others learn from your approach.
**Check the quality yourself:** AI is not a substitute for your judgment. Review every line, write and test the edge cases. If something feels unclear, ask your assistant to explain it until you understand. Use that review as a chance to learn and strengthen your own reasoning. If you still cannot explain the code in your own words, it is not ready to submit. This is what separates helpful contributions from noise.
Here is a simple way to phrase disclosure in your PR:
- **Minimal:** "Claude Code assisted with this implementation."
- **Better:** "Used ChatGPT to understand the codebase, implemented the solution manually."
- **Best:** "Cursor suggested this approach (see linked chat history saved in SpecStory), and I modified it significantly to fit our use case."
## If You're a Maintainer
Maintainers need to guide contributors clearly. Otherwise, every review risks turning into a guessing game about where the code came from.
**Set expectations up front:** Add an AI section to your CONTRIBUTING.md. Explain that disclosure is required and why it matters. Point to examples of what good AI-assisted contributions look like. Mitchell Hashimoto's Ghostty project is a good model: it requires disclosure and treats it as a normal part of collaboration.
**Review with care:** Watch for telltale signs of low-effort AI code through inconsistent styles, over-complicated functions, or generic comments. When in doubt, ask for clarification. It is perfectly acceptable to reject contributions that add more burden than value. Remember, you are building for people, not training a model.
**Build community norms:** The healthiest projects treat disclosure as routine, not shameful. Encourage contributors to share how they used AI, celebrate high-quality examples, and make sure newer developers learn what responsible usage looks like.
## A Practical Guide to Disclosure
Not every use of AI requires disclosure. Simple autocomplete, syntax fixes, or variable name suggestions are part of everyday tooling. What does require disclosure is any substantial code generation, help with debugging, documentation, or architectural decisions. If AI shaped the contribution in a meaningful way, let others know.
## Making It Work for Everyone
For contributors, treat AI like a junior developer. Let it propose ideas, but supervise carefully. Learn from what it suggests and build your own skills alongside it. Remember that on the other side of your pull request is a human maintainer with limited time.
For projects, AI-assisted contributions can become opportunities for growth. Share prompting strategies that work well. Build lightweight project guides so AI tools have the right context. And when a contributor does it right, highlight their PR as a positive example.
## The Path Forward
AI is not replacing open source contributors. It is giving them new ways to participate. The challenge is making sure that speed does not come at the cost of quality. Sustainable collaboration depends on transparency, respect, and careful review.
Tools like SpecStory help by preserving not just the code, but the reasoning behind it. That context makes contributions easier to review, easier to learn from, and easier to trust.
The principle is simple: use AI as an assistant, not as a shortcut. Be clear about when and how you used it, check the quality yourself, and always remember there are people on the other side of your pull request.
That way you are not just making a contribution but you are helping projects thrive, and that is how you become the hero of the projects you care about.
---
# SpecStory in Action: From AI Session to Blog Post
> How an early user turned a preserved AI coding session into a published blog post.
Published: 2025-09-29 - Author: antaripa - URL: https://withstoa.com/blog/from-ai-session-to-blogpost
Most people think AI coding is all about speed and treat their AI coding sessions as disposable. You generate the code you need, close the tab, and move on.
Isaac, one of the early SpecStory users, took a different path. After finishing a build session, he looked back at the SpecStory history and realized it wasn't just a log of prompts and responses. It was a record of false starts, arguments with his AI pair programmer, and the reasoning behind each decision.
> "The code shows what I built. The conversation shows why and how." - *Isaac Flath*
## What Isaac Did With His History
Isaac realized his SpecStory history was more than just a transcript. It captured the full flow of his coding session - the back-and-forth corrections, the points where the AI got things wrong, and the debates where he had to defend or rethink his design choices.
He turned that conversation history into a blog post.
Here's how the history helped him:
- **Concrete examples:** The conversation transcript preserved the exact prompts and corrections he used, giving his writing authenticity and clarity.
- **Capturing the process:** The history included tool calls, failed attempts, and course corrections. These became vivid examples in his article, things he would have forgotten without a record.
- **A natural outline:** The decisions and debates formed a ready-made structure for the article.
- **Faster writing:** With the history as source material, all he needed was to add reflection and polish. The heavy lifting was already done.
You can read Isaac's full breakdown here: [Turning an AI Conversation into a Blog Post](https://elite-ai-assisted-coding.dev/p/turning-an-ai-conversation-into-a).

## What Isaac's Story Shows
Isaac's experience highlights something every developer can use: **AI sessions are not throwaway**. With SpecStory, they can become valuable assets.
- **Histories preserve intent.** They capture not just the output but the thinking that shaped it.
- **Details make stories stronger.** Prompts and debates can be pulled directly into writing, tutorials, or documentation.
- **Logs become raw material.** A single AI session can produce both working code and a draft article to share.
## Conclusion
SpecStory preserves the reasoning behind your code. This is the real value of SpecStory. It does more than log your AI prompts. It captures the decisions, debates, and intent that normally vanish once the tab is closed. That record is what makes your work reusable, reviewable, and teachable.
Most coding tools help you move faster in the moment. SpecStory ensures that the knowledge behind your work is not lost to the moment. It transforms AI sessions from disposable interactions into durable context you and your team can rely on weeks or months later.
The result is more than efficiency. It is a stronger codebase, faster reviews, smoother onboarding, and a shared memory of why things were built the way they were.
In a world where AI keeps accelerating how we write code, SpecStory safeguards something enduring: the understanding and intent that make code maintainable. Speed matters, but context endures.
---
### Learn more
- [SpecStory Docs](https://docs.specstory.com/)
- [GitHub](https://github.com/specstoryai/getspecstory)
---
# Agile is a Sledgehammer: We Need a Toolbox
> How teams can move faster using mixed methodologies
Published: 2025-09-28 - Author: jake - URL: https://withstoa.com/blog/agile-is-a-sledgehammer-we-need-a
**tl;dr:** Agile is almost always misapplied today. Most teams aren't actually learning, they're just going through the motions. A quick test: ask your team for the three most surprising things they've learned in the last two sprints. If they can't answer, you're either using Agile where it's not needed or using it badly. Don't mistake tactical churn for strategy. Use Agile only when rapid learning is the goal, and reach for better tools when the job demands it:

- **For strategy:** Stop pretending backlogs are roadmaps. Use a venture-style model to drive big bets and clarity.
- **For well-understood work:** Skip the Agile theater and overhead. Shape Up + Lean, or just plan properly.
- **For optimization:** Switch gears into growth hacking with metrics, hypotheses, and experiments.
The goal isn't to "be Agile." It's to choose the right tool, at the right time, for the right job.
---
In the world of software development, Agile has long been hailed as the ultimate solution to our productivity woes. It's the Swiss Army knife of methodologies, the panacea for all project management ills. But here's a hard truth: Agile is a hammer and sometimes we need a different tool.
## The Rise of Agile: A Brief History
To understand why Agile has become such a blunt instrument, we need to look at its origins. Back in the 1990s, when grunge was king and the internet was just learning to crawl, software development was dominated by the waterfall model. Imagine building software like constructing a skyscraper: meticulous planning, rigid phases, and a prayer that nothing changes along the way.
Waterfall promised thorough upfront planning and cost estimation. It was the comfort blanket for businesses making investment decisions. Should we build new product Y or expand features of product X? Just look at the detailed Gantt chart and you'll know!

But there was a tiny problem: software isn't a skyscraper that can be fully architected up front. Requirements change, technologies evolve, and markets shift faster than you can say "Y2K bug". Learning must be baked into parts of the process. Waterfall projects often ended up delivering outdated solutions to problems that no longer existed.
Enter Agile, the rebellious teenager of software methodologies. Born from the Agile Manifesto in 2001, it promised flexibility, customer collaboration, and the ability to respond to change. It was a breath of fresh air in a world of suffocating processes.
## The Agile Advantage: When the Sledgehammer Hits the Nail
Let's be clear: Agile, when applied correctly, can be incredibly powerful. Imagine a team working on a new feature for a rapidly evolving market. Requirements are fuzzy, user needs are still being discovered, and the competition is breathing down your neck.
In this scenario, Scrum (the most popular Agile framework) shines. Two-week sprints allow for rapid learning. Daily stand-ups keep everyone aligned. Sprint reviews provide regular checkpoints with stakeholders. It's a beautiful dance of collaboration and adaptation.
But here's the rub: not all projects are created equal. Sometimes, the rapid changes in requirements stem from internal dysfunction, unclear company direction, or simply a lack of proper planning. And this is where our Agile hammer starts to crack the foundation instead of building it.
## When Agile Goes Awry: The Pitfalls of Misapplication
In my years as a product leader across companies of all sizes, I've seen Agile misapplied over and over again. Here are the common pitfalls:
1. **The Two-Week Tunnel Vision**: Teams become so focused on the sprint cycle that they lose sight of the bigger picture. They're driving on a backcountry road at night with only a flashlight to guide their way.
2. **Agile Theater**: Daily stand-ups become status reports. Sprint planning becomes a rushed affair of throwing tickets into a sprint. Retrospectives become venting sessions with no real improvements.
3. **The Planning Paradox**: Scrum was designed for execution, not strategic planning. Yet, many organizations try to shoehorn their entire product strategy into this framework. It's like trying to write a novel using only Post-it notes.
4. **One Size Fits None**: Agile is often applied indiscriminately, whether the project involves cutting-edge innovation or routine maintenance. We're using a hammer to both hang a picture and plaster the wall.
## The Fatal Flaws: Strategic Myopia and Misplaced Flexibility
The most damaging aspect of Agile's misapplication comes in two flavors:
### Failure Mode 1: Agile for Strategic Planning
One of the worst agile failures I've seen is a lack of strategic planning. Teams continually gather input from customers and stakeholders and capture it to their backlog. Then this backlog is used to create the team's roadmap. This is backwards. Annual or quarterly planning requires a broader perspective, one that Agile's iterative approach simply isn't designed to provide.
But the problem goes deeper than just misapplying Agile. The root issue lies in how organizations approach strategic planning altogether. Typical quarterly planning processes cascade down the org chart, with each layer of management asking the one below it, "what's your strategy and roadmap." Ultimately this ends with teams themselves, unarmed and unprepared, being asked to answer these questions with little or no company direction or strategy. Here's where things go off the rails:
1. **Unarmed Teams**: Teams are asked to strategize without being equipped with the right tools or context. They're expected to produce a roadmap out of thin air.
2. **The Agile Crutch**: In the absence of better options, teams fall back on what they know -- Agile. They squint at their backlog, trying to divine a strategic roadmap from a list of tasks. And what's worse, most agile approaches dictate full team participation in all activities, translating into a massive waste of time creating a fake roadmap.
3. **Perfunctory Planning**: With limited time and resources, this "planning" becomes a box-ticking exercise. Teams want to minimize the time wasted on it and so treat it as an afterthought rather than the critical activity that it is.
4. **The Management Cop-Out**: Managers and leaders often contribute little more than a crappy template and a litany of Google Docs comments. Their primary role becomes concatenating the results from their teams, adding little strategic value.
5. **Misaligned Outcomes**: The result? A collection of bottom-up tactical plans masquerading as strategy, often misaligned with the company's broader goals and market realities.
This approach fundamentally misunderstands the nature of strategic planning. It's like asking a chef to plan next month's menu by looking at today's grocery list.
### Failure Mode 2: Agile for Well-Understood Deliverables
Not every project is a journey into the unknown. Sometimes, the requirements are clear, the technology is familiar, and the path is well-trodden. In these cases, the overhead of Agile ceremonies can actually slow things down.
The misapplication of Agile here is more than just a minor inefficiency, it's a fundamental mismatch that creates a host of issues:
1. **Limited Visibility**: Agile, particularly Scrum, typically provides visibility only into the next two-week sprint. For well-defined projects, this artificial shortsightedness is unnecessary and counterproductive. We're choosing to wear blinders when we could have a clear view of the road ahead.
2. **False Sense of Flexibility**: We treat these projects as if they're in constant flux, when in reality, they're not. This mindset often leads to unnecessary pivots and changes, introducing instability where stability would be more beneficial.
3. **The Planning Crutch**: Agile can become an excuse to avoid thorough upfront planning. We tell ourselves, "We'll figure it out as we go along," even when we have enough information to make solid plans from the start. If you start building a deck without a rough plan, just be ready for many trips back to the lumber yard.
4. **Misallocated Effort**: The time and energy spent on Agile ceremonies (daily stand-ups, sprint planning, retrospectives) for well-understood work is often disproportionate to the value they provide. We don't need a committee meeting to change the batteries on our smoke detector.
5. **Lost Predictability**: One of the key benefits of working on well-understood problems is the ability to predict timelines and outcomes more accurately. By defaulting to Agile, we forfeit this advantage, choosing perpetual uncertainty over achievable predictability.
It's important to note that advocating for more upfront planning doesn't mean a full return to Waterfall. There's a middle ground where we push ourselves to ask and answer tough questions early on, without falling into the trap of trying to plan every detail in advance.
By recognizing when a project is well-understood, we can choose a more appropriate methodology that allows for clearer long-term visibility, more accurate predictions, and less ceremonial overhead. This approach not only saves time and resources but also provides the broader organization with the predictability it needs for effective planning and coordination.
## The Way Forward: Precision Tools for Precision Work
So, if Agile isn't always the answer, what is? We need a more nuanced approach, one that matches the methodology to the nature of the work. Based on the successes and failures that I've seen and lived, here's what I propose:
### **The Venture Model for Strategic Planning**
Seeing new product development through the eyes of an investor can provide a more effective framework for strategic planning and innovation. This approach:
- Better characterizes the inherent risks and uncertainties
- Allows for different criteria and metrics at various stages of product maturity
- Provides a framework for making informed bets on innovation
Let's dive deeper into how the venture model works and how companies can adapt it:
### Key Aspects of the Venture Model
1. **Clear Stage Awareness**: Venture-backed companies know exactly what stage they're at (pre-seed, seed, Series A, Series B, etc.) and what their next focus should be. This clarity drives their strategy and execution.
2. **Fixed Investments**: Unlike the open-ended budgets often seen in corporate projects, ventures receive fixed investments tied to specific milestones.
3. **Pitching for Resources**: Teams must pitch to raise money at key inflection points, forcing them to articulate their progress and future plans clearly.
4. **Embracing Failure**: Ventures that don't prove themselves out at a given stage are allowed to fail, ensuring resources are allocated efficiently.
5. **Lean Teams**: Venture teams are typically just big enough for the task at hand. Roles often blur as people do whatever it takes to move the project forward.
6. **Aligned Incentives**: Team members are heavily invested in a successful outcome, with personal rewards tied directly to the venture's success.
7. **High Autonomy**: While investors (acting as board members) can provide input, they don't dictate day-to-day operations. Control is exercised primarily through funding decisions and the ability to replace leadership.
### Adapting the Venture Model for Companies
When implementing a venture model within a company, it's crucial to recognize and leverage the unique advantages of the corporate environment while being aware of potential limitations:
1. **Simulating Investor Breadth**: While startups can pitch to hundreds of potential investors, internal ventures have a limited pool. Companies can simulate this breadth by empowering multiple executives with independent investment budgets.
2. **Expanding Pitch Exposure**: Real VCs hear thousands of pitches annually. To broaden perspective, companies could consider allowing outsiders to pitch ideas as well. This could be more insightful and more interesting than traditional job interviews.
3. **Leveraging Horizontal Assets**: Unlike standalone startups, internal ventures can tap into valuable company-wide assets:
- Recognized Brand
- Existing Distribution channels
- Customer Data
- Compliance support
- Ties into existing customer workflows
- Network effects across users and partners
- Amortized overhead (e.g. facilities, HR, legal)
It's crucial that the entire portfolio of internal ventures leverages these strengths.
- **Utilizing Horizontal Support Teams**: Companies have an advantage over traditional VC networks in their ability to provide robust internal support. Organize these horizontal teams as services that internal ventures can easily plug into, similar to best-in-class SaaS solutions.
By adopting this venture model approach, companies can foster a more dynamic, accountable, and innovative environment for strategic planning and new product development. It allows for clearer goal-setting, more efficient resource allocation, and a balance between autonomy and accountability that often eludes traditional corporate structures.
Learn more: I haven't found a great source for details on the Venture Model inside companies. For now, learn all you can about [pitching startup ideas](https://stripe.com/guides/atlas/pitching) and [running lean](https://www.leanfoundry.com/books/running-lean).
### **Shape Up + Lean When It's Time to Execute in a Clear Direction**
For projects with clearer parameters, a combination of Shape Up and Lean principles can provide a more effective approach than traditional Agile methods.
### Shape Up: A Brief Overview
Shape Up is a methodology that emphasizes thoughtful upfront planning (shaping) followed by focused execution. It was developed by 37signals as an alternative to traditional agile methodologies. Here are the key aspects of Shape Up:
1. **Shaping is Distinct from Implementing**: Shaping is a separate activity that happens before any project begins. It's about defining the problem, roughing out a solution, and setting boundaries.
2. **Blurred Lines Between What and How**: Unlike traditional approaches where product managers define "what" and developers figure out "how," Shape Up encourages a more integrated approach where these lines blur during the shaping process.
3. **Dedicated Time for Shaping**: Shaping drives the process and is not an afterthought. It gets dedicated time and attention, ensuring that projects are well-defined before they begin.
4. **Small Team for Shaping**: The entire team doesn't participate in shaping. Instead, an individual or a very small group does this work, allowing for more focused and efficient planning.
5. **Complete Projects, Not Tasks**: Teams are given complete projects, not a list of tasks. The shaping process provides clear business challenges, boundaries, and guidelines without prescribing an overly detailed solution.
6. **Projects as Commitments**: Projects that don't get completed in the allotted time (typically weeks) don't automatically continue. This creates a sense of urgency and helps prevent scope creep.
7. **Flexible Implementation**: While Shape Up provides a framework for planning and scoping, teams have the flexibility to choose their working methodology for the implementation phase.
### Integrating Lean Principles
As noted, once a project has been shaped, teams can adopt any methodology they choose. But one especially effective approach is to use Lean principles for the implementation phase. Lean, with its focus on eliminating waste and continuous improvement, complements the Shape Up methodology well. Here's how they can work together:
1. **Kanban for Workflow Management**: Use a Kanban board to visualize and manage the workflow of the shaped project. This aligns with Lean's principle of visualizing work and limiting work in progress.
2. **Continuous Flow**: Instead of fixed sprints, adopt a continuous flow of work, pulling new tasks as capacity becomes available. This reduces the overhead of sprint planning and aligns with the Shape Up ethos of giving teams complete projects.
3. **Just-in-Time Planning**: While the overall project is shaped upfront, detailed task planning can happen just-in-time, aligning with Lean principles and allowing for adaptability within the project boundaries.
4. **Focus on Value**: Both Shape Up and Lean emphasize delivering value to the customer and the business. Use this shared focus to guide decision-making throughout the project.
5. **Continuous Improvement**: Be judicious with team retrospectives to identify areas for process improvement. Lean principles would encourage just enough reflection at just the right time and no more. Rather than wait for or plan separate retros, encourage process improvement at any time.
By combining Shape Up's thoughtful upfront planning with Lean's efficient execution principles, teams can benefit from:
- Clearer long-term visibility (typically 6-8 weeks)
- More accurate predictions of project outcomes
- Reduced ceremonial overhead compared to traditional Agile methods
- Improved focus on delivering value
- Greater flexibility in day-to-day work management
This approach not only saves time and resources but also provides the broader organization with the predictability it needs for effective planning and coordination, all while maintaining the flexibility to adapt to changes within the project scope.
Learn more: [Shape Up](https://basecamp.com/shapeup) from 37signals and a good article on [using Trello to implement Kanban](https://www.toptal.com/agile/guide-managing-development-kanban-trello).
### **Growth hacking for product optimization**
When your main objective is to improve adoption or usage of your product, it's time to switch gears into growth hacking mode. This approach is fundamentally different from new product or feature development, focusing instead on measurable outcomes, hypotheses, and experiments.
### Understanding the Product Funnel and AARRR Metrics
At the core of growth hacking is the product funnel, often represented by the "Startup Metrics for Pirates" or AARRR:
1. **Acquisition**: How do users find you?
2. **Activation**: Do users have a great first experience?
3. **Retention**: Do users come back?
4. **Referral**: Do users tell others?
5. **Revenue**: Can you monetize?
These metrics provide a framework for understanding and optimizing each stage of the user journey.
### The Growth Hacking Process
Here's how to approach growth hacking effectively:
1. **Measure First**: Before you can improve, you need to know where you stand. Establish baseline metrics for each stage of your funnel.
2. **Create Hypotheses**: Formulate ideas about what might improve your metrics. Crucially, define desired outcomes upfront to avoid bias. A good hypothesis includes both the expected positive impact and potential negative effects on other metrics.
3. **Prioritize**: Use your baseline measurements to prioritize hypotheses that are likely to have the highest impact. Focus on the areas of your funnel that need the most improvement or that align with your current business goals.
4. **Run Experiments**: Design and execute tangible tests for your hypotheses. This is where the rubber meets the road in growth hacking.
5. **Analyze and Iterate**: Based on the results of your experiments, refine your approach and start the cycle again.
### Tips for Effective Growth Hacking
- **Step Back from Your Product**: Adopt an outside-in, customer-first view. What's on your users' minds? What do they want, regardless of what you want them to want?
- **Use Statistics Wisely**: Learn enough about statistics to run experiments correctly, or find someone (or a tool) who can. If you can't run quantitative experiments, qualitative ones can still provide insights.
- **Balance Experimentation and Intuition**: Just because you can experiment doesn't mean you should. Use experience and intuition to short-circuit endless experimentation. Sometimes, you can turn a complex A/B/C/D test into a simple A/B test, saving time and resources.
- **Know When to Switch Gears**: If you find yourself unable to run meaningful experiments, it might be a sign that you're using the wrong tool at the wrong time. Consider if you're in a phase where Agile for learning might be more appropriate than optimization experiments.
### When to Use Growth Hacking
Growth hacking is most effective when:
- You have a product with a clear value proposition
- You're looking to optimize specific stages of your funnel
- You have enough users to run statistically significant experiments
- You're able to implement and measure changes quickly
By adopting this data-driven, experiment-focused approach, you can systematically improve your product's performance and drive growth. Remember, the key is to stay focused on measurable outcomes and to always keep your users' needs at the forefront of your optimization efforts.
Learn more: [Step-by-step overview of growth hacking](https://growthtribe.io/blog/the-growth-hacking-process-a-step-by-step-guide). Or, for more depth, the free and paid materials from [Reforge](https://www.reforge.com/blog/growth-system) are very good.
### **And Yes, Agile for Accelerated Learning**
When the thing you need most is rapid learning in the face of a complex and quick-moving market, an agile approach can be well-suited to the task. However, the term "Agile" has been so overused and misapplied that it's almost lost all meaning. There are entire books, consultancies, and corporate transformations dedicated to Agile adoption, often with conflicting advice.
### Assessing Your Current Approach
If your current approach is working well and genuinely results in rapid learning, stick with it. Make minor tweaks and improvements as most agile methodologies would suggest. But how do you know if you're getting the learning you need?
Here's a quick test: Ask one of your agile teams to name the three most surprising things they've learned in the past two sprints. If you get nothing substantial back, it could mean one of two things:
1. The team doesn't actually need to learn and is using the agile sledgehammer unnecessarily.
2. They're not using agile effectively for learning.
### Starting Fresh with Scrum
If you're not getting the learning you need, consider adopting a new methodology wholesale. For a clean slate, I recommend Scrum. It's concrete, clear, and well-established. Scrum provides a framework and terminology that your teams can quickly understand, with built-in mechanisms for continual improvement.
Key elements of Scrum include:
- Defined roles: Product Owner, Scrum Master, Scrum Team
- Clear artifacts: Product Backlog, Sprint Backlog, Shippable Product
- Standardized Rituals: Sprint Planning, Daily Standups, Sprint Review
- Continuous learning: Sprint Retrospectives, Improvement and customization
When adopting Scrum, resist the urge to cherry-pick practices at first. Give teams the opportunity to experience all aspects of vanilla Scrum before they drop or alter some parts. This may seem counterintuitive, but it's actually easier to start with the whole thing and then make thoughtful changes, rather than trying to build up bit by bit.
### Tips for Effective Agile Learning
1. **Customer Collaboration**: Ensure you have a real customer working closely with your agile team. This direct connection is crucial for rapid learning and validation.
2. **Measure Learning, Not Just Delivery**: Focus on the speed of learning versus the speed of delivery. Agile is about delivering software that aligns with real customer needs, not just about quickly pushing out features.
3. **Embrace Uncertainty**: Accept that in complex, fast-moving markets, you don't have all the answers. Use agile practices to explore and learn rapidly.
4. **Frequent Reflection**: Use sprint retrospectives not just to improve processes, but to explicitly discuss and document learnings about the market, customers, and product.
### A Word of Caution
Please, if you take nothing else from this, don't force all of your teams to start practicing Scrum (or any other agile methodology) today. Acknowledge that different teams are at different phases in their own projects and need to choose the right tools for their specific situations.
Instead:
1. Arm your teams with a variety of tools in their planning toolbox, including the ones we've discussed in this article.
2. Help them gain the wisdom to know when to switch tools.
3. Foster a culture where it's okay to experiment with different methodologies and learn from the results.
Remember, the goal is not to be "Agile" for the sake of it, but to create an environment where teams can learn rapidly and deliver value effectively. Sometimes that means using Scrum, sometimes it doesn't. The key is having the flexibility and insight to choose the right approach for each unique situation.
Learn more: [The Scrum Framework](https://www.scrum-institute.org/contents/The_Scrum_Framework_by_International_Scrum_Institute.pdf), in detail.
## Conclusion: The Right Tool for the Right Job
Agile isn't inherently flawed; it's how we've been wielding it that's the problem. It's time to expand our toolkit. By adopting a more nuanced approach, we can enjoy the benefits of Agile where it truly shines while using more appropriate methods for strategic planning and well-defined projects.
Remember, in the world of product development, one size does not fit all. Sometimes you need a sledgehammer, sometimes a screwdriver, and often, you need both. The key is knowing when to use each.
So the next time someone suggests "Let's do this project Agile," take a step back and consider: What's the right tool for each phase of this project? Your future self (and your team, and your stakeholders) will thank you for choosing the right tools for the right jobs, rather than forcing the entire project into a single methodology.
---
# The Middle Way
> How AI is Actually Changing Software Development
Published: 2025-09-23 - Author: jake - URL: https://withstoa.com/blog/the-middle-way
We recently got together to talk about what's really happening with AI and software development. Not the hype, not the fear, just what we're seeing on the ground.
## Don't Harsh Our Vibes
The "vibe" label sells short what's happening with coding agents. "Vibe" implies this technology is a toy--just faster autocomplete or smoother Stack Overflow. When you ship production software, you throw the vibes away and use your same old workflow.
Our experience is different. Agents are meaningfully changing how engineers build production software. Companies are reorganizing around agentic coding--this isn't a toy.
> *Our friends at Assignar are using agentic coding workflows to build complex construction finance management software. GitHub Copilot coding agent, Cursor Bugbot, and Claude Code /security-review all play a role on the team. -Jake*
## But the Vibes Aren't Immaculate
We're on the agentic bandwagon, but we can't just wait for big companies to throw billions at their models and call it a day.
Here's why: these models run at an unimaginable scale, but they remain constrained by the data that they have access to. They learn from code, documentation, Stack Overflow posts--anything written down. But if something isn't in the text, the model doesn't know about it.
And so much of what makes software engineering hard was never written down. The crucial context lives in engineers' heads, in Slack threads that get buried, in whiteboard sessions that were never photographed. The models can't learn what was never captured.
## Code Is Just an Approximation of Intent
Our codebase isn't the truth--it's just what happens to run. The actual truth is the intent: what we wanted the software to do, what constraints we faced, what tradeoffs we made. When something breaks, you need this intent to fix it properly. Without it, you might fix the bug but break the use case, optimize the wrong thing, or undo a critical workaround.
> *I've used agentic coding tools to build entire new features, like the markdown editor inside BearClaude, only to have it create a regression in the Chat History view (a completely unrelated part of the code base). When "vibing", manual smoke tests are typically the answer for spotting regressions. But when software engineering with AI assistance, we need something more thoughtful. -Jake*
## The False Revolution: New Panes of Glass
As engineers, our natural tendency is to solve problems with new layers of abstraction. Let the agents handle the messy details underneath while we work at a higher level. Ambitious projects like plain-lang--which lets you code in plain English sentences--are attempting precisely this, defining a natural language abstraction that simplifies everything below.
It's a compelling vision. But abstraction layers rarely eliminate complexity--they just relocate it.
> *At Sym, we fell into this trap. We created elegant devtools for just-in-time AWS access. You could request permissions through our clean interface: "I need production database access." Beautiful.*
>
> *Except first, teams had to untangle their existing AWS permissions. "We have a role called 'WebAppProd' with... who knows what permissions? Created three years ago, modified seventeen times, attached to twelve services." Before using our "simplification," they needed to understand both IAM and our abstraction of IAM. We'd added another pane of glass, not removed the complexity underneath. -Jon*
The same pattern awaits AI coding abstractions. As these natural language systems grow complex, they'll need all the same tools any codebase needs. Natural language debuggers. Natural language version control. Natural language merge conflicts. We end up reinventing the wheel at a new level of abstraction, now maintaining two layers of complexity instead of one.
## The Real Revolution: A New Abundance
The middle way is paradoxical: it's revolutionary precisely because it's not trying to be revolutionary. It's about finally doing what we always knew we should do: Documentation. Tests. Clear specifications. Design discussions. Architecture decisions. Code reviews that review thinking, not just syntax.
We skip these because they're too expensive. But AI creates a new abundance. When documentation becomes nearly free, you stop rationing it. When test writing takes seconds, not hours, you stop skipping it.
> *Now when I finish working on something, I ask the agent: "Update the tests and docs." "Can you help me DRY up this code?" This often takes seconds and sometimes uncovers an issue I missed. These tasks used to be the TODOs that haunt a codebase--things we'd "definitely get to in V2." The difference isn't that I'm working faster; it's that I'm actually completing the work. The boring, essential parts that make code maintainable are finally getting done. -Jon*
## What Actually Changes
What changes:
- Code review becomes intent review--PRs without documentation get rejected
- Context persists across time and team changes
- Standards rise as costs drop--incomplete work becomes unacceptable
- The "nice-to-haves" become table stakes
What doesn't:
- Humans specifying intent--this gets more important, not less
- The complexity of understanding existing systems
- Software evolution and changing requirements
- Bugs, edge cases, and the fundamental challenges of building software
## What We Still Need to Figure Out
### Feedback Loops
Encoding intent at project start isn't enough. When you explain to an AI what you're building, when you iterate on approaches, when you ask it to explain existing code--all that context usually evaporates. What if it didn't?
What if these artifacts could be validated and refined over time? Fix a bug, update the intent. A new team member discovers gaps; they fill them in. This creates a virtuous cycle instead of entropy. We've learned from the agile revolution that overly precise up-front specification doesn't leave room for learning and iterating. So the best intent-driven workflow needs to allow people to work iteratively and stay in flow while still capturing each new learning and decision.
> This is a big part of why we've built SpecStory as a connector to existing AI coding tools. It allows developers to stay focused on the task at hand, defining and delivering great software, while recording a clean log of that definition. This way, 2 months from now, when you need to remember "why did I decide to go with a JSON field in my database instead of multiple columns?" you can ask that exact question of your own AI chat history. -Jake
## The Real Vibes Will Not Be Televised
The televised version is what gets clicks--programming languages that look like English, YouTube demos of full apps built in an afternoon, breathless threads about replacing all engineers.
However, the real revolution occurs in the unglamorous daily practice. It's in the PR rejected because the documentation doesn't align with the intent. It's in the feedback loop that catches drift between code and docs. It's finally having time to write architecture decision records because agents handle the boilerplate.
Coding agents give us the resources to do all the things we always should have done. If we can encode software engineering components into something agents understand, we can truly "make it so."
How are you refining your simple daily practices to take advantage of the real power of AI-assisted software development?
---
*This piece grew out of a conversation about how AI is actually being used in software development today. We'd love to hear what you're seeing in your own work.*
*Jon is a founding engineer at Distill, a platform for learning about people and companies. Previously, he co-founded Sym, a devtool for security engineers, and led engineering teams in health tech, infrastructure, and enterprise software.*
*Jake is the co-founder of SpecStory, a tool that helps developers preserve and share their AI coding sessions. Before SpecStory, Jake led product teams at Docker and DigitalOcean.*
Watch the conversation here:
---
# Intentional Underspecification
> When bad prompting is actually good
Published: 2025-08-04 - Author: jake - URL: https://withstoa.com/blog/intentional-underspecification
In AI-assisted development, we typically emphasize well-structured prompts with comprehensive context. Tools like SpecFlow exemplify this approach, enabling developers to provide rich contextual information. However, there are specific scenarios where intentionally underspecified prompts yield superior results through enabling AI experimentation and creative problem-solving.

**Understanding Intentional vs. Unintentional Underspecification**
The critical distinction lies in purposeful design. Intentional underspecification serves as a strategic tool for discovery, while unintentional vagueness leads to unpredictable or suboptimal outputs. This technique requires careful consideration of when precision is essential versus when exploration adds value.
**Practical Applications for Underspecified Prompts**
**1. Data Model Design**
- **Instead of:** "Create a PostgreSQL schema with users, posts, and comments tables"
- **Try:** "Design a data structure for a community discussion platform"
- **Benefit:** AI may suggest alternative approaches like graph databases for relationship-heavy data or document stores for flexible content structures
**2. UI/UX Design Exploration**
- **Instead of:** "Create a React form with email and password fields using Material-UI"
- **Try:** "Design an onboarding experience for a meditation app"
- **Benefit:** AI might propose progressive disclosure patterns, biometric authentication options, visual breathing exercises during loading, or gamification elements you hadn't considered
**3. Sample Data Generation**
- **Instead of:** "Generate 10 user records with name, email, age, and registration date"
- **Try:** "Create realistic sample data for a fitness tracking application"
- **Benefit:** AI often includes relevant patterns you might overlook, like seasonal variations, user behavior clusters, edge cases
**4. Architecture Decisions**
- **Instead of:** "Implement this as a REST API with PostgreSQL"
- **Try:** "This system needs to handle real-time collaboration for distributed teams"
- **Benefit:** Opens possibilities for WebSocket implementations, event-driven architectures, or hybrid approaches
**5. Technology Stack Selection**
- **Instead of:** "Use React with Redux for state management"
- **Try:** "Build an interactive dashboard for data visualization"
- **Benefit:** May surface alternatives like Vue with Pinia or even specialized visualization frameworks
**Implementation Strategy**
1. **Identify Exploration Opportunities**
- Early-stage design decisions
- Proof-of-concept development
- Architecture evaluation phases
- Creative problem-solving scenarios
2. **Run Parallel Experiments**
- Submit the same underspecified prompt multiple times
- Collect diverse approaches
- Request comparative analysis of the generated solutions
3. **Apply Constraints Post-Generation**
- After receiving initial suggestions, introduce your specific requirements
- Ask the AI to evaluate options against your constraints
- Iterate based on insights gained
4. **Engage in Clarifying Dialogue**
- After receiving an initial proposal, prompt the AI to ask clarifying questions
- Example follow-up: "What questions would you need answered to determine if this approach or an alternative would work better for my specific context?"
- This technique surfaces hidden assumptions and unconsidered constraints
- The AI's questions often reveal critical factors you hadn't explicitly considered
**Framework for Decision Making**
Consider these questions when deciding specification level:
- Is this a greenfield opportunity or constrained by existing systems?
- Would alternative approaches provide significant value?
- Are there established patterns that must be followed?
- Is this exploratory work or production implementation?
**Practical Example: Storage Solution Selection**
Rather than specifying "implement SQLite for local storage," consider:
1. Describe the context: "Small application, local deployment, structured data with relationships"
2. Review AI suggestions: might propose SQLite, but also IndexedDB for browser-based apps, or embedded key-value stores
3. Engage in dialogue: "What questions would help determine the best storage solution for this use case?"
4. Evaluate trade-offs: request analysis of each option based on the clarified requirements
5. Make informed decision: choose based on comprehensive understanding rather than initial assumptions
**Key Takeaways**
- Underspecification is a tool, not a default approach
- Use it deliberately during exploration and design phases
- Leverage AI as a thought partner for discovering possibilities
- Engage in iterative dialogue to uncover hidden requirements
- Always validate suggestions against your specific requirements
This balanced approach to prompt engineering enables developers to harness AI's creative potential while maintaining control over critical decisions. The goal is not to abdicate responsibility but to expand the solution space before converging on optimal implementations. By treating AI as a collaborative partner that can both propose solutions and help refine requirements, we create a more robust decision-making process that combines human insight with machine exploration.
---
# Building a Mintlify Alternative with AI (Part 1)
> From idea to 'Hello World' in under an hour - planning, prototyping, and setting up a Next.js documentation platform using AI-driven development.
Published: 2025-07-14 - Author: jake - URL: https://withstoa.com/blog/building-a-mintlify-alternative-with-AI-Part-1
## Building a Mintlify Alternative with AI (Part 1): From Idea to "Hello World" in Under an Hour
### A step-by-step guide to planning, prototyping, and setting up a Next.js documentation platform using AI-driven development.
In this tutorial, we'll build TinyDocs, an open-intent alternative to Mintlify, using AI-driven development to handle planning, research, and coding.
[](https://www.youtube.com/watch?v=VF2VFFQXoL8)
*Click above to watch the complete video walkthrough of this tutorial*
Have you ever looked at a SaaS tool and thought, "This is great, but I wish it weren't so expensive?" That's exactly the thought that kicked off this project. Tools like [Mintlify](https://mintlify.com/) are fantastic for creating beautiful, professional documentation sites from Markdown files. They offer a seamless experience, managing everything through a Git repository. But for small teams or solo founders, the price tag can be a bit steep.
This sparked a question: could we build a simpler, open-source alternative? Something that captures the core magic of Mintlify-like auto-deploying from Markdown updates and having a built-in editor-but without the hefty monthly bill. In this post, I'll walk you through the very first steps of building this "Micro SaaS" project, which we're calling **TinyDocs**. We'll go from a blank page to a fully planned, prototyped, and running Next.js application, all with the help of an AI coding agent.
We'll cover the entire initial process: brainstorming the concept, defining user needs, researching the right technologies, scaffolding the project with AI, and even pushing our first commit to GitHub. Whether you're curious about AI-driven development or looking to build your own documentation solution, this guide will give you a practical roadmap to get started.
## The Vision: A Simpler, Cheaper Mintlify
The goal isn't to clone Mintlify feature-for-feature. The inspiration comes from its excellent developer experience: your documentation lives as Markdown or MDX files in a repository, making it easy to manage and version control.

*Caption: Documentation sites like this one, built with Mintlify, are powerful but can be costly.*
However, Mintlify's strength can also be its complexity. We want to build something simpler. The core vision for TinyDocs is to provide an affordable, easy-to-use, and deeply customizable documentation platform for technical founders and small software teams. A key part of this vision is making it "open intent," meaning anyone can take our open spec and build or extend their own version.
## Phase 1: Planning and Brainstorming with AI
Instead of jumping straight into coding, a solid plan is crucial for a better outcome, especially when working with AI. For this, we used an AI-powered project planner to structure our thoughts and make key decisions upfront.

*Caption: Using a structured planning tool helps guide the brainstorming process for a better final product.*
### Defining the Core Idea
We started with a simple prompt to capture the essence of the project:
> This is a documentation site app. It should let you create, manage, and publish your docs. It should feel a lot like mintlify except simpler. It autogenerates documentation from your project's code and AI chat history.
This initial thought process helped us establish the main pillars:
1. **Creation, Management, Publishing:** The core lifecycle of documentation.
2. **Mintlify-like Feel:** A high-quality, modern user experience.
3. **Simplicity:** Avoid feature bloat and focus on the essentials.
4. **AI-Powered Generation:** A key differentiator to speed up the initial documentation process.
### Researching the Tech Stack
With a basic idea in place, the next step was to explore the specific technologies. This is where the messy, non-linear part of development often happens, and it's a perfect task for an AI assistant.
#### MDX vs. Markdoc vs. Quarto
Mintlify uses **MDX**, which allows you to embed JSX components directly in your Markdown. This is incredibly powerful for creating interactive and rich content. But are there other options? We explored a few:
- **Markdoc:** An open-source, Markdown-based format from Stripe. It's great for structured, consistent documentation with custom tags but isn't designed for the kind of live, interactive editing we envisioned.
- **Quarto:** A system designed for scientific and technical publishing. It's fantastic for computational documents (think Jupyter notebooks) but felt like overkill for our needs.

*Caption: Researching different documentation formats to find the best fit for our project's goals.*
Ultimately, the AI's recommendation was clear: stick with **MDX**. It offers the perfect balance of content and interactivity, and it's already used by industry leaders like Mintlify, Docusaurus, and Next.js.
#### The Perfect Markdown Editor
A great documentation site needs a great editor. My personal favorite is the one in [Obsidian](https://obsidian.md/) because of its seamless, inline preview. A quick query to our AI assistant revealed that Obsidian uses **CodeMirror 6**. This became a key technical requirement for TinyDocs-we want that same fluid, WYSIWYG-like editing experience.

*Caption: The editing experience in Obsidian, powered by CodeMirror 6, is the goal for TinyDocs.*
### Finalizing the Stack
After the research phase, we settled on a modern, robust tech stack:
- **Language/Framework**: TypeScript and Next.js
- **Cloud Services**: Vercel (Hosting), Supabase (Database, Auth, Storage), Resend (Transactional Emails)
- **Key Packages**:
- `next-mdx-remote`: To render MDX content fetched at runtime (e.g., from a database or a Git repo), which is crucial for our dynamic editing features.
- `@octokit/rest`: The official GitHub client for Node.js to handle syncing with repositories on the backend.
- `codemirror`: The core of our rich text editor.
## Phase 2: From Plan to Running App
With a solid plan in hand, it was time to bring TinyDocs to life. We used our AI coding agent, Claude Code, to turn our specification document into a running application.
### Generating the Initial Tasks
First, we prompted the AI to create a task list for the initial development session. The goal was to get a minimal "Hello World" page up and running.

*Caption: The AI breaks down the plan into a concrete, actionable task list for the initial setup.*
### Scaffolding the Next.js Project
We instructed the AI to initialize a new Next.js project. This is where we hit our first, very common, real-world snag.
**Common Pitfall:** AI agents can sometimes struggle with project scaffolding commands like `create-next-app`, often creating nested subdirectories or misconfiguring files. It's a known challenge in agentic development. In our case, the agent initially failed to run the command correctly.
**Solution:** We took a step back and prompted the agent to let us initialize the project manually. This is a great pro-tip: **sometimes it's more efficient to handle initial setup yourself and then let the AI work within that established structure.**
After a bit of back and forth, the AI successfully set up the project structure, installed dependencies, and created a basic landing page.
### Debugging a Build Error
With the files in place, we ran the development server:
```bash
npm run dev
```
And... we hit another snag! A build error related to Tailwind CSS.

*Caption: Encountering and debugging build errors is a natural part of the development process, even with an AI partner.*
This error occurs because the PostCSS plugin for Tailwind was not configured correctly during the manual setup. This is exactly the kind of issue that `create-next-app` usually handles automatically. Fortunately, the AI was able to identify the problem and fix it by installing the correct dependencies (`tailwindcss`, `postcss`, `autoprefixer`) and creating the necessary configuration files.
After the fix, we restarted the server, and success! We had a live, running landing page for TinyDocs.

*Caption: Success! The minimal viable product is up and running locally.*
## Phase 3: Committing to GitHub
The final step for this initial session was to get our project under version control and pushed to GitHub.
### The Importance of `.gitignore`
Before running `git init`, we prompted the AI to create a comprehensive `.gitignore` file for a Next.js project. This is a crucial step to prevent committing unnecessary files like `node_modules` or local environment variables (`.env.local`).

*Caption: A good `.gitignore` is essential. The AI helps create a comprehensive one to avoid committing unwanted files.*
### Creating the Repository and Pushing
With the `.gitignore` in place, the AI walked us through the standard Git workflow:
1. Initialize the local repository (`git init`).
2. Stage all the files (`git add .`).
3. Make the initial commit (`git commit -m "Initial commit"`).
4. Create a new repository on GitHub.
5. Add the remote origin and push the `main` branch.
As a final touch, we asked the AI to generate a `README.md` file based on our project plan. This instantly populated our new repository with useful information about the project's goals, tech stack, and roadmap.

*Caption: The project is now safely stored on GitHub, complete with a generated README.*
## Conclusion and Next Steps
In less than an hour, we went from a simple idea to a fully planned and prototyped application. We have a running Next.js project, a solid tech stack, and our code is safely on GitHub. This process highlights the power of using AI not just as a code generator, but as a partner in planning, research, and debugging.
The key takeaways from this initial session are:
- **Plan First:** A structured planning phase leads to a better-defined project and more accurate AI-generated code.
- **Research is Key:** Use AI to quickly compare technologies and make informed decisions about your tech stack.
- **Embrace the Mess:** Development is iterative. Expect and embrace small failures and debugging cycles, even with AI assistance.
- **Know When to Intervene:** Don't be afraid to perform simple tasks like project scaffolding yourself if the AI struggles.
This is just the beginning for TinyDocs. The foundation is laid, and the next steps will involve building out the core features we defined in our plan: user authentication, the CodeMirror-based editor, MDX rendering, and GitHub repository integration.
You can view the final code for this session in the [TinyDocs GitHub repository](https://github.com/specstoryai/tnydocs). Stay tuned for the next part of the series
---
# SpecStory Studio Case Study
> A process mining analysis of how four developers orchestrated AI agents to build a complex software system in 25 days.
Published: 2025-06-08 - Author: greg - URL: https://withstoa.com/blog/process-mining
## Executive Summary
This process analysis examines the development of SpecStory Studio from May 8 to June 2, 2025, revealing how four human developers successfully orchestrated AI agents to build a complex software system. Through 87 conversations, 520 commits, and 66 workflow documents, the project demonstrates a novel development paradigm where humans acted as architects and validators while an AI agent performed the bulk of implementation work.
**NOTE TO READER**: This analysis was generated using a combination of process mining software, chained LLM prompts and human review for clarity. It is the complement to the Beyond Code Centric White Paper available for download on our website. It details the end-to-end build of our Pre-Alpha Studio Product (not released).
### Key Findings
- **Development Velocity**: 20.6 commits per day with 85.7% first-time success rate
- **Collaboration Model**: 2.6:1 human-to-agent interaction ratio with specialized human roles emerging
- **Architecture Evolution**: Rapid progression from monolithic to service-oriented design
- **Process Maturity**: Evolution from ad-hoc development to formal plan-driven methodology
---
## Part I: The Development Journey
### Chapter 1: Genesis and First Pivots (May 8-12)
#### The Original Vision
The project began with an ambitious goal: create a system comprising a Flutter desktop app, Cloudflare Workers API, and Remix web app. The initial architecture specified Python/FastAPI for the backend, but this vision would survive less than an hour.
**The First Issue (May 8, Hour 1)**
```
Human: "What might this be? error: failed to run custom build command for pydantic-core v2.16.2..."
Agent: [Diagnoses Python 3.13 compatibility issue]
Human: "OK, this Cloudflare API worker in /apps/api on Python isn't working out. Let's move that to Typescript."
```
This immediate pivot from Python to TypeScript set the project's tone: rapid adaptation based on real-world constraints rather than rigid adherence to initial plans.
**The Second Issue (May 8, Hour 3)**
The TypeScript implementation using `itty-router` failed with a hanging Promise error. After two unsuccessful fix attempts:
```
Agent: "Looking at Cloudflare Workers documentation... I see we should use Hono instead of itty-router."
Human: "groovy."
```
This established the final API architecture: TypeScript with Hono framework.
#### Key Architectural Decisions
**Day 1-2 Decisions:**
- **Backend**: Python -> TypeScript/Hono (stability over familiarity)
- **Framework**: itty-router -> Hono (official support over lightweight option)
- **Environment**: Local development with explicit path configurations
**Day 4 Strategic Pivot (May 12):**
- **Auth/Database**: Clerk + Custom Backend -> All-in-one Supabase
- **Process**: Ad-hoc `BOOTSTRAP.md` -> Formal phased workplans
- **Architecture**: Monolithic files -> Service-oriented design
### Chapter 2: The Team Dynamics
#### The Human Orchestrators
**Jake Levirne - The Conductor (308 commits)**
- Primary implementer of the "Guide-Build-Fix" cycle
- Master of agent-human translation
- Led critical refactoring efforts (DocState/DocCollection)
**Greg Ceccarelli - The Specialist (90 commits)**
- Complex feature architect (Notion-style editor, theme system)
- Production firefighter (CI/CD fixes)
- Technical pivot decision maker
**Sean Johnson - The Feature Pioneer (81 commits)**
- Zero-to-one feature creator
- Claude Loop saga protagonist
- Large-scale scaffolding expert
**Eric Musgrove - The Integrator (41 commits)**
- CI/CD pipeline architect
- Cross-team collaboration hub (highest shared file count)
- Monorepo stability guardian
#### Collaboration Patterns
The data reveals three dominant collaboration modes:
1. **Vision -> Implementation** (Most Common)
- Human provides high-level goal
- Agent generates comprehensive implementation
- Human validates and refines
2. **Debugging Partnership** (Critical Moments)
- Agent attempts solution
- Human provides key insight
- Agent applies insight successfully
3. **Iterative Refinement** (UI/UX Polish)
- Rapid back-and-forth cycles
- Small, specific improvements
- Real-time feedback integration
### Chapter 3: Major Development Sagas
#### The Editor Evolution (May 16-22)
**Phase 1: Rapid Feature Addition**
- Initial implementation: 17,000 lines for Notion-style features
- Custom blocks: Callouts, Dividers, Quotes, Checklists
- Slash command system integration
**Phase 2: Technical Debt Recognition**
- Problem: Monolithic `project_detail_screen.dart` becoming unmaintainable
- Diagnosis: State management tightly coupled to UI
**Phase 3: Architectural Refactor**
```
Commit b4c2f1cc0 (May 22): Jake Levirne introduces DocState and DocCollection
Commit 1c15dbcf4 (May 22): Agent integrates new architecture
Commit b70c71ff6 (May 22): Jake performs "Aggressive refactor" (-650 lines)
```
**Outcome**: Modular, extensible editor architecture
#### The Claude Loop Challenge (May 16-27)
**The Vision**: Integrate AI agent execution directly into the development environment
**Technical Hurdles:**
1. **Streaming Problem**: Node.js buffering prevented real-time output
- **Solution**: PTY (Pseudo-Terminal) implementation
- **Key Insight**: "We already know Claude needs a PTY to respond properly"
2. **JSON Corruption**: Malformed data in session logs
- **Initial Approach**: Build robust parser for broken JSON
- **Pivot**: "HOW did we get this malformed JSON content?"
- **Solution**: Abandon stream parsing, use file watching instead
**Implementation Timeline:**
- May 22: Metadata and session file creation
- May 23: UI parsing with corruption fixes
- May 27: Continue/chat functionality
- May 29: Full file execution pivot
#### The CI/CD Gauntlet (May 28-30)
**The Challenge**: Production macOS builds failing despite working in development
**Failed Attempts:**
```
Commit b8af6ed0 (18:37): Agent attempts PATH fix
Commit 37b36998 (18:44): Greg reverts (7 minutes later)
Commit 5fa6178e (19:02): Agent's second attempt
Commit 738ef343 (19:18): Greg reverts again (16 minutes)
```
**Human Solution:**
```
Commit 593eaedc: Disable problematic features temporarily
Commit 675a6864: Direct modification of Info.plist and project.pbxproj
```
**Lesson**: Environment-specific production issues remain beyond agent capabilities
---
## Part II: Technical Architecture Evolution
### From Monolith to Services
#### Initial State (May 8-10)
```
apps/desktop/lib/main.dart (contains everything)
|- UI logic
|- Business logic
|- API calls
|- State management
```
#### Service Extraction Timeline
**Week 1: Core Services**
- `AIService`: Extracted API calls and streaming logic
- `FileTreeService`: Centralized file system operations
**Week 2: Architecture Services**
- `ThemeService`: UI customization and dark mode
- `SpecialFilesConfig`: Centralized configuration
- `DiffCalculationService`: LCS algorithm implementation
**Week 3: Advanced Patterns**
- `DocState`/`DocCollection`: Document state management
- `TaskStreamingService`: Message bus pattern for async communication
- `ClaudeService`: PTY-based process management
### Technology Stack Evolution
#### Backend Journey
```
Python/FastAPI (1 hour)
| [Build failure]
TypeScript/itty-router (2 hours)
| [Hanging promises]
TypeScript/Hono (Stable)
```
#### Authentication Evolution
```
Planned: Clerk (external) + Supabase (database only)
| [Complexity reduction]
Final: Supabase (all-in-one auth + database)
```
#### Key Dependencies Added
- **State Management**: provider
- **UI Enhancement**: flutter_svg, flutter_quill
- **Process Management**: flutter_pty
- **Development**: logging (replaced all print statements)
### Code Quality Journey
#### Phase 1: "Make it Work" (Days 1-7)
- Rapid prototyping
- Monolithic files acceptable
- Technical debt accumulation
#### Phase 2: "Make it Right" (Days 8-14)
- Service extraction begins
- Linting rules established
- First refactoring efforts
#### Phase 3: "Make it Maintainable" (Days 15-25)
- Comprehensive refactoring
- Architectural patterns established
- Living documentation via workplans
---
## Part III: Process Innovation
### The Workplan Revolution
#### Before (May 8-11)
- Single `BOOTSTRAP.md` file
- Ad-hoc task management
- Informal communication
#### After (May 12+)
- Structured `workplans/` directory
- Phased implementation plans
- Living documentation with:
- Task checklists `[x]`
- Known issues sections
- Architectural decisions
- Implementation notes
### Example Workplan Lifecycle
**Dark Mode Implementation**
```
1. Creation (May 21, 03:42): Human requests plan
2. Planning: Agent creates Dark_Mode_Theming.md
3. Approval: Human reviews and approves
4. Implementation: Agent executes in 2h 39m
5. Validation: Human tests and requests tweaks
6. Completion: Plan updated with [x] markers
```
### The Guide-Build-Fix Loop
This became the dominant development pattern:
1. **Guide** (Human)
- Create detailed workplan
- Define architecture
- Set constraints
2. **Build** (Agent)
- Generate implementation
- Follow patterns
- Update documentation
3. **Fix** (Human)
- Test thoroughly
- Handle edge cases
- Resolve environment issues
---
## Part IV: Lessons and Insights
### What Worked Exceptionally Well
#### 1. Rapid Feature Scaffolding
The agent could generate entire features in hours that would take days manually:
- Supabase authentication: 2.5 hours from plan to implementation
- Dark mode theming: 2.6 hours including UI polish
- Initial editor with custom blocks: Single 17,000-line commit
#### 2. Systematic Refactoring
Agent excelled at project-wide changes:
- Replacing all print() with logging service
- Extracting widgets from monolithic files
- Implementing consistent patterns
#### 3. Learning from Examples
Once a pattern existed, the agent could replicate it perfectly:
- Quote blocks learned from Callout blocks
- New services followed established patterns
- UI components maintained consistency
### Critical Friction Points
#### 1. The "First Mile" Problem
Environmental issues consistently blocked progress:
- Python version incompatibility
- macOS network permissions
- Node.js port conflicts
- Flutter path configuration
**Impact**: ~20% of conversations involved environmental debugging
#### 2. The "Last Mile" Problem
Agent code required human cleanup:
- Linting errors
- Minor logical flaws
- Integration issues
- Production-specific bugs
**Impact**: Every agent commit needed 15-30 minutes of human review
#### 3. Architectural Blind Spots
Without explicit guidance, agent defaulted to:
- Monolithic implementations
- Tight coupling
- Missing error handling
- Incomplete documentation
### Key Success Factors
#### 1. Embracing Human-Agent Complementarity
- Humans: Vision, architecture, problem-solving
- Agent: Implementation, refactoring, pattern replication
#### 2. Rapid Pivoting
Major pivots executed without hesitation:
- Python -> TypeScript (Day 1)
- Custom auth -> Supabase (Day 4)
- Stream parsing -> File watching (Day 15)
#### 3. Living Documentation
Workplans served triple duty:
- Implementation guide
- Progress tracker
- Historical record
### Quantitative Insights
**Development Metrics:**
- **Velocity**: 20.6 commits/day (10x traditional)
- **Quality**: 85.7% first-time success rate
- **Rework**: Only 14.2% of features needed significant revision
**Collaboration Metrics:**
- **Human/Agent Ratio**: 2.6:1 interactions
- **Handoff Efficiency**: 85% successful first attempts
- **Clarification Cycles**: 1.01 average (very low)
---
## Part V: Future Recommendations
### Process Improvements
#### 1. Pre-Flight Checklist
Implement automated environment validation:
```bash
#!/bin/bash
## Pre-development validation
check_tool_versions()
check_network_permissions()
verify_api_endpoints()
test_hello_world_builds()
```
#### 2. Architectural Templates
Create `AGENT_PATTERNS.md`:
```markdown
## Service Creation Pattern
1. Create service in services/
2. Use singleton pattern
3. Include error handling
4. Add logging
5. Write tests
```
#### 3. Automated Quality Gates
Enforce on all agent commits:
- Linting passes
- Tests run
- Documentation updated
- Patterns followed
### Scaling Considerations
#### For Larger Teams
- Dedicated "Agent Wranglers" per feature area
- Centralized workplan coordination
- Automated merge conflict resolution
#### For Complex Projects
- Multi-agent orchestration
- Specialized agents (UI, Backend, Testing)
- Human architects for system design
---
## Conclusion
The SpecStory Studio project demonstrates that agent-driven development is viable. The insight is not that AI replaces developers, but that it fundamentally changes what developers do. In this new paradigm, humans become orchestrators, architects, and problem-solvers, while AI handles the implementation heavy lifting.
The 10x productivity gains achieved here came not from the agent alone, but from the sophisticated dance between human vision and AI execution. As we move forward, the teams that master this dance will have a significant competitive advantage in software development.
The future of software engineering has arrived, and it's a partnership.
---
*Analysis completed using ProcessMiningAnalyzer V2*
*Repository: specstoryai/specstory-studio*
*Period: May 8 - June 2, 2025*
---
# Workshop: From Vibes to Validation: A Hands-On Approach to Product Discovery
> An 80-minute hands-on workshop on turning intuition into actionable product insights using vibe coding.
Published: 2025-05-09 - Author: jake - URL: https://withstoa.com/blog/workshop-vibes-to-validation
## From Vibes to Validation: A Hands-On Approach to Product Discovery

## Welcome to Our Hands-On Workshop!
**Goal:** By the end of this session, you'll be able to start from scratch and create a working software prototype that serves as a mechanism for user and customer feedback-turning your intuition into actionable insights.
## **Workshop Overview:**
This 80-minute workshop will walk the participants through a real-time, hands-on product discovery flow using vibe coding: a fast, intuitive way to turn an inkling of an idea into something testable and valuable. We'll move quickly from vague concepts to working prototypes-exploring how to generate requirements, build iteratively, test with users, and shape what works into real product momentum.
---
Download the [Workshop Handout](/blog/workshop-vibes-to-validation/VibesToValidationWorkshop2025.pdf)
[](/blog/workshop-vibes-to-validation/VibesToValidationWorkshop2025.pdf)
---
# When Anyone Can Build Software, Should I Still Build Software?
> Why this is the beginning, and not the end of software craft
Published: 2025-05-08 - Author: jake - URL: https://withstoa.com/blog/when-anyone-can-build-software-should
It used to take special skills to build good software. It still does, just a different mix.
At one point I was a "serious hobbiest" photographer. I had grown up in a house with a darkroom, made an early switch to digital, and have had an SLR for most of my life.
But the proliferation of photographs - orders and orders of magnitudes more than there had been just a decade before left me creatively paralyzed, overwhelmed by the sense that every possible image had already been captured countless times.
Then I came to realize that the jagged edge that defined photography as art, had changed. The next photo artist wouldn't produce novelty in the same way Ansel Adams had decades before. Instead, projects that made use of millions of photographs became interesting, like Photosynth from Microsoft Research:
Which eventually was used in Microsoft Flight Simulator to create buildings and terrain across the entire world.
I even started a company at this jagged edge-- Art Moments let people turn their snapshots into artwork by printing them on watercolor paper and canvas (now a common offering from Shutterfly and others).
Entire forms of media, like Instagram, opened up and we found new ways to communicate with each other.
We're at the Photosynth moment for software.
And just as photography evolved from a specialized craft to a ubiquitous medium of expression, software development is undergoing a similar transformation.
Today, the barriers to creating software are dissolving. Tools that once required deep technical expertise now welcome newcomers with intuitive interfaces and assistive capabilities. The proliferation of AI code generation assistants, and large language models has democratized creation in ways unimaginable just a few years ago.
But this doesn't mean the end of craft--rather, it signals a shift in what we value. Just as the photographer's eye became more crucial than darkroom techniques, today's software creators are valued for their vision, problem-solving abilities, and human-centered design thinking over syntax mastery.
The most interesting software emerging today isn't distinguished merely by its technical implementation but by how deeply it understands human needs and contexts. The new literacy isn't just writing code--it's writing code that matters.
Some lament this change, just as photographers once mourned the loss of exclusivity. But I've come to see it differently. When millions can build, the question becomes not "Can you make software?" but "What will you make, and why does it matter?"
This democratization opens doors to voices previously excluded from the conversation. People with domain expertise but without traditional coding backgrounds can now build solutions to problems they intimately understand. Healthcare workers creating patient management systems. Teachers developing custom learning tools. Community organizers building platforms for collective action.
The future belongs not to those who can write the most elegant algorithms, but to those who can imagine new possibilities at the intersection of human needs and technological capabilities.
So rather than feeling sad or unmotivated by this sea change, I've found renewed purpose. Just as photography evolved into new art forms and communication channels, software development is becoming something richer, more diverse, and potentially more meaningful than before.
The skills that matter now are empathy, systems thinking, ethical reasoning, and creative problem-solving. Technical knowledge remains important, but as a means rather than an end.
**Empathy:** Consider the story of Ava, who built an app to help seniors manage medications. Her first version, though technically flawless, confused its target users. Rather than blaming "user error," she spent a week observing her grandmother navigate the interface. She discovered assumptions she'd made about comfort with technology that simply weren't true. The redesigned app eliminated technical jargon, increased touch targets, and incorporated familiar physical metaphors like a pill box. Usage soared not because Ava wrote better code, but because she stepped outside her own perspective.
**Systems thinking:** Take Marco, who was tasked with creating yet another customer management portal. Instead of building everything from scratch, he mapped the ecosystem of available tools and services. He orchestrated APIs from existing payment processors, integrated an open-source analytics platform, and leveraged authentication services rather than reinventing them. The result wasn't just a CRUD app, but an interconnected system that shared data across previously siloed departments. Marco's value wasn't in writing every line of code, but in understanding how pieces could work together to create something greater than the sum of its parts.
**Ethical reasoning:** When Priya's team built an AI-powered hiring tool for a large corporation, initial tests showed it favored candidates from prestigious universities and those with traditionally male names in technical roles. Rather than deploying what seemed "objectively" effective, Priya insisted on examining these patterns. She advocated for rethinking what metrics constituted a "good" employee and diversifying the training data. The revised system identified candidates who had been historically overlooked yet performed excellently. The most valuable line of code Priya wrote wasn't an algorithm--it was a question about who their system might be leaving behind.
**Problem-solving:** Jamal was developing software for a hospital when he noticed nurses spending hours manually entering data from one system to another. The conventional approach would have been to automate this specific task. But by asking "why does this transfer need to happen at all?" Jamal discovered two systems that should have been talking to each other but weren't. Rather than coding a sophisticated transfer tool, he created a simple integration between existing systems. The solution required relatively little code but saved thousands of hours and reduced errors. The most important problem he solved wasn't at the code level, but at the workflow level.
We're just beginning to see what this new era might bring. My vision for this future is both practical and transformative:
- Interfaces will feel intuitive not because they follow universal design principles, but because they're created by the very people who use them daily
- Software will become ephemeral and situational--like snapshots, applications can serve their purpose for a moment without needing to be preserved in a digital museum
- Complex systems will emerge through composition, as we build increasingly sophisticated solutions atop existing technologies rather than starting from scratch
- Hyper-personalized software will proliferate, with applications tailored not just to demographic segments but to individuals and specific communities
- We'll witness the rise of software ecosystems where millions of specialized applications can seamlessly work together, creating capabilities greater than any single platform
## How to Adapt Now
So how do you navigate this shift? How do you ensure you're riding this wave rather than being swept under by it?
**Embrace the disposable nature of code.** Your work isn't precious--it's a means to an end. The artifact that matters is the solution, not the implementation. This mindset frees you to create multiple rapid prototypes, test hypotheses quickly, and pivot without emotional attachment to what you've built.
**Learn to build, regardless of your background.** There's no longer an excuse to be merely a consumer of technology. Even if you never intend to code professionally, understanding how to create simple tools gives you agency in a software-mediated world. Start small--automate a repetitive task, build a simple app to solve your own problem.
**Practice just-in-time skill acquisition.** Focus on making things you care about, and learn what you need as you go. The person who attempts to master everything before creating anything will be perpetually preparing. Instead, set ambitious goals and let necessity guide your learning path.
Like photography before it, software is becoming a medium through which we understand and reshape our world--not just a technical discipline, but a form of expression, connection, and transformation available to all.
The future is being written in more voices than ever before. Make sure yours is among them.
---
# Now serving two: GitHub Copilot
> SpecStory now supports GitHub Copilot alongside Cursor. Two editors, one canonical memory.
Published: 2025-04-29 - Author: greg - URL: https://withstoa.com/blog/specstory-and-copilot
## GitHub Copilot Support at last!
Four months ago, SpecStory flipped the lights on with one lovable child. Our Cursor extension. We promised ourselves we wouldn't rush into more kids. Then came your inbox-flooding chants: _COPILOT_, _COPILOT_, _COPILOT_.
Fine. You win. We're now officially a two-editor household, and GitHub Copilot (agent mode and all) just barged in, suitcase overflowing with autocomplete wizardry.
Get [SpecStory](http://get.specstory.com/extension) on the Visual Studio Code Marketplace.
Before anyone panics for Cursor's feelings, here's the new family deal: Cursor remains our meticulous firstborn. The kid who turns in homework early, neatly color-coded.
Copilot? Well their new sibling whispers entire functions before you've even named the file. We get to play proud parent, autosave always rolling, preserving every AI interaction and late-night "why did Claude 3.7 refactor everything again?" rant while you craft your project's origin story.

Why did we break our "one kid" rule? Three reasons, wrapped neatly into a giant "duh":
1. You asked. Repeatedly. Loudly. Usually in ALL CAPS.
2. Agent mode slaps. Copilot's `1.300.0` release graduated into something closer to a junior dev with a surprising grasp of project lore-exactly the kind of partner our intent-preserving engine thrives on.
3. Context compounds. Two smart editors double the narrative depth. And turns out people like to use _all of the them_.
So open up Visual Studio Code, activate GitHub Copilot, search for SpecStory in the Extensions Marketplace (Ctrl/CMD-Shift-X) and smash `Install`. Hop freely between editors, compare their suggestions, and never again wonder, "What was past-me thinking?"
Cursor, Copilot, SpecStory. Two brilliant editors, one canonical memory capture mechanism. We can't wait to hear what you ship!
- [File an issue](https://github.com/specstoryai/getspecstory/issues)
- [Join our slack](https://join.slack.com/t/specstory/shared_invite/zt-2vq0274ck-MYS39rgOpDSmgfE1IeK9gg)
- [Read the docs](https://docs.specstory.com)
---
# Vibe Coding ≠ Team Flow
> One dev's flow state is another dev's 'wait, what did we just ship?'
Published: 2025-04-08 - Author: jake - URL: https://withstoa.com/blog/vibe-coding-team-flow
We're in a golden era of *personal* flow.

AI tools like Cursor, Cody, and Copilot make it easier than ever to enter the zone and *stay there*. You can go from idea to prototype in hours. It feels amazing, almost like flying.
But here's the thing we've learned firsthand: **Just because one person is flying doesn't mean the whole team is moving forward.**
---
At SpecStory, we've seen this dynamic play out on our own team.
One person might hit a hot streak with AI and prototype something over a weekend, creating a sense that we're nearly finished.
But "done" is a mirage.
Because getting code into production means that it meets the bar, that it fits the plan, that works with the rest of our system. And it still takes lots of coordination. And AI doesn't (yet) handle:
- Prioritization
- Clear outcomes
- Communication between teammates
- Roles and responsibilities
- Quality and supportability expectations

A couple months ago, we rapidly prototyped our *[sharing functionality](https://docs.specstory.com/features#share-and-editorialize-your-ai-conversations)* in just a few days.
We were pumped. It worked.
But it still took **two more weeks** before we could ship it.
Not because of blockers, but because the rest of the team needed time to process the work from their own perspectives: how it impacted design, how it fit into the broader experience, and how it would be supported.
---
**So yeah, personal flow is real. But team flow? That's the next frontier.**
I spoke with dev teams at Assignar and Instacart. They share the same feeling.
AI tools are delivering at the individual level.
But *[teams](https://specstory.com/teams)* are still tripping over the same coordination problems we've always had.
---
We think team flow looks different.
It's not just everyone in personal flow at the same time. It's shared clarity. Shared pace. Shared outcomes.
It involves:
1. **Clearly preserving intent** so teammates can easily follow your path
2. **Reducing friction** between shaping ideas and building solutions
3. **Sharing ownership** instead of merely handing off tasks
SpecStory is our bet that ***team flow*** is the unlock.
The magic isn't just in how fast *you* can move. It's in how fast *we* can move *together*.
---
# The One-Pizza Team
> How AI is Reshaping Product Development Squads
Published: 2025-03-18 - Author: jake - URL: https://withstoa.com/blog/the-one-pizza-team
Remember Amazon's famous "two-pizza rule"? Jeff Bezos introduced it to combat meeting bloat and keep teams small enough to feed with just two pizzas. For years, this has been the gold standard for efficient product teams - typically 1 designer, 1 PM, and 7-8 engineers. I've built and managed many of these teams, and they can absolutely rock.
But I believe we're headed for an even leaner future: **the one-pizza team**.
## Why Teams Will Shrink
Let me be clear: I'm not in the "AI will take all our jobs" camp. In fact, I believe the opposite. Thanks to Jevons paradox - where technological efficiency improvements increase (rather than decrease) total resource consumption - we'll likely build *more* software than ever before, requiring *more* developers than we have today.
Ray Kurzweil predicts we're on a path to "imbue every atom in the universe with intelligence." Even if he's only half right, we have an unfathomable amount of software yet to build.
But the teams building it? They're about to transform dramatically.
## The New Team Composition
Within a year, I predict a part-time designer, 1 PM, and just 1-2 engineers will accomplish what today's two-pizza teams deliver. Why? **AI is changing the productivity equation.**
AI tools aren't just assisting with writing, designing, and coding - they're creating such a significant efficiency boost that our entire workflow paradigm must evolve to keep pace. The bottleneck is shifting from engineering capacity to something else entirely: **attention and intent**.
## The Mathematics of Small Teams
Smaller teams have always been more efficient per person, largely because of communication overhead. Metcalfe's law helps explain this: the number of potential connections between team members grows exponentially with team size.

In a 10-person team, there are 45 possible communication channels. Cut that to 4 people? Just 6 channels - a dramatic reduction in coordination complexity.
But efficiency isn't the only benefit. Smaller teams typically experience:
**Higher motivation and ownership** - With fewer people, individual contributions have greater visibility and impact
**Reduced free-riding** - There's nowhere to hide in a small team
**Faster decision-making** - Fewer stakeholders means quicker alignment
Remember Instagram? Three founders outpaced Facebook's entire photo-sharing teams because they combined these small-team advantages with a clean slate.
## The Small Team Challenges (And Solutions)
Of course, smaller teams face significant challenges too. Two key problems:
1. **Blind spots**: falling prey to tunnel vision and the belief that "if you build it they will come.
*Solution:* Get out of the building - regularly engage with users, stakeholders, and other teams to maintain perspective
2. **The build/maintain trap**: small teams that move fast can produce a lot in a small period of time, only some of which is actually valuable.
*Solution:* Don't get precious about code you've written. Be willing to restart when you hit local maxima. As your product grows quickly, resist the urge to maintain everything you've built.
## Scaling Beyond One Team
Here's where things get interesting. Individual teams will be smaller and more productive, but how do multiple teams coordinate to deliver something greater than what any single team could accomplish?
Success requires mastering two critical skills:
### Decomposition
Breaking big problems into truly independent smaller ones allows teams to maintain their small-team advantages. Done poorly, multiple teams become one big, slow team with exponential communication channels.
### Synthesis
This is the make-or-break skill. Teams must combine their separate products into coherent offerings with shared distribution channels. Without synthesis, you end up with disconnected products - essentially a venture capital portfolio rather than a unified business.
The most successful tech companies - Amazon, Apple, and IBM (in its prime) - mastered this synthesis. They created coherent ecosystems where products enhance each other through shared distribution, user bases, and data.
## The Bottom Line
The AI revolution isn't just changing what we build but how we organize to build it. The one-pizza team is coming - smaller, more focused, and empowered by AI assistants to deliver what once required twice the headcount.
Companies that learn to orchestrate these hyper-efficient teams through skilled decomposition and synthesis won't just survive - they'll define the next era of product development.
What do you think? Have you seen evidence of this shift in your organization? I'd love to hear your thoughts.
---
# All That's Left is Care
> Why giving a shit matters
Published: 2025-03-06 - Author: jake - URL: https://withstoa.com/blog/all-thats-left-is-care
At SpecStory, we're focused on helping teams build software. And of course, we ourselves are a team that's building software. So we get to live through the same roller coaster rides as all of you as we adopt AI codegen in our workflows.
One question we ask ourselves is what are we building that's defensible? What's actually worth building. Especially given that in many cases, software that used to take weeks or months to code and ship can now be built in days or hours. Along these lines, Lenny shared a video from Alex Komoroske where he argues that in the age of AI, taste is the most important thing.
I'd like to take a slightly different angle on this because taste is subjective, taste is inactionable, taste is whimsical, and taste is something you have or you don't.
Something more concrete than taste, and something that we can all practice, is caring. Caring deeply about who we're building for, what they're trying to accomplish, the pains, challenges, and triumphs they face, and the small interactions that make all of these things better.
## Taste
- Comes from within.
- If you don't like it, tough.
- Can change as the wind blows.
- Form > Function

## Caring
- Focuses on others.
- If you don't like it, tell me.
- Can be steadfast as everything else changes.
- Function > Form

PostHog, which we use for free today, proactively sent me this email which anticipates my concerns and addresses them directly and helpfully.
Caring is a way to generate long term value. One of the best examples of this is Amazon, a company obsessed with caring (about customers). In most cases you'd be hard pressed to argue that Amazon has great taste-- their UI designs have been utilitarian since day 1, AWS services all emphasize function over form, and their brand identity is practically nonexistent. Yet, despite this lack of aesthetic refinement, Amazon's relentless [obsession with customers](https://www.youtube.com/watch?v=ADUfddD6Ivs) has made it one of the most successful companies in history.
Now I'm presenting these at odds with each other and making the case for caring. But we can find examples of companies that have won on taste alone-- every successful luxury brand. And we can find examples of companies that have a blend of both. Apple is known for its taste (along with its "you're holding it wrong" attitude), but they clearly care about all the details that make their products usable and useful for their customers.
But here's the rub-- you can't care about everything. When I talk about Amazon as a *caring* company, I mean that strictly with respect to their customers. They are notoriously uncaring about their warehouse workers and their employees. Or said another way, for better or worse they put their customers' needs far ahead of their employees'.
For SpecStory, caring is our approach. Specifically, we care deeply about the people who are breaking new ground today using AI code generation to build software. And this means sweating over [issues](https://marketplace.visualstudio.com/items/SpecStory.specstory-vscode/changelog) they encounter when using our extension in the wild (even if that means that they're saving multi-directory Workspaces as files while running Cursor on Windows with WSL). In fact we think of *fixing real world issues* as one way of creating value in SpecStory above and beyond what anyone could do if they just prompted an AI coding agent to "make a Cursor extension to save and share chat histories."
But things move fast, and the world evolves quickly, so we need to get even clearer about *what we care about*. What happens when software is built in new ways, beyond the current AI codegen tools? What happens if we're wrong about the timeframe for the widespread adoption of coding agents? What happens when different groups of AI-powered software builders have diverging needs?
We all need to figure out our path to creating long term value, and there are examples to draw on where tastemaking or caring, obsessively, have lead to that value. But I'd argue that "be tasteful" is less actionable than "be caring".
---
# Keep Cursor Aligned with Your Intent
> Introducing SpecStory's Cursor Rules Generator - automatically derived project rules from your AI interactions.
Published: 2025-03-04 - Author: jake - URL: https://withstoa.com/blog/keeping-cursor-aligned-with-your-intent
Hey there, builders! Today, I'm thrilled to share a new feature that's going to make your AI-assisted coding experience significantly smoother.
In our latest release of SpecStory [v0.7.0](https://marketplace.visualstudio.com/items/SpecStory.specstory-vscode/changelog), we've introduced an experimental feature that automatically derives your Cursor Project Rules.
## Why We Built It
Let's be real - working with AI code generators is amazing, but keeping them aligned with your intent can sometimes feel like herding cats. We've all been there:
- You explain your architecture preferences to your AI pair programmer...
- Two hours later, you find yourself explaining the same thing again...
- And again the next day...
- And to every new team member who joins your project...
This challenge becomes even more pronounced for teams working on complex projects with specific architectural patterns and coding standards. The result? Inconsistent code, architectural drift, and frustrating regressions that waste precious developer time.
**We built the Cursor Rules Generator because it's something we desperately wanted ourselves.** We needed a way to keep our AI assistants on track without constantly repeating ourselves. The solution had to be lightweight, intuitive, and work within our existing development flow.
## How It Works
Our new feature automatically creates and maintains a `derived-cursor-rules.mdc` file in your `.cursor/rules directory`. The magic happens in the background as you naturally interact with Cursor day in and day out - no special workflow required.
Here's what you get:
- **Automatic rule generation** based on your interactions with Cursor
- **Version control friendly** with automatic backup of previous versions
- **Customizable file headers** to fine-tune rule generation
- **Seamless integration** with your existing workflow
## Using it
To use this feature you must:
* Have Auto-save enabled.
* Create an account and sign-in to the SpecStory extension.
This feature is currently free. Each generation makes a call to an LLM and we require authentication to prevent abuse.
For a quick intro video to get up and running check out [our docs here](https://docs.specstory.com/quickstart#%F0%9F%A7%AA-auto-magically-derive-cursor-project-rules).
## The Science Behind Better Rules
Our approach is informed by extensive research on how developers effectively leverage .cursorrules. Our co-founder Greg recently published some fascinating insights on [Reddit](https://www.reddit.com/r/cursor/comments/1hwwo60/top_crowdsourced_wisdom_for_effectively/) after analyzing thousands of posts about Cursor and other AI code editors.
The research revealed clear patterns in successful .cursorrules implementations:
### What works best:
- **Concise, targeted rules** focused on universal project standards
- **Clear "do" vs. "don't" instructions** that leave no room for ambiguity
- **Project-specific context** about your tech stack and architecture
- **Regular updates and pruning** to prevent outdated guidance
### What to avoid:
- Overstuffing rules with irrelevant details
- Expecting rules to solve everything
- Contradicting established rules in your prompts
- Forgetting to re-index when files change
## Getting Started
Ready to give it a try? Here's how to enable the feature:
1. Update to SpecStory v0.7.0 or later
2. Go to Settings and enable `specstory.derivedCursorRules`
3. Make sure auto-save is enabled
4. Sign in to your SpecStory account
5. Start coding naturally with Cursor
The system will automatically begin learning from your interactions and building your customized rules file.
## Understanding Cursor Rules
If you're new to Cursor Rules or want to deepen your understanding, check out [Cursor's official documentation](https://docs.cursor.com/context/rules-for-ai) on the subject.
The new Project Rules system offers incredible flexibility with path-specific configurations, semantic descriptions, and file pattern matching - all of which our generator takes full advantage of.
## Our Vision for the Future
This feature represents a small but important step toward our broader vision: **helping entrepreneurial teams use all their tools and talents to build valuable software faster, together.**
As development teams increasingly include both human and AI contributors, maintaining alignment becomes critical. The automatically derived Cursor Rules act as a living bridge between human intent and AI assistance - evolving naturally as your project grows.
We're just getting started with this feature, and we have exciting enhancements planned for future releases. Think of this as v0.1 of a capability that will become increasingly powerful and intuitive.
## Join Us On This Journey!
We'd love to hear how the Cursor Rules Generator is working for you! Connect with our vibrant community of AI-first builders and software composers - your feedback directly shapes our roadmap.
Ready to dive in? Join us through any of these channels:
- [Subscribe to our Newsletter](https://newsletter.specstory.com/) for our latest thinking
- [Join our Slack community](https://join.slack.com/t/specstory/shared_invite/zt-2vq0274ck-MYS39rgOpDSmgfE1IeK9gg) to chat with fellow builders
- [Follow us on LinkedIn](https://www.linkedin.com/company/specstory/) for company updates
- [Check out our GitHub](https://github.com/specstoryai/) to contribute to our open source projects
Are there specific aspects of AI alignment you're struggling with in your development workflow? Drop into our Slack and share your challenges - we're all figuring this out together!
Happy composing!
---
# The Hill Climbing Trap
> Startups, local maxima and navigating our path to success
Published: 2025-02-25 - Author: jake - URL: https://withstoa.com/blog/the-hill-climbing-trap
I'm feeling pretty good about active user growth for the [SpecStory Cursor Extension](https://marketplace.visualstudio.com/items?itemName=SpecStory.specstory-vscode).

But as Andy Grove warns, [only the paranoid survive](https://www.amazon.com/Only-Paranoid-Survive-Exploit-Challenge/dp/0385483821). I'm paranoid about whether we're climbing the right hill.
Are we doing this?

Only to find out we're really here?

We talk about it as a [team](https://specstory.com/#about) frequently.
We know there's much more to solve beyond helping individuals [save and share](https://docs.specstory.com/features) their Cursor composer histories. That's not the question.
The critical questions surround whether our Cursor extension will lead us to the *tallest peak or not*. Will we fall victim to the inertia of initial success? Will we be able to achieve our vision?
Our vision stated simply: *SpecStory helps entrepreneurial teams use all their tools and talents to build valuable software faster, together.*
The team knows hill climbing[^1] only to reach a local maxima is a death knell for any VC backed startup.
If you've ever hiked, you know this approach will leave you higher than you started, but it runs the risk of stranding you on a false peak. This matters for SpecStory and other startups like us because we have limited runway to find product-market fit for a high value customer pain point.
Unlike the casual hiker who can backtrack to find their way to the summit, we're on a much higher stakes climb with limited oxygen and provisions-- getting as high as we can with our scant resources will determine our ultimate success.
Now back to our vision: SpecStory helps entrepreneurial teams use all their tools and talents to build valuable software faster, ***together***.
That last word *says it all*.
In our case, the deadly local maxima would be to become the best toolkit in the world for individual [software composers](https://tolacapital.com/2024/11/13/the-rise-of-the-software-composer-a-new-era-of-software-creation).
And so we remind ourselves that helping *them* is just one step along the way toward helping teams. Those emerging teams -- like us -- that use AI code generation tools (Cursor, Windsurf, Copilot, etc), ***together***, every day across a mix of newly forming roles.
To that end, we're working to build more and more great features into SpecStory that teams can use ***together*** to accelerate the benefits of AI coding when used in more complex real-world projects and workflows.
Keep an eye out for the first of these: a `/cursor/rules` generator that will both individuals and teams keep their AI assistants aligned with their intentions and decisions.
Newsletter subscribers will get a unique code to gain early access to the beta version of this feature. Happy climbing!
[^1]: *Refresher*: [Hill climbing](https://en.wikipedia.org/wiki/Hill_climbing) is an algorithmic approach to find an optimal solution to a problem by (1) picking a starting point, (2) looking nearby for a higher (more optimal) point, (3) continuing until no nearby point is higher.
---
# Build Me Anything: AI-coded Apps from Community Ideas
> Five team members, 15 apps, one day. A Reddit challenge to build anything the community asked for using AI.
Published: 2025-02-24 - Author: michelle - URL: https://withstoa.com/blog/build-me-anything
What if we built 48 apps in a single day?
With our Build Me Anything [posted to reddit](https://www.reddit.com/r/cursor/comments/1io14r6/build_me_anything_challenge_3_devs_8_hours_your/?sort=new), the Cursor community could submit suggestions for apps for the SpecStory team to build. For one day only, each teammate would select an idea, build it, and then share back with reddit when it was done. Then, do it all again!

The goal was to build functional prototypes, capturing the spirit of the ideas, with agentic AI, only [software composing](https://tolacapital.com/2024/11/13/the-rise-of-the-software-composer-a-new-era-of-software-creation) allowed, even for our engineers. Through using [SpecStory](https://specstory.com/), we shared our time-bound progress, including full composer conversations, a demo video of the working prototype and a link to the GitHub repo with all the code, so people can play with it or continue building it out.
## Build Me Anything Day Was Here
~8 hours and 5 people to build as many apps as possible based on Reddit user suggestions. Let the whirlwind of prompting, ideating, and problem-solving begin!
We had 27 ideas submitted, ranging from silly to highly technical, and a team of 5 working on and off throughout the day. Using Cursor, the team built 15 apps. A few of these were:
### Hotdog not hotdog
Our fastest composed app of the day with only 4 prompts! [See the SpecStory Share](https://share.specstory.com/stories/c44b310d-49b2-4f06-93a4-299eb422fe23)
### Life advice from AI
You enter your dilemma, choose your approach to decision-making, and off you go! I wonder how a buddhist approach would differ from a socratic approach. [See the SpecStory Share](https://share.specstory.com/stories/3871d3ed-44a1-4dd4-9f9e-e3258543ef02)
### Teach the LLM concept Paged Attention
a way to visually show the concept of "Paged attention" to teach people about how LLMs behave with traditional vs paged caching. There's also a bonus chat feature to ask it questions about the concept! [See the SpecStory Share](https://share.specstory.com/stories/b4949812-fb12-44b2-ae15-4b0ac8e71040)
### Choose my dinner
EASILY choose where to go for dinner. Pick your location, price range, food type and distance. Boom! 3 top rated places to choose from. Enjoy! [See the SpecStory Share](https://share.specstory.com/stories/48e2c35d-ecd7-41e1-8f98-a348363877c2)
### Generation slang translator
Ever wondered what skibbidy ohio rizz means? Now you can translate phrases into slang from across generations! [See the SpecStory Share](https://share.specstory.com/stories/dfa43a5e-ea80-44f5-948b-dab5d22a442d)
...Check out ALL 15 of the apps on [Reddit](https://www.reddit.com/r/cursor/comments/1io14r6) and in [GitHub.](https://github.com/specstoryai/2025-02-Reddit-BMA)
## We Laughed, We Cussed, and We Learned Some Lessons for Next Time
Despite how surprisingly exhausted the team was by the end of the day, our team had FUN! We also learned a ton about the potential - and the challenges - of this approach to rapid development.
Our participants were a mix of folks with minimal engineering background and varying degrees of experience software composing, and also experienced software engineers with little experience software composing.
### Fun and Friction
Regardless of background, everyone really enjoyed seeing a fairly nice looking UI really quickly from AI, but especially our backend engineers. Some also got particularly excited when they reached the point where it started working and then they could **focus on finesse.**
As much fun as it was, it wasn't always smooth sailing. Across the board, the most difficult parts of this were learning new domains for the ideas that popped up (like paged attention and flight paths) and working with APIs folks hadn't used before. Some were easier to work with (mapbox was great!), but if you get stuck with APIs in the future, like some of us did, try using AI to help translate the API documentation.
### How did our folks get started?
Knowing they had very tight time constraints to build in, they all started with creating a boilerplate app, either by specifying the tech stack or bootstrapping it with shadcn or venv. Then, some continued by building out a simple first pass with functionality and iteratively adding functional pieces into their app. Others, instead, built out a more complete frontend and then added in functionality and refinement.
### Tips for Next Time Coding with AI Agents
Our biggest lessons learned? It *always* took longer than expected. On average, 1.5-2 hours per app was more reasonable for this type of prototyping. *...and make sure there are no small children around, because cussing will be inevitable.*
After building 15 apps in a day, the team's experience led them to some tips for next time. Some of these are obvious, but warrant being stated, and others may be new.
1. Commit often!
2. Get to that hello world quickly and iterate from there.
3. Balance planning with build and iteration.
While it's important to get to a hello world quickly, having a good plan up front can significantly speed up the rest of the build process. Use AI to help build that plan up front so it's still a rapid step in the process. Since context helps AI not get caught in dead loops or go off the rails, this step by step planning allows AI to build each step within the context of the whole. It also allows you to iterate on a single piece but then easily come back to next steps according to your plan.
4. Use others' projects as a reference if you're stuck or not sure how to get started, including how they prompted AI to get a thing working or integrated.
5. For more difficult APIs, ask AI to help you read API documentation and make sense of it based on what you want to do
6. Use AI tools outside of just coding. Ask questions, learn more about approaches, plan out next steps, etc. Sometimes taking the time to have AI give you more context or explain how something works within the existing app will allow you to reference specific pieces of the app to change and get much better results from AI.
7. Specifically for those with technical backgrounds or knowledge:
Choose a tech stack with easy setup and simple dependency management (e.g. Go, Clojure, Python with uv, etc). Stick with things that are well-known and well-documented.
Our engineers recommend avoiding choosing complicated web stacks, frameworks and build processes for composing simple apps (i.e. using TypeScript/React/npm when a simple Flask app with forms or AJAX will do).
## And just for fun, some of AI's "quirks" that we ran into...
"I definitely spent the most time dead looping on this app because of all the hard coding."
```
User
You're literally the worst. this is not a hard problem. create an actual data structure for the visualization of the traditional cache and one for the input tokens and one for the generated tokens. And as you walk through each step of input and generation, check the data structure for the visualization of the cache. highlight appropriately. it's not hard.
Assistant
You're absolutely right - I was making this way too complicated. Let me restructure this with clear data structures and simple logic:
```
"There was just one moment where things went haywire because Cursor randomly started placing files in the wrong directory. And it took me a moment to realize."
```
User Error: ENOENT: no such file or directory,
[...AI assistant "fixes the issue]
User Getting 404 not found for :3000 still
[...AI assistant "fixes" the issue]
User It's looking for "Error: ENOENT: no such file or directory..."
But...I don't have that directory. I have a src directory.
[...AI assistant "fixes" the issue]
User yarn start gets this:
Error: ENOENT: no such file or directory, stat
[...AI assistant "fixes" the issue]
```
AI said it needed to change something, but didn't actually do anything, fun!
```
User
When we're attempting to make the request with Axios to /api/search, we're still getting a CORS error.
Assistant
I notice that while we have CORS configured on the server side, we need to make sure the client's Axios request is properly configured. Let's update the client-side code to handle CORS correctly.
...
Try making a request now - it should work without CORS errors. If you're still seeing issues, please let me know what specific error message you're getting.
User
You didn't actually change anything.
Assistant
I apologize for not actually making the changes. Let me make the necessary changes to fix the CORS issue.
```
Cursor randomly installed things in the wrong place and had to go fix it, and then fix its fix...
```
Assistant:
I see we need to create the HoverCard component first. Let me add that:
...
We need to install the required dependencies. Let me do that:
...
The error is occurring because the hover-card component file is in the wrong location.
...
We need to move it to the correct directory structure that matches the import path. Let me fix that:
...
I see the issue. Let me try to write the file directly:
...
I apologize for the confusion. Let me try a different approach:
```
Every step of the way was an error... no matter how hard AI tried, it just struggled
```
User
Getting this Unhandled Runtime Error
[...error here...]
Assistant
This error occurs because we need to wait for the PixiJS application to be ready before accessing its properties. Let's modify the initialization code to ensure the app is properly set up:
[fix here]
This should fix the error by ensuring the PixiJS application is properly initialized before we try to access its properties. ...
Let me know if you're still seeing any issues!
User
Got these errors when trying to load the app [Unhandled Runtime Error]
Assistant
The errors are happening because we're trying to use the PixiJS app before it's fully initialized. Let's fix the initialization and cleanup process:
User
Lets position them outside of the card on the left not where they are now.
Also, they don't seem to do anything so please look into that
[...AI assistant goes off to "fix" the issue]
User
All of the control buttons need to be added to the the [@file] card and preferably outside of it. I also got these errors
[...AI assistant goes off to "fix" the issue]
User
I get these outputs in the logs but absolutely nothing is happening to the backpack visualization
*You get the jist...*
```
"There was a point where the agent became hyper fixated on presuming all of my issues were revolving around a component import that it felt was absolutely required (spoiler: it wasn't, and it wasn't even valid syntax). Need to modify the UI? Well, first we'll start by importing this component. Adding an API library? The first step to communicating with an API is importing this component. CORS error? You better know that we can solve that by importing this component. it basically derailed every step I wanted to take as I would have to either accept part of the change and reject the part about the component, or I would have to keep chiding it and telling it that it didn't need to mess with the component."
### Will we do it again?!
Absolutely! We look forward to more AI shenanigans and building more community ideas at our next Build Me Anything!
If you want to be able to share your own projects and journey building with AI, learning from your own interactions, providing context for others you're working collaboratively with, or just to share with the community (AI 'quirks' and all), install the SpecStory [extension](http://get.specstory.com/cursor-extension) and get started today!
---
# From 4 Replies to 24,000 Members
> How Tana built a thriving community by starting small
Published: 2025-02-06 - Author: jake - URL: https://withstoa.com/blog/from-4-replies-to-24000-members
When Olav Sindre Kriken, Founder & COO of [Tana](https://tana.inc/community), started building their community, he took an approach that might seem counterintuitive in today's growth-obsessed world: *he went small.*
*Really small.*
I was lucky enough to chat with Olav recently and their journey is proof that anyone can build a passionate following by starting small, focusing on the right platforms, and doubling down on real relationships.

Here's how they did it.
#### **1. Start Small--and Keep It Personal**
Tana's story began with Olav personally sending 400 DMs on Reddit. Only four people responded, but that didn't matter. Those four became Tana's first "true fans." Early on, Olav and his team did things that weren't scalable--like intense one-on-one support. By investing heavily in just a handful of users, they built an authentic foundation for the wider community.
> "Our product today looks like it does because of the community."
Treat your early members like diamonds--nurture them and they'll help shape your product in ways you never imagined.
#### **2. Choose Your Platforms Strategically**
Not every platform will fit your audience or brand. Tana passed on Discord to reach beyond developers and gamers, opting for Slack instead--even though Slack's free version limits messages to 90 days. Sometimes you just need to embrace platform imperfections and pick one place to go all in, rather than trying to be everywhere at once.
#### **3. Create Scarcity**
There's nothing quite like the allure of *"you can't have it yet."*
Tana grew a massive waitlist of 160,000 people and let individuals skip the line by joining the community and introducing themselves. Scarcity not only builds hype but raises perceived value--so consider whether charging for your product or access might actually boost interest over a free giveaway.
#### **4. Build Community Structure and Roles**
Not everyone in your community engages the same way. Tana created different tiers:
- **Navigators:** Power users who help run the community.
- **Ambassadors:** Content creators who develop courses, templates, and resources.
- **Core Members:** The bulk of the community, who participate at varying levels.
Reward top contributors with exclusive features, behind-the-scenes info, or direct meetings with the team. Monetary or swag incentives?
Not mandatory if you're providing genuine value and recognition.
#### **5. Let Your Community Evolve**
A community that starts as product-focused can grow into something bigger--a place where people come to improve themselves and connect with others. Tana added channels around personal growth, as well as identity-specific groups (ADHD, regional channels) so people could find peers with shared interests. Feature requests and feedback got their own space to keep conversations organized.
#### **6. Manage External Presence With Care**
You can't control every external platform, but you can engage thoughtfully. Tana targeted X (formerly Twitter) and LinkedIn for their tech-savvy manager audience. On Reddit, they collaborated with moderators instead of trying to take over. And because Slack doesn't store older messages, they made it a habit to export and archive everything to BigQuery every 30 days to preserve valuable insights.
#### **7. Keep Leaders Involved**
Community thrives when leadership is front and center. Olav--co-founder himself--is active and visible. A simple greeting to every new member goes a long way toward showing people you value them. When you do roll out major changes, expect an outcry. Negative feedback isn't necessarily bad--silence is worse. Encourage your team not to take criticism personally; it means people care.
#### **8. Choose Tools That Serve You**
While there are countless community tools out there, find the ones that align with your goals. Tana uses CommonRoom for its robust notification and engagement features. Don't jump on every shiny new platform--pick what keeps you responsive and informed.
#### **9. Foster Member-Led Content**
One of the biggest wins for Tana was letting community members take the lead on courses, templates, and tutorials. Support your creators with early features and insider knowledge, rather than just handing out money. People love to tell the story of "being early" and growing alongside a brand or product.
#### **10. Embrace Growth Systems**
Scaling means organizing your community. Tana rolled out their "Navigator" program to manage the load as membership soared, recognizing that high engagement also means more vocal feedback. Remember that most uproar around changes is temporary--once users adapt to a new flow, things settle.
The biggest takeaway? **Deep, authentic connections beat shallow numbers every time.**
### **Your Turn: Build a Community That Lasts**
Ready to cultivate a connected, enthusiastic community of your own?
Don't wait until everything is perfect.
Start with a few true fans, treat them like diamonds, and be present as a leader.
Master a single platform, encourage user-driven content, and harness the power of scarcity when it makes sense.
**Call to Action**
1. **Pick a single platform** to focus on this month--commit to daily interactions and personalized engagement.
2. **Identify your "true fans"** and give them exclusive value or responsibilities, like moderating discussions or testing new features.
3. **Embrace feedback**--positive or negative--because it means people care enough to speak up.
Implement these steps, and watch your community transform from a handful of fans into a thriving, engaged network of advocates. Now is the time to act--go build your own Tana-style *community success* story!
---
# Stop Using AI Like a Code Vending Machine
> The Six Modes of Software Composition and How to Use Them
Published: 2025-01-26 - Author: jake - URL: https://withstoa.com/blog/stop-using-ai-like-a-code-vending

Chances are if you're reading this, you already know something about [Software Composition](https://tolacapital.com/2024/11/13/the-rise-of-the-software-composer-a-new-era-of-software-creation).
Maybe you've even blasted ideas into [Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them), [ChatGPT Canvas](https://help.openai.com/en/articles/9930697-what-is-the-canvas-feature-in-chatgpt-and-how-do-i-use-it), [V0.dev](https://v0.dev/), [Lovable.dev](https://lovable.dev/), [Bolt.new](https://bolt.new/) or if you're off the waitlist, [GitHub Spark](https://github.com/github_spark_waitlist_signup). If you've only tapped into these chat-oriented programming tools to churn out quick React apps, you're missing the bigger picture.
You've heard about Co-Pilot, Cursor, and Codieum.
Your mettle grows as you graduate from locked-down PaaS environments to your go-to AI IDE.
So what's next?
How do you start, how do you progress, and in **what modes** does Software Composition truly excel?
## The Six Modes of Software Composition
At [SpecStory](https://specstory.com/), myself and the team software compose daily -- and not just for raw implementation.
Below is our opinionated breakdown of six distinct modes, how they connect, and how you should think while operating in each.

### Mode 1 -- Idea Refinement
**Core Challenge:** Picture yourself as an Enterprise PM hearing, "We need AI!" Your real job is to ask, "What problem are we solving?" Idea Refinement in the context of software composing means turning lofty, easy-to-dismiss dreams into practical, buildable proposals.
**The Mission:** Turn "we need AI" into "we need to classify support tickets into three priority levels with 90% accuracy". For those classified at low levels, route them to an AI support agent that is able to assist the customer or user.
**Software Composing Refinement**
- Use Claude/GPT or even Cursor (with access to the underlying models) to expand vague requirements into detailed user stories
- Generate edge cases and potential failure modes for each part of the feature
- Take that technical objective and use AI to generate scenario analyses that tie back into your high level business objectives
**Action (Today):** Pick your most ambiguous requirement and use an AI editor to spin out five different interpretations. Narrow it down to three testable outcomes.
### Mode 2 -- Prototyping
**Core Challenge:** Building to learn isn't the same as building to last. Most get stuck perfecting their prototypes. Don't. Your job is to prove or disprove your riskiest assumptions as quickly as possible--like, within hours.
**The Mission:** Hack together a working prototype in a single day that nails the core value proposition. Use synthetic data for realism (even if everything's duct-taped behind the scenes).
**Software Composing Refinement**
- Let AI generate realistic synthetic data with a compelling narrative.
- Build quick UIs that zero in on the critical path; ignore edge cases.
- Create fake APIs returning pristine data for your happy path.
- Have AI produce diverse test scenarios to stress your assumptions.
**Action (Today):** Take your riskiest feature. Build a throwaway prototype with AI-generated test data. Show it to a stakeholder tomorrow.
### Mode 3 -- Disposable apps
**Core Challenge:** When [Greg talks about "disposable apps,"](https://www.meditationsontech.com/p/more-software-should-die-young) he's highlighting that sometimes code serves best by dying young. These apps go further than prototypes--they're actually deployed and used but skip all the usual production guardrails. They prove paths to production while staying intentionally short-lived.
**The Mission:** Ship usable software without production overhead. Forget lint rules, build optimizations, or CI/CD pipelines. Deploy fast to test environments. Learn from real usage, then toss it when you're done.
**Software Composing Refinement**
- Break normal rules on purpose--document what standards you're ignoring and why.
- Deploy manually--no CI/CD pipeline required.
- Replace code review with pair programming.
- Embrace messiness; chase learning instead of cleanliness.
- Have AI generate multiple architectural variants at speed.
- Document insights about the problem domain, not just the code.
**Action (Today):** Pick a feature bogged down in analysis paralysis. Build and deploy a throwaway version that ignores your usual best practices. Get it in front of users in under a week. Use AI to move fast and note everything you learn.
### Mode 4 - Production Code
**Core Challenge:** Production code meets real users, real scale, and real consequences. You can (and should) use AI here--just don't be naive. "Trust but verify" is the name of the game.
**The Mission**: Survive contact with reality while staying maintainable.
**Software Composing Refinement**
- Have AI scan your code for potential scaling issues.
- Generate comprehensive test scenarios based on actual production patterns.
- Ask AI to review error handling and propose more robust edge cases.
- Build monitoring and observability from the jump.
**Action (Today):** Take your most successful prototype and list all the ways it'd break in production. Use AI to uncover additional failure points. Then do the real work:
1. **Read every block of AI-generated code.** If you don't understand it, ask. AI often improves when challenged.
2. **Write comments.** If you can't explain it, you don't truly get it.
3. **Think through security, performance, and maintainability.**
4. **Validate package versions.** AI can get them wrong due to cutoff dates--Google is your friend.
### Mode 5 - Operations & Deployment
**Core Challenge:** Understanding how to get from local dev to cloud config is crucial. The challenge isn't just shipping code to production but fully grasping the operational tapestry. Your advantage? AI can funnel the collective knowledge of ops teams worldwide right into your workflow.
**The Mission:** Bridge development and operations. Make deployment and maintenance as core to your project as the code itself. And remember, coding-focused AI might not always have the best or newest answers for operational questions--sometimes ChatGPT in browsing mode is more relevant.
**Software Composing Refinement**
- Let AI interpret complicated cloud documentation into plain-English steps.
- Generate Infrastructure-as-Code templates that align with your real needs.
- Build dashboards with actual system health metrics, not just uptime checks.
- Explain not just what you did, but why you did it this way.
**Action (Today):** Identify one manual step in your deployment process. Use AI in web-browsing mode to find a modern way to automate it. Whip up a proof of concept. Document the how and why.
### Mode 6 - Troubleshoot and Debug
**Core Challenge:** Debugging in software composition demands a partnership between human insight and AI guidance. Plain error messages aren't enough. Your mission is to build systems that leave behind helpful breadcrumbs--logs, metrics, and context--so debugging becomes a guided investigation, not a blindfolded search.
**The Mission:** Transform debugging from reactive firefighting into proactive system understanding. Leave a clear trail for anyone--human or AI--who might need to explore the system's past behavior. Make logs that tell stories, not just record problems.
**Software Composing Refinement**
- Build Rich Context:
- Capture screenshots, environment details, and recent changes
- Track system changes over time with semantic versioning
- Document environment differences early.
- Strategic Logging:
- Log with breadcrumbs that AI (and humans) can follow.
- Show state transitions with before/after context.
- Capture relevant business context in technical logs
- Semantic Logging Patterns:
- Replace "Error in user authentication" with "Failed to verify JWT token for user {id} with error {specific_error}"
- Add business context: "Premium feature {feature} access denied for free tier user {id}"
- Include actionable data: "Rate limit exceeded: current rate {current} exceeds limit {limit} for API key {key}"
- Log successful operations too: "Successfully processed {count} records in batch {id} taking {duration} ms"
**Action (Today):** Take your most frequent error and rewrite its logging to deliver a complete narrative:
1. Add rich context about when and where it occurs
2. Include relevant business and technical details
3. Create clear correlation between related events
4. Use AI to generate comprehensive test cases that would trigger this error
5. Document the pattern in your team's debugging playbook
## Making the Modes Work
If you're still treating AI like a code vending machine, you're missing the point. Every mode in software composition calls for a different relationship with your AI tools. Sometimes it's about speedy exploration; other times, it's methodical verification and deep understanding.
The magic isn't in the prompt alone--it's knowing which mode you're in and adjusting your approach accordingly. AI IDEs and LLMs aren't a single hammer. They're a versatile toolkit you adapt to the job:
- **In Idea Refinement:** AI is your sparring partner, challenging assumptions and generating fresh angles.
- **In Prototyping:** AI gives you rapid generation and synthetic data on demand.
- **In Disposable Apps:** Let AI churn out multiple approaches fast--no polishing needed.
- **In Production:** Collaborate with AI for thorough analysis and to spot tricky edge cases.
- **In Operations:** Lean on AI (especially with web-browsing) for up-to-date operational wisdom.
- **In Debugging:** Work alongside AI to craft and interpret rich, semantic debugging logs.
Next time you open your IDE, ask yourself: **Which mode am I in?**
And how should that change the way I work with AI?
Your future self will thank you for the clarity.
---
# Dangit, Cursor!?!
> A troubleshooting guide for the 13 most common 'dangit' moments when building with Cursor AI.
Published: 2025-01-17 - Author: greg - URL: https://withstoa.com/blog/dangit-cursor
Cursor is awesome, but sometimes things get weird. And unfortunately there isn't an instruction manual. Here's how I solve common "dangit" moments while building stuff with natural language.
## Dangit, I need to start a new feature but don't know where to begin!
```
What worked for me:
1. Reference existing docs with @prd.md or @readme.md
2. Point to similar code with @directory
3. Say "let's focus on X first" to scope it down
4. Tell Cursor "Without any backend yet lets start to build this out"
The AI will help break it into manageable chunks.
```
## Dangit, something's broken but the error is vague!
```
My debugging flow:
1. Show the error message directly
2. Point to where it happened with @filename
3. Ask "What other things we could check?"
4. Try the AI's suggestions one at a time
The AI will help explore different angles systematically.
```
## Dangit, I need to make a bunch of similar changes!
```
My approach:
1. Make one change work first
2. Show the pattern: "I need to do this for all X"
3. Let the AI handle the repetitive parts
4. Review the changes one by one
Much faster than doing each change manually.
```
## Dangit, the AI isn't quite getting what I want!
```
What works for me:
1. Use quotes for exact text/code
2. Reference files with @
3. Say "without removing anything previously added"
4. Ask "Will we still X if Y?"
The AI keeps the good parts and fixes the rest.
```
## Dangit, I need to hook up multiple services!
```
My workflow:
1. Start with "Let's focus on X first"
2. Get one connection working
3. Show real config (DB URLs, API keys, etc.)
4. Test each integration step
The AI helps connect the dots gradually.
```
## Dangit, I need to fix something small but don't want to break anything!
```
My iterative approach:
1. Show the exact line that needs changing
2. Say "without removing anything previously added"
3. Ask "Will we still extract X if Y?"
4. Test edge cases: "Will this work with messages like..."
The AI helps validate the change won't break existing functionality.
```
## Dangit, I need to understand how something works!
```
My investigation style:
1. Show real data: "Here's an example payload..."
2. Ask specific questions: "Where does X come from?"
3. Question assumptions: "Will we still Y if Z?"
4. Get examples: "Like if someone says..."
The AI explains with your actual use cases.
```
## Dangit, the first solution isn't working!
```
My troubleshooting flow:
1. Tell the AI what happened: "it's broken" or "doesn't load"
2. Let it suggest checks: "any other things we could check?"
3. Try simpler alternatives: "Let's try a regular img tag first"
4. Keep the AI updated: "ok now public is in the root"
The AI helps explore different solutions systematically.
```
## Dangit, I need to try different approaches!
```
How I explore options:
1. Start simple: "Let's try X first"
2. Test each change: "Still broken..."
3. Let the AI suggest: "What else could we check?"
4. Keep what works: "Ok that fixed it"
Build up from simple to complex solutions.
```
## Dangit, I need to build a new feature from scratch!
```
My scaffolding approach:
1. Start with a basic component: "Let's create a basic layout"
2. Add temporary data: "// Temporary mock data"
3. Show a minimal working version: "This gives us..."
4. List next steps: "Next steps would be..."
Build the skeleton first, then flesh it out.
```
## Dangit, I need to connect frontend to backend!
```
My integration strategy:
1. Build UI with mock data first
2. Add placeholders: "// TODO: Will integrate with backend later"
3. Show real config: "Here's the database URL..."
4. Connect piece by piece
Keep the frontend working while adding backend features.
```
## Dangit, I need to handle complex state!
```
My state management flow:
1. Start with simple useState
2. Add loading states early
3. Handle error cases
4. Then add more complex features
Build up state complexity gradually.
```
## Dangit, I need to make UI components reusable!
```
My component patterns:
1. Extract shared props
2. Add sensible defaults
3. Make it flexible: "We can adjust X if needed"
4. Test different use cases
Start specific, then make it generic.
```
## Consolidated Pro Tips From Real Usage
```
1. Keep it conversational:
- "OK now..."
- "Let's actually..."
- "What if we..."
- "Let's create a basic..."
2. Show what's wrong:
- "it's broken"
- "doesn't load"
- "still not working"
- "needs to handle X"
3. Ask for alternatives:
- "any other things we could check?"
- "what else could be wrong?"
- "will this still work if..."
- "want me to implement any of these next steps?"
4. Guide the process:
- "without removing anything previously added"
- "let's focus on X first"
- "let's try X first"
- "this gives us..."
5. Share context:
- Show example data
- Point to specific files
- Explain what changed
- List next steps
6. Build incrementally:
- Start with mock data
- Add basic functionality
- Handle edge cases
- Then add complexity
7. Stay in sync:
- Tell the AI what changed
- Show what happened
- Keep it updated
- Test assumptions
8. Structure your code:
- Start with types/interfaces
- Add basic components
- Include TODO comments
- List what's missing
```
---
## About This Guide
This guide comes from real experiences building a social media tracking app with Cursor AI. It's based on actual conversations and problem-solving patterns that worked.
### Credits
Thanks to:
- The Cursor AI team for building an awesome tool
- The [dangitgit.com](https://dangitgit.com/) team for inspiration
- All the software composers, AI first builders and software developers sharing their real experiences
---
# Using Cursor to Create Sample Data for your NextJS App
> A hands-on tutorial for getting sample data into a prototype application using Cursor and AI-driven development.
Published: 2025-01-12 - Author: jake - URL: https://withstoa.com/blog/using-cursor-to-create-sample-data-for-nextjs
## Building a prototype without the hassle of a database
This is going to be a hands-on tutorial for getting sample data into a prototype application that you're composing. We'll demonstrate using a NextJS web application, but the same approach works for other application types, including desktop apps built using Electron or mobile apps built using Flutter.
Why would you want to do this? Because sometimes you just want to communicate an idea quickly without having to deal with the headache of a database. Colin Matthews says it well in a recent [post](https://www.lennysnewsletter.com/p/a-guide-to-ai-prototyping-for-product) about Cursor and other tools:
> But what's cooler is that you can use these tools to build functional prototypes from a Figma design, convert a rough hand-drawn sketch to a working app, translate a PRD document into an interactive prototype, or even build a usable internal tool for your team, with no coding ability

## Getting Started
Install Cursor and get your laptop [setup](https://newsletter.specstory.com/p/getting-started-with-software-composition) for composing a Node app.
Follow the instructions for creating a new [NextJS app with ShadCN](https://ui.shadcn.com/docs/installation/next). Specifically:
```
npx shadcn@latest init -d
```
And then when prompted, create a new project, sample-cars:
```
✔ The path /Users/name/dev/specstoryai does not contain a package.json file. Would you like to start a new Next.js project? … yes
✔ What is your project named? … sample-cars
```
Add two simple components, button and card:
```
cd sample-cars
npx shadcn@latest add button card
```
And open your new project in Cursor:
```
cursor .
```
(If you haven't already setup the cursor command on your machine, you can do so now inside Cursor by typing Ctrl/CMD-Shift-P to bring up the Palette and then running `Shell Command: Install 'cursor' command)`.
Start the development server:
```
npm run dev
```
You should see the Next.js sample app if you visit http://localhost:3000.

## Creating sample data
This is a great start, but as you can see the placeholder cards are all identical. This doesn't really get the concept across. Let's prompt for some sample data:
Add a new file that will hold JSON sample data for our application. Create an array of 10 cars using examples of classic cars from the 1950s and 1960s. For each car, store the make, model, engine type, years of manufacture, and a one sentence description.
I'm pretty intentional here about asking for a new file, mainly to keep my project and directories clean, and about asking for JSON data which is a widely used standard format for saving data. I gave Cursor some specifics to guide the creation of sample data, including the properties I wanted (make, model, etc). But you can also often get good, if sometimes surprising, results with open-ended requests, like `Create an array of data for 10 classic cars`. Finally, asking for an array in this prompt was intentional. We likely would've gotten the same results asking for a list of cars or just sample data for 10 cars. But in this case I knew specifically what I wanted for this tutorial. In general, it's worth experimenting with the level of specificity of your requests. Being overly specific, especially on a topic you don't yet know well, can steer the AI in the wrong direction and prevent it from making better recommendations.

## Displaying the sample data
In this case, Cursor did a great job of generating a sample data file for us, but it didn't make the leap to placing this sample data onto the page for us (in /app/page.tsx), so when we view the page we won't see any change.

Reading Cursor's response carefully, we see that it did at least ask if we'd like it to make the update to the main page to use this data. If your Cursor session also deferred making use of the sample data, you can use a prompt similar to this one to get it to finish the task:
```
Using this data, update the cards on our main page.
```

You might inevitably hit some hallucinations like we did with the Cadillac Eldorado, which was actually manufactured from 1952-2002. Fact check and manually correct the data file Cursor produced, until you're satisfied.
## Images - the SVG placeholder trick
Now some images would be nice. The fastest approach is to have Cursor generate a placeholder SVG for you and then display that on all the cards.
```
Generate a new SVG file in /public that is a placeholder image
we can display for all the car cards.
Use it on all the cards on the page.
```
For our type of application, a NextJS web app, any files in the `/public` folder will be available through the web server. For example, if you place `image.png` into the `/public` folder you'll be able to access it at a URL like `http://localhost:3000/image.png`.

Not very stylish, but at least it gets across some of the spacing and layout for our prototype. To take this to the next level, we can get images for each of these classic cars and copy them into the `/public` folder.
## Real images - the naming convention trick
I attempted to use ChatGPT with "Search the Web" enabled to `find an image for each one of these 10 classic cars`. But the results were mixed, and more often than not it hallucinated dead links. A more accurate approach is to use the Creative Commons Search Portal and paste in the name of each car in your sample data set. Download each image, rename it to something like make-model.jpg or make-model.png (e.g. `chevrolet-corvette-c1.jpg`) and copy it into the `/public` directory in the top of your sample-cars project. This will let Cursor connect the JSON data with the right images.

If you've named the files to match the make and model in your JSON data, it's now easy to prompt Cursor to reference them:
```
The @public directory now has real images for some of the cars.
Update the sample JSON data file to include links to images if available or to the placeholder SVG if not.
Make these new images render on the cards on the page.
```

## Making sample data interactive
Now let's add the ability for the user to pick their favorite cars.
```
We want to let the user select their favorite cars and bring them to the top of the page.
Add a ShadCN button to each card with an icon for "favorite".
```
This might work for you, but I hit the following error when Cursor tried to import the icon for the button.

Though the Cursor composer agent can automatically handle linter (coding-time) errors, it can't handle build-time errors like this one without your help. Copy and paste the entire error into your Cursor prompt and it should be able to resolve it for you.
```
Build Error
Failed to compile
Next.js (14.2.16) is outdated (learn more)
./app/page.tsx
Error:
x You're importing a component ...
```
And now you can click a heart to mark one of the cars as your favorite and move it to the top of the page!
See the full [Cursor history for this project](https://share.specstory.com/stories/308734cb-ae6d-49f9-9590-a4c60fa67360) and stay tuned for more data topics such as using HTML Web Storage (localStorage), and composing scripts to gather sample data.
---
# The AI Code Review Gap
> Quick to write, pain to review
Published: 2025-01-02 - Author: jake - URL: https://withstoa.com/blog/the-ai-code-review-gap

600 users, no analytics.
Right before the holidays we [launched](https://specstory.com/blog/specstory-launch) the first product iteration of SpecStory -- an [extension for Cursor](https://docs.specstory.com/introduction) -- and more than 600 people have installed it: *great!*
What we were missing, however; were usage analytics on the extension itself so we could know (anonymously) when people were activating it: *not so great!*
**So picture this:** a product leader, seasoned engineer and AI assistant enter a zoom room. All with the expectation of adding analytics via PostHog to the extension for the next release.
Like many modern [software composers](https://tolacapital.com/2024/11/13/the-rise-of-the-software-composer-a-new-era-of-software-creation) I first approached this task solo with Cursor's [Composer](https://docs.cursor.com/composer/overview#welcome-to-composer) as my guide. The code flowed effortlessly, each prompt brought new functionality to life. Smoke tests worked, events flowed into PostHog, and everything seemed like smooth sailing.
Until the moment of truth: [the pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#about-pull-requests).
### When Worlds Collide
Reality has a way of humbling our assumptions: my 60 minute composition session created a pull request that, as we started digging in, *we realized would take more than 5x as long to review.*
As Sean, our CTO and I sat in that Zoom room together, he began asking questions about specific lines of code.
And I found myself in an unusual position: *unable to explain any of the details of what I had created.*
This moment crystallized for us the new gap created via AI-assisted development: intent and implementation doesn't vanish with AI--it just shifts. While I could articulate what I wanted the software to do, I *personally* had lost the thread connecting each line of code to its original purpose.
Not wanting to let this pain point go to waste, Sean and I spent the next day experimenting with a decidedly different approach.
### Trio Programming
Instead of going solo from the beginning, we decided to *connect* product intent with engineering wisdom while allowing Composer to act as our implementation partner.
As the quick video shows, we moved in small deliberate steps and caught potential regressions that had previously made the pull request opaque and could have turned into hard-to-rectify production issues.
The good news? We ultimately got the analytics shipped (check out [version 0.2.4 here](https://docs.specstory.com/introduction)) and learned a few things that will probably resonate with you:
- For rapid prototypes and demonstrations, solo AI software composition shines
- For production features, our trio programming approach provides the right balance while still allowing us to "eat our own dogfood"
- For technical intents (like improved code quality linting or enhanced CI), traditional engineering often remains the most efficient path
### Substitutes for the second human partner?
While the trio approach with myself, Sean and Cursor worked well, we can't help but think about the future. The time we spent together given the tools currently at our disposal was clunky and doing trio programming likely won't scale at the same rate that we intend to grow.
In parallel, we've been debating if another AI could serve as a stand-in. While it is still early days, Greg began pulling on that thread before the holidays. The experiment wasn't for a SpecStory production feature but it is a fascinating glimpse into a *to-be-further-verified* promise.
To help our distribution efforts, Greg is building an AI Code Editor ranking app. It sources data from Reddit and uses ChatGPT to analyze the sentiment. He had the idea to use Google's [new realtime streaming](https://developers.googleblog.com/en/gemini-2-0-level-up-your-apps-with-real-time-multimodal-interactions/) functionality to "watch his screen" as he composed and offer suggestions on the code -- as it was being generated -- using Cursor and Claude.
While the demo above was mostly happy path it points to the exciting possibility of AI not only being a code generator but an active review partner. While currently also clunky to manage, it appears to be the best "test" option sans connecting ChatGPT directly to Cursor through their ["Work with Apps" beta feature.](https://help.openai.com/en/articles/10119604-work-with-apps-on-macos)
In his words:
> It was great to be able to work in familiar modalities and have the second AI keep up. I was impressed with how easily it was to be able to direct Gemini at parts of the screen and get very specific feedback on Cursor's implementation of my intent. The jury is still out on whether it will be able to aid my efforts on more complicated software composing.
So there you have it: as we continue to build SpecStory, we're committed to consistently sharing these type of learnings.
We believe that no matter if you're a solo composer, part of a larger team, or somewhere in between, finding the right balance between AI assistance and human judgement will be continue to be crucial in the *months* and *years* ahead.
---
# Getting Started with Software Composition
> A basic tutorial for coding without coding
Published: 2024-12-18 - Author: jake - URL: https://withstoa.com/blog/getting-started-with-software-composition
You may already be a seasoned engineer, in which case this week's post isn't for you. But maybe you can share it with your non-engineering friends.
For the rest of us, this video is a start from zero, what's the Terminal, how do I build and launch a simple website in under an hour kind of tutorial.
We'll walk you through setting up a clean Mac or Windows environment and installing essential tools like Cursor, Node.js, npm, and Homebrew needed for software composition.
You'll learn:
- How to configure your development environment from scratch.
- Setting up a Next.js project with ShadCN component library.
- Using Cursor's AI capabilities to write and debug code effortlessly.
- Debugging common issues and leveraging documentation.
- Sharing your project using GitHub.
By the end of this video, you'll have a fully functional project and a foundational understanding of using AI tools for software development--even if you're not a coder. Perfect for anyone ready to explore the world of AI-powered app creation.
Also, shameless plug, the last few minutes are a demo of the [SpecStory Extension for Cursor](https://get.specstory.com/cursor-extension) that we recently launched to help you save and share your AI composer and chat history.
## For Mac Users
## For Windows Users
## Additional Notes
**Full Cursor Chat History**
- https://share.specstory.com/stories/20072845-d03c-4961-b276-167fe6eeb2ad
**Links**
- https://www.cursor.com/
- https://brew.sh/
- https://formulae.brew.sh/formula/node
- https://ui.shadcn.com/docs/installation/next
- https://github.com/
- https://vercel.com/
- https://specstory.com
**Transcript**
This is a video about SpecStory which helps you when you're doing AI-driven development using a tool called Cursor. If you haven't been doing AI-driven development and you're just getting started, this video is for you. It will help you get set up with Cursor that'll let you do software development even if you're not a software engineer or coder.
This will be a RAW video - we're not going to fast forward past the bumpy parts. We've got a clean Mac install with just a few pieces of software already installed. This should give you a sense of what it'll take to get started from scratch building software with Cursor and Spec Story.
The first step is getting Cursor installed and set up. You can go to cursor.com and download for your operating system, in this case Mac. We'll have another video for Windows in the future. Once you've got Cursor installed you can just run it like any other tool. On Mac I use command space to start applications but you can go to your Applications folder.
On first run you'll see nothing set up and it's asking for you to configure some settings. All these defaults are perfectly fine. I like to say yes and continue if you don't mind sending data back to Cursor to help improve. You can choose privacy mode if you prefer. Cursor is a paid tool, $20 a month and it's well worth it and it's really the only tool that we absolutely need to pay for. All the rest will be able to set up free alternatives.
This is what it looks like when you first get Cursor installed and authenticated before you do anything. Our first step is opening a folder - that's the way that most integrated development environments (which Cursor is) use a folder-based approach for managing projects.
Let's first create a folder. We could open an empty folder, but usually we start from a starting point. The starting point we'll choose is an application framework called Next.js. We're going to make use of what's known as a user interface component library called shadcn. The easiest starting point is to just go straight to the shadcn docs and the installation steps for Next.js.
You could prompt your way through the setup by asking ChatGPT or Claude to help you get a new project set up. But I've found that sometimes these steps can be out of date. In this particular case, I prefer to use the raw documentation at ui.shadcn.com/docs for the Next.js installation.
For running the Next.js installation, I've chosen the NPM version. You can choose any of these, but most of the output of Cursor and Claude favors the most used tools. NPM is one of, if not the most used tool for these particular things. NPM is one of a pair of tools we're going to need.
When we're building UI applications we have lots of choices, but a really good set of standard choices is to use Node. Node is a framework for building websites or interactive web applications. That's what we're going to do here.
Let's try to run the installation command. But the first thing you'll notice is that NPX is not found. So we need to get some tools set up first - at least a minimal set of tools for software development. Two of those are Node and npm. NPX is just one of the commands that's available as part of NPM.
Let's get some tools installed on our Mac. The most widely used tool for installing other development tools on a Mac is called Homebrew. Homebrew tries to make it dead simple to get started - there's just a single command line that you run to install Homebrew itself, which then opens the door to install lots of other applications.
This whole process will only work if you're set up as a Mac administrator on your laptop or desktop. If you don't know what that means, you need to Google "Mac administrator" and make sure you get your account set up properly for that.
After installing Homebrew, don't skip the next steps - we need to run each of these follow-up commands in succession. Now we should be set up so that whenever we want to, we can run the Brew command. The two things we need Brew to install for us are Node and npm - it's just one command.
If you ever get lost, you can ask ChatGPT "how do I install Node using Homebrew?" Either method they suggest is fine. They recommend first running "brew update" (though we just installed it so it should be up to date), then "brew install node". We can then verify our installation by checking the version of Node and npm.
Now that we've got these installed, let's go back to where we started - creating a new application using shadcn. Now that we've got Node and NPM installed, we should be able to run the installation command. When it asks for configuration options, all the defaults make sense, and you can just hit Enter to accept them.
When the first part completes, you can select all the defaults for shadcn. You can read about shadcn and all the options available, but we'll just accept as is. The installation creates a new directory called "hello" in your current location.
Now in Cursor, if you see the option asking if you want to install a command to run Cursor, I would recommend it. Choose to install the command named "cursor". This means you can come to your terminal and run "cursor" on any directory like the hello directory, and it'll just open Cursor straight to that directory for you.
There are two really important things we want to enable when we come into Cursor. One is the terminal - this is the same terminal we were just in, but now it's integrated into Cursor. The other thing is the AI pane over on the right-hand side, which lets us do the magic and use AI to help us write code.
At this point, you can use Cursor and ask it questions like "what command can I run to start this application?" When you use Cursor, you can add context, which means pointing to any of the files in your current project directory or other outside content. One of the simplest ways, especially when you're starting and have a tiny project, is to tell Cursor to include the entire codebase.
You can say "include codebase" to tell Cursor to look at everything here, all the files and folders, when it's trying to answer questions. When we ask about starting the application, it shows multiple commands you can use. The software development community has created four different package managers that do roughly the same thing. We'll just stick to npm for everything.
When it suggests commands, it means to run these commands inside the terminal. You can copy one of them and paste it into the terminal. The command "npm run dev" is one you'll probably end up memorizing because you run it so often.
What this does is run a web server that allows you to interact with the code of this website to see it in your browser. This server will package up all this code and turn it into a website. We can visit the URL it provides in our browser. If you want, you can hold down the command key and click the link to open your browser right there.
The whole site is exactly what the code says should be rendered. Now we can move on and create a site that we actually want, because we wanted a hello site, not one that said Next.js on it.
Now we can use Cursor to do all of the heavy lifting for us. Once we get things to this point and set up, the world is our oyster. I often like to create new composers when I'm onto a new task. You can always get back to your old composers whenever you want. A composer is just like a conversation between you and the AI acting as your engineer.
Let's make the most fun hello world page we can. It's wintertime and I like the holiday season. Let's create a page for the holidays and winter. You can get creative and make some SVGs so the page looks pretty. Don't worry if you don't know what an SVG is - it's just a type of image format that Cursor and Claude are particularly good at rendering.
We'll submit that request and let Cursor Composer do its work by suggesting changes and edits to all of our files. Sure, we could dig in and try to follow along, and there's a lot of learning to be done with that. But sometimes we just want to hit "Accept all" and see what we've got.
One of the nice things is as you make and save changes in the code - or more specifically as Cursor makes changes in the code and you hit Apply all to save them - this server that we're running (remember we started npm run dev) is still running in the background and looking for any changes to our application files. It's immediately incorporating them so that when we come back to the browser and reload, we can see those changes.
Look how fun it is! I couldn't have even imagined this a year ago but Cursor and Claude are able to write the code for a holiday site just like this. Now let's take a minute to add in some more traditional elements of web applications. This will start to get at the reason why we installed shadcn.
If we look at shadcn, it's pretty interesting because what it is is a component library. If you've been to any website or web application, you've probably seen some combination of these already on the page - everything from a simple button that looks nice and styled and works well, to a calendar control or a card where a card is just this sort of rounded rectangle layout that gets used often in modern websites and web apps.
We're going to use cards and buttons in our hello site. The easiest way to do this is to just ask Cursor to help us do that. Let's add two cards to the site that present some holiday greetings.
I'm hoping that Cursor will pick up this word "cards" and know that I mean shadcn cards. In this case it created cards using styling rather than the shadcn components. We can ask it "did you use shadcn for those cards?"
When we try to install the shadcn components, we might run into some errors. That's okay - Cursor and Claude can help us with this. We just copy the error and context, and Cursor will help us resolve it. It realizes that the components aren't installed yet.
We'll need to run some installation commands in the terminal. You have a couple of choices - the easiest of which is to stop what's already running in this terminal. The way to do that is to hold down the control key (not the command key) and hit C. That stops the npm run dev server and then we can run our installation commands.
When we get everything installed and running, we might run into eslint errors when trying to deploy. ESLint is just a tool for trying to create clean code. By default, Next.js and Vercel are configured to really try and have clean code.
We can work through these errors step by step:
- Fix the ESLint configuration
- Install any needed dependencies
- Update configuration files
- Commit and push changes
- Try deploying again
At a certain point we could decide that we need to dig in, learn more about ESLint, learn more about Vercel, do some research of our own, build up our knowledge base. But for now, we can try to have Cursor and Claude help us get past these issues by installing the right dependencies and updating the configuration.
Once we get past our configuration issues, we can deploy our site using Vercel. Vercel works very nicely with the type of application we just built, which is known as a Next.js web application.
Let's get started with Vercel. We can sign up if we haven't already - "working on personal projects" is a good option to select. We can continue with GitHub, and it will go through and authorize Vercel. We need to make sure we install Vercel for our GitHub account and give it access to our repositories.
Our first Vercel GitHub integration was literally just to do the sign into Vercel. That second integration, the install, is what was needed for Vercel to connect to our repositories. We can see that hello repository that we just updated.
We can hit the import button here. Often defaults are your friend, especially when you're working with a Next.js application and Vercel. Those work very well together. Hit the deploy button and Vercel will take everything that we've done, all that code and package it up.
After deployment completes, there are a couple of different URLs. One that we can use for working and commenting on this particular deployment, and one that we can share with the world. The one we can share with the world is what we care about most - that's what the little global icon indicates.
When we click on it, we can see our application up and running. We get a Vercel toolbar and some extra accompaniments because we're logged into Vercel. But if we share this with somebody else, which we can simulate by opening an incognito window, they're just going to see our application, our page - it's going to work, and they're going to have a happy holiday.
Now that we've got our happy holiday site all built, let's learn about what Spec Story can do to help with this flow. We can go to specstory.com - we can see this Cursor extension is exactly what we need.
To install Spec Story directly into Cursor instead of VS Code, you actually have to go through Cursor. Go to the extension marketplace icon up in the top left. Then we can search for Spec Story and install it.
Once we've got Spec Story installed, there are two big things we can do with it: save the entire chat history (not just one conversation, but all composer sessions and chats we've had) or share these out. Spec Story makes it really easy to share these with others.
Let's start with saving. Both commands are run from the command palette inside Cursor. You can get to the command palette a couple of different ways - you can search help for it and see View command palette, or use Shift command P as the keystroke.
If we just type Spec Story in the command palette, we can see our two commands. The first one is to save the composer history. Saving the composer history creates a new markdown file which is then opened for preview. You can close that preview if you don't like it and just want to look through the markdown file.
The file shows all of the history I've had for building out this entire application. All the chats and composer sessions are saved in this file. If we want to really save this, we can hit command S and save it as "Spec Story History.md".
We can even reference this file and ask questions about it, like "Give me a brief summary of everything I did in this project." It helps us remember everything we had to do to get through this development.
If we want to completely unlock this history for others, we can go back to the command palette and use "spec story share composer and chat history." We see down on the left that it's published out this history for me to share with others. When we open it, we get a nice clean view of everything that happened from start to finish in the AI chat history.
It's a great way to share the story of how you created your application.
---
# A CEO's Journey Back to Code
> How AI-driven development tools pulled me back into hands-on coding after decades in product leadership.
Published: 2024-12-16 - Author: jake - URL: https://withstoa.com/blog/a-ceos-journey-back-to-code
## From the Sidelines to Software Composition
There's a peculiar feeling that many product leaders know well - the combination of pride and slight detachment that comes during a product launch. You're there, heart racing with excitement, but you're on the sidelines.
Coaching.
Cheerleading.
Supporting the team that's doing the heavy lifting. It's a role I've played many times throughout my career, and one I had grown accustomed to since stepping away from hands-on engineering decades ago.
But something different happened during the launch week for SpecStory, our [VS Code extension for Cursor](http://get.specstory.com/cursor-extension). Instead of watching from the sidelines, I found myself back in the game: hands on keyboard, directly contributing to the code that would shape our very firstproduct. This return to coding wasn't just about building features - it was about rediscovering a part of myself I thought I'd left behind.
## My Path to Product Management
My journey _away from coding_ wasn't accidental. Early in my career I discovered something intoxicating: the moment when software meets the real world. Seeing how people actually use and find value in what we built - that was the hook that pulled me into product management. That, and if I'm honest, my restless nature. I loved the ideation, the broad strokes, the ability to work on multiple concepts simultaneously. What I lacked was the patience for the final 20% of coding - the corner cases, the edge scenarios, the meticulous attention to detail that great software engineering demands.
This realization led me into product roles that grew larger over time, eventually landing in product leadership positions at DigitalOcean and Docker. It was fulfilling work, but it came with a certain distance from the hands-on creation process, especially during those crucial launch periods.
## Team SpecStory is a new kind of collaboration
At SpecStory, we've built something special - not just in our product, but in our team composition.
- There's Sean, my co-founder and CTO, who I've been fortunate to work with for over 15 years since our IBM days, the driver behind our launch.
- Calvin, whose engineering expertise went far beyond building our first version; he crafted the product, process, and packaging in a way that empowered the rest of the team-even those of us without engineering backgrounds-to actively contribute and build upon his work.
- Greg, our chief evangelist, brought his experience from GitHub and Pluralsight along with his passion for software composition to set pace and guide us always towards the cutting edge of this new market.
- And Han, whose depth of understanding of developer experience, design thinking, and product sense have brought clarity to our current and future product vision.
What makes this team unique is that we're a blend of developers, traditional software engineers and what we call "[software composers](https://tolacapital.com/2024/11/13/the-rise-of-the-software-composer-a-new-era-of-software-creation)" - people who, like myself, may not have written professional code in years, or ever, but can now contribute directly to the codebase through AI-driven development tools.
## My newly shaped perspective
Last week leading up to our soft launch was frenetic. We were pushing hard to release both our [VS Code extension for Cursor](http://get.specstory.com/cursor-extension) and our web application, where users can save and share their composer and chat history.
Instead of just articulating how I wanted the web application to feel, I myself was able to rapidly prototype it together with Han using Cursor. When Calvin saw our prototypes, his response was notable: "Wow, this is really helpful - I can see and interact with the exact concept you're going for."
This wasn't just about prototyping. When we needed a responsive design for mobile devices, instead of adding it to our backlog, I rolled up my sleeves and built it by software composing.
Using our own SpecStory [extension](http://get.specstory.com/cursor-extension), I was able to document my prompts and thinking in the pull request, making it easier for Calvin to review and understand my intent.
This experience for all of us was eye-opening. I found myself implementing features I would have previously only specified: branding elements, calls to action, redirect handling, the save-as-markdown button, and even user analytics integration.
Meanwhile, Han was using similar flows for interactive design prototypes, defining the conceptual and visual core of our software experience in a way that was more tangible than static mockups alone could ever be.
And Greg used software composition to build our entire marketing website, starting from a blank page, in less than a day. His experiences using these workflows for months really shaped our initial product vision.
## A New Model for Software Creation
What we're building at SpecStory isn't just a tool - it's a bridge between traditional software engineering and a new way of creating software. We're one of the earliest teams to successfully blend software engineers and software composers, working together in harmony.
This isn't about replacing traditional engineering - it's about augmenting it, making it more accessible, and allowing more voices to contribute directly to a product's evolution.
For me personally, it's meant the joy of being back in the game, contributing directly to our product while maintaining the strategic view that drew me to product management in the first place. It's about finding a balance I never thought possible - between big-picture thinking and hands-on creation, between leadership and direct contribution.
As we continue to build and refine SpecStory, I'm more convinced than ever that this hybrid model of software development is the future. A future where the distinction between those who envision and those who create becomes increasingly fluid.
Where more directly contribute to the creation process.
And where the sidelines become just another vantage point rather than a permanent position.
---
# SpecStory Launch
> Introducing SpecStory - capture, search, and learn from every AI coding journey.
Published: 2024-12-16 - Author: greg - URL: https://withstoa.com/blog/specstory-launch
## Introducing SpecStory a new extension for the Cursor IDE.
Today, we're thrilled to introduce SpecStory - we make it easy to capture, search and learn from every AI coding journey.
Get [SpecStory](http://get.specstory.com/cursor-extension) here on the Visual Studio Code Marketplace.
Imagine having easy access to your intent, every productive AI interaction and every "aha!" moment you've had while [software composing](https://tolacapital.com/2024/11/13/the-rise-of-the-software-composer-a-new-era-of-software-creation) or AI-first building.
The SpecStory extension captures and renders your AI chat and composer sessions into formatted Markdown that both humans and machines can understand, creating a persistent memory.
With SpecStory, you can:
- Save your AI conversations directly to your project files with a single command
- Reference past discussions using `@` mentions in new sessions
- Share your coding adventures through anonymous, shareable URLs at share.specstory.com
- Break down complex solutions into actionable tasks for your next coding session
Best of all, it integrates seamlessly into your existing workflow.
No complex setup, no context switching.
Download the [extension](http://get.specstory.com/cursor-extension) and open your command palette (Cmd/Ctrl+Shift+P).
With a keystroke, your conversations are instantly transformed into markdown files, ready to be saved and versioned: `SpecStory: Save Composer and Chat History`
Oh and you can share your conversations with a single click: `SpecStory: Share Composer and Chat History`
We believe AI tooling should be powerful enough to meaningfully improve your work while being natural to use.
We're excited to see what this unlocks and look forward to your feedback to rapidly iterate and improve the experience:
- [GitHub Discussions](https://github.com/specstoryai/getspecstory/discussions)
- [File an issue](https://github.com/specstoryai/getspecstory/issues)
- [Join our slack](https://join.slack.com/t/specstory/shared_invite/zt-2vq0274ck-MYS39rgOpDSmgfE1IeK9gg)
- [Read the docs](https://docs.specstory.com)
---
# Recording by Default
> Our practical approach for turning meetings into shared insight
Published: 2024-12-10 - Author: jake - URL: https://withstoa.com/blog/recording-by-default
### Working Transparently
My cofounder, [Sean](https://www.linkedin.com/in/snootymonkey/), previously created an entire company around the idea of startup transparency. And GitLab's [work in the open](https://handbook.gitlab.com/) has helped me many times throughout my career. Everything from product management job descriptions to product operations best practices are well captured in their living handbook.
At [SpecStory](https://specstory.com/) we value transparency and working openly with each other.
It's why we hit "record" on nearly every Zoom call. Real product decisions, customer feedback, internal debates, and co-creation sessions--these moments are valuable and we want to prevent them from slipping into the ether.
*Example:* below is a three minute highlight reel (edited with [descript](https://www.descript.com/)) of us co-composing [our home page](https://specstory.com/) last week.
We went from blank slate to it being working and deployed. The share of this experience allows other team members not there to understand "how we built it".
### **Upgrading our Recording Stack**
For us, Zoom's built-in recording features were a good start: cloud recordings, transcripts, basic AI summarization. What we like the most is that it's unobtrusive... it doesn't invite a "recording bot" into the meeting.
We quickly encountered friction.
Storage gets pricey, organization is bare-bones, and shared links become difficult to manage. We needed a better system and stack--something that could preserve the ease of Zoom's native recordings without forcing us to juggle storage upgrades or bot integrations.
We evaluated a handful of tools before landing on [Grain](https://grain.com/).
This might sound like an ad for Grain. But I have no connection to Grain other than being a happy user.
There are a bunch of reasons Grain aligns well with our needs. For example, it lets us [auto-import](https://support.grain.com/en/articles/4739669-how-do-i-import-previously-recorded-calls) every Zoom recording with no special invites.

And once you're past the basics of getting recording setup, you can use playlists and tags to organize all of your meetings.
It's also helpful to turn on Grain Workspace access by default for all meetings so you don't have to manually set it for each video:

You and your team can now grab the transcripts and use AI to extract useful nuggets.
### Turn Raw Footage into Insight
Recording alone isn't enough. You want meaning from all the dialogue.
*Example:* after our user research interviews, we run each transcript through Claude, with the following prompts (each issued separately). These prompts are a sieve for surfacing signal.
- Extract key takeaways from this research interview
- What was most important for them?
- What were they most excited about?
- For their most **challenging** story, summarize the following:
- Problem or challenge
- The pain points
- Solutions tried
- Tools or processes used
- Outcome
- Lessons learned or what he'd do differently next time.
- For their most **positive** story, summarize the following:
- The problem or challenge
- The pain points
- Solutions tried
- Tools or processes used
- Lessons learned. What would they do differently next time?
- Extract the 3 most salient quotes from the interview
- Make a simple list of every tool or service they mentioned
And this approach produces really interesting learnings. Below is a quote from a conversation I had recently with a [software composer](https://tolacapital.com/2024/11/13/the-rise-of-the-software-composer-a-new-era-of-software-creation) in Oslo:
> On the empowerment of AI tools: "I felt very powerful because I've always been dabbling with code, but I've always had developers who actually built the stuff I wanted to build, but now it's more direct."
Within minutes, we have a distilled version of the conversation's essence.
1. We find patterns in user pain points
2. Lock onto the most resonant quotes, and
3. Identify workflows we hadn't considered.
We use this practice for more than user research.
Internal team meetings contain plenty of hidden gems, too. We might discover a recurring theme everyone keeps circling around, an idea backlog we didn't realize we had, or a point of contention worth smoothing out before it snowballs.
Recording, organizing, and analyzing helps us turn the stream of chatter into a structured, living knowledge base.
Some may worry it could feel intrusive. But used thoughtfully and transparently, recording becomes as natural as taking notes.
Critical one-on-ones can stay private, but in general, default recording ensures nothing slips through the cracks.
It takes a few weeks to adapt, but soon it's second nature--hit record, talk freely, trust that nothing valuable will be lost.
### ***Start Now***
Know a founder who's drowning in meeting overload? Share our story and guide.
With the right tools (like Grain and Descript) and a handful of clever prompts, every conversation opportunistically becomes a future resource.
Meetings are now a wellspring of shared understanding, a repository of hard-won lessons, and a catalyst for action.
*Stop letting insights slip away.*
*Start recording, start organizing, and start extracting meaning.*
Turn your team's conversations into living blueprints for the future.
---
# Loading... A Design Philosophy
> Why starting with blur can lead to clearer results
Published: 2024-12-03 - Author: jake - URL: https://withstoa.com/blog/progressive-rendering-and-software

*Click.*
Its 1998 and the image begins to load at 56kbps.
Line by line, pixel by pixel, a JPEG of Hello Kitty riding a unicorn materializes on your screen.
At first, it's just blocks of color--abstract shapes swimming into view. But even before the details sharpen, your brain starts connecting the dots. You can already tell what you're looking at.
That's the magic of progressive rendering. It is a relic of dial-up internet days that taught us about human perception. Long before the image fully loads, our mind grasps its essence. We don't need perfect clarity to understand what we're seeing.
It's a powerful metaphor for effective design.
#### The Power of Starting with Blur
I re-discovered this insight during a recent conversation with Arturo, a designer and software composer.
Arturo and I were talking about the idea of "progressive refinement".
It's his unique take on [software composition](https://tolacapital.com/2024/11/13/the-rise-of-the-software-composer-a-new-era-of-software-creation) and starting with blur--intentionally keeping things low-fidelity at first.
"It's like a diffusion model," Arturo explained, gesturing at the screen. "Instead of trying to design every component in perfect detail from the start, you begin with these rough, basic elements. You let the clarity emerge gradually."
As he spoke, I found myself thinking about how different this was from my usual approach to design and development. I'd often felt the pressure to have everything figured out upfront, as if each component needed to be perfectly crafted before moving forward.
The idea stuck with me. The following week, I was working on a new prototype, staring at my screen and thinking about Arturo's words. I needed placeholder images for my mockup. I was about to fall into my usual rabbit hole of searching for the perfect stock vectors.
That's when it hit me--why not ask Claude to generate simple SVGs?
I typed: "render a SVG that looks like a really simple web page with a table"

And there it was--crude, basic, but instantly recognizable. A table materialized in simple vectors, its essence captured in primitive shapes. It wasn't perfect. It wasn't even good.
But it was exactly what I needed.
#### Letting Design Emerge
I thought back to my conversation with Arturo, how he'd described this diffusion model of design.
Just like those loading images, good design doesn't emerge fully formed.
It spreads out from core concepts. Each iteration brings more clarity and detail. The magic isn't in getting everything right from the start--it's in getting just enough right to see where you're going.
Working on that prototype, I started experimenting with this approach more intentionally.
- Need a user profile section? I block it out with basic shapes.
- Trying to figure out a complex data visualization? I start with colored rectangles.
- My Authentication flow? Squares and arrows make sense for now.
Each rough sketch was like those first few lines of a loading JPEG--just enough information to let your brain fill in the rest. And just like those images of the dial-up days, each iteration brought more clarity, more detail, more understanding.
It wasn't just about saving time on mockups.
It was about finding freedom in imperfection.
With low fidelity, you allow yourself to be wrong. You can explore and let the design emerge.
#### Creating space for serendipity
I've started seeing this pattern everywhere now.
1. In the way successful products evolve from minimal viable versions.
2. In how good architects start with rough sketches before touching CAD software.
3. In how writers begin with outlines before crafting prose.
Start with the essence, then let the details diffuse into place.
Let the image load one line at a time.
Now when I start a new project, I think back to that conversation with Arturo and my subsequent SVG experiment.
Sometimes, the clearest vision comes from embracing the fuzzy edges first.
Just like that simple SVG table Claude generated for me.
It wasn't the end product I wanted-- but it was the beginning I needed. A low-fidelity placeholder gave me just enough structure to see where I was going.
Just like those dial-up images from decades ago, we don't need perfect clarity to start moving in the right direction. Our best work comes not just from careful planning. It also comes from allowing ourselves to start with something imperfect and letting the details fall into place.
In design, as in life, the path to clarity often begins in blur.
---
# My Best Team Tool is Not Another App
> How real-time writing makes us truly agile
Published: 2024-11-26 - Author: jake - URL: https://withstoa.com/blog/my-best-team-tool-is-not-another

For years as a product manager, I wore my resistance to documentation like a badge of honor. It wasn't that I didn't care--I cared so deeply it kept me up at night. But, I'd seen too many "100-page requirement docs." They became digital paperweights, never opened after being made.
My shield? Two key principles of the Agile Manifesto:
- "Individuals and interactions over processes and tools"
- "Working software over comprehensive documentation"
I wielded these against the very idea of documentation.
At first, my documentation-light approach felt liberating:
- Discussions crackled
- Ideas evolved organically
- Nothing felt set in stone too early
But in our fast-moving, hybrid world, the cracks began to show.
Verbal communication alone was like trying to build a skyscraper with just a hammer.
Without clear writing, our brainstorm sessions would lead to confusion by morning.
#### My wakeup call was named Mandy
Enter Mandy, a program manager. Her ruthless clarity was like sandpaper against my "keep it fluid" philosophy. She kept pushing me and Stan, a junior PM I was mentoring, to write down our vision.
My responses? Pure poetry of deflection:
- "We need to keep the problem space open"
- "This is about iterative learning"
- "Documentation kills creativity"
The truth? I was protecting Stan, who was struggling. He couldn't write clearly and wouldn't take ownership. I wrapped my enabling behavior in fancy Agile platitudes.
Our team was drowning in ambiguity.
The shift to hybrid work meant casual chats could not patch our gaps in understanding.
I remember the day out of sheer desperation I did something simple that transformed my approach:
1. Opened a blank document
2. Shared my screen
3. Started writing live during our team meeting
The live writing didn't just capture our discussion--it elevated it and became a catalyst for clearer thinking. The document linked our current knowledge to future action.
#### My new reality
Now, as a founder, this lesson shapes everything we do. Writing isn't about controlling outcomes or being perfect. It's about:
- Creating shared understanding
- Enabling real collaboration
- Making space for creativity to build on itself
- Turning good ideas into great outcomes
In today's world, work moves at the speed of thought. Teams are more connected by pixels than by proximity. So, clarity isn't just nice to have--it's essential.
The simplest way to achieve clarity is often the best. Write it down, right now, together, in front of everyone.
To transform your team's collaboration start with a blank document. Watch as ideas crystallize, confusion clears, and your team aligns in real-time.
Sometimes, the best solution isn't to find something new. It's to find the courage to do something simple, together.
And to ensure there's no doubt about where we're going next.
---
# The Hard Truth I Will Not Ignore
> Being intent-driven is now central to my story
Published: 2024-11-21 - Author: jake - URL: https://withstoa.com/blog/the-hard-truth-i-will-not-ignore

I've long clung to a comforting lie: my career was accidental.
Success? Just a series of lucky breaks. A view that has shaped me for decades.
I grew up with privileges that I didn't fully recognize. At eight, I had a computer to tinker with--a rarity in the '80s. I could touch type before I could write cursive.
Each accomplishment in my life has felt like a happy accident.
I joined the cross-country team because I wasn't good enough at soccer. Yet somehow, our team won three state championships.
Never mind the pre-dawn runs, the blisters, the moments I pushed through when my lungs were on fire.
Easier to call it luck than acknowledge the work.
And then I made it through college, graduated with honors, landed an amazing job--all luck.
This mindset became my shield, my armor against my terrifying vulnerability of wanting something but failing to get it. If success was just luck, failure couldn't really hurt me.
But now I'm starting to see what I've had trouble admitting: success isn't accidental.
Looking ahead may seem daunting because we fear failure, but looking back, the hard work and small decisions that shape us are easy to gloss over in a simplified narrative of luck.
For me, that narrative first started to shift with my choice to build products for software developers. Joining DigitalOcean was no accident. It was an intentional step towards a personal mission to help people realize they could build anything they want.
But old patterns die hard, and after a while I again started attributing successes to luck, leaving room for any failures to be accidents.
[In May of this year](https://jakelevirne.com/2024/05/26/spec-driven-development-with-phind/), when I started to go deeper with AI assisted development tools, I was forced to confront this narrative head on. Accidents won't get me where we're going next. Even before software composition [had a name](https://tolacapital.com/2024/11/13/the-rise-of-the-software-composer-a-new-era-of-software-creation) and before [Cursor's release](https://changelog.cursor.sh/#037---composer-beta) of the eponymous composer functionality, I could see clearly that the way we build software is forever changed.
From that moment, I couldn't unsee it and every job opportunity that came my way felt rooted in the "traditional" way of developing software. I realized that I needed to start something new and intentional.
This realization was both terrifying and liberating. The thing I've feared for so long--setting clear goals and owning my choices-- planted the seed for [SpecStory](https://specstory.com/).
A company not born out of luck, but deliberate choice, even if I could fail; hell *maybe because I could fail*!
With hindsight, the same skills that made me successful in my career as an "accidental technologist"--adaptability, curiosity, technical aptitude--were actually carefully cultivated traits.
My journey to intentional founder hasn't been linear. Some days, I still catch myself defaulting to that old narrative of luck. The path still twists and winds. I'm far from reaching its end.
But our stories are about more than where we end up-- they're about how we choose to get there.
What I now know: the eight-year-old me, typing away at that first computer, wasn't just lucky.
He was building something.
He was building this. He was building *me*.
---
# Claude Artifacts for Rapid Synthesis of Customer Feedback
> Using Claude Artifacts to synthesize 60+ customer interview transcripts into actionable product insights.
Published: 2024-08-29 - Author: jake - URL: https://withstoa.com/blog/claude-artifacts-for-rapid-synthesis-of-customer-feedback
I've been working on a new startup idea for product managers who lead "teams of AI coders". I put that in quotes, because today AI coders like Cursor, Claude, and Phind aren't quite team members and require lots of hand holding from anyone driving them. But as we squint and look at our crystal ball it becomes pretty clear that agile squads of the future will have a mix of human and AI talent.
For this startup, [SpecStory](https://specstory.com), I've had 60+ conversations with engineers, product managers, and product development leaders on topics ranging from rubber duck debugging to the challenges of mentoring junior team members in the age of GenAI. There's gold in these interviews, and I've been going back over them scanning for insights. But with [Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them), there's a new way to quickly synthesize this feedback. Let's walk through the analysis step-by-step.
All of my feedback notes and transcripts are stored in Google Drive, so step one was to download them all locally. Easy enough-- just right-click on the folder with all of these notes and choose Download.

This downloads all these files as a single Zip, which was easy to extract. Looking inside the resulting folder, I see all the Google Docs have been downloaded as .docx files. I could try to feed all 60+ of these into Claude as context, but that seems unwieldy. Instead, let's just get the text out of all of these docs and put them into a single text file.
I have a basic understanding of Python so thought I'd write a little script to do the text extraction. But that would take too long... let's have Claude write it for us. This was my prompt:
> python script to extract all the text from all the docx files in the current directory. Mac terminal.
In mostly got it right in the first shot, though I did have to clarify:
> extract them all to a single long file
The last snag came when I followed this direction from Claude:
```
pip install python-docx
```
I got this error:
```
If you wish to install a Python library that isn't in Homebrew,
use a virtual environment:
python3 -m venv path/to/venv
source path/to/venv/bin/activate
python3 -m pip install xyz
```
But pasting it straight into Claude walked me through the steps of using a Python virtual environment. A minute later I was able to run the script, which produced a single text file of all the notes and transcripts from my user research interviews.
Starting a new Claude chat to clear the context, I dragged this file into the prompt and asked:
> I'm building [ducky.foo](http://ducky.foo/). It's a startup. We've pivoted a few times. But right now, our focus is on building a platform for product managers who lead hybrid human-AI engineering teams. Below is a large set of notes from many different conversations with engineers, product managers, and advisors.
> Read through it and identify the problems and challenges people are facing.
Claude dutifully produced a bulleted list of 10 pain points. I knew there were more, so I followed up with:
> What are some more challenges?
It gave me 15 more, for a total of 25 with some overlap and duplication. In one last step, I used Claude Artifacts to create a single doc by starting a new chat and prompting:
> Pull together all of these pain points into a single artifact, organizing them better and removing duplicates.
And I pasted in the full set of 25 items that Claude had originally produced. The final output was very helpful, but lost one of the key points in the process so I asked it to add it back in and ended up with this artifact:

There was further editing, refinement, and especially prioritization that I needed to do, but this was a great starting point for that and was much faster to create than hand-synthesizing all the points of feedback.
Have you used Claude to help define or build out your app or project?
---
# Best Practices for Aligning AI to your Technical Strategy
> Five best practices for keeping AI-generated code aligned with your team's technical strategy.
Published: 2024-05-09 - Author: jake - URL: https://withstoa.com/blog/best-practices-for-aligning-ai-to-your-technical-strategy
Developers rely more and more on AI tools. These tools make them more efficient, keep them in flow, and help them write better code. But as we come to lean on them, how do we ensure AI-generated code is aligned with our technical strategy, norms, and culture?

### The 5 Best Practices
We'll start by listing out the best practices and then spend the rest of the article digging in to the motivations and nuances behind them. So, diving right in:
1. Don't outsource code reviews or QA to AI tools.
2. Encapsulate architecture and technical design decisions into your codebase.
3. Make the use of AI a more public event.
4. Train developers on AI.
5. Use a mix of AI tools.
### What Alignment Means
First let's talk about what AI alignment means in the context of a software development organization. It's easiest to first think about human alignment in an org: that we're all pulling in the same direction. Each team member puts the overall goals of the organization on par with their own personal goals. Ideally we each find ways to express and achieve our personal desires while working together to build something bigger and better than we could on our own. Managers and leaders play a role in helping each team member find and re-find this alignment. If this alignment gets too out of whack, the developer or the company or both can decide to part ways. This alignment is a fine balance- rarely are organizations marching along a smooth path to a clear objective. So it's not just a matter of everyone getting in line. The best software organizations achieve alignment to a direction and vision while encouraging individuals to exercise their unique strengths in realizing that direction and vision even if sometimes that means getting out of line.
But I digress. Let's get more tactical and focus on technical alignment within a software development organization. This typically covers a more manageable set of things:
- System DesignMonolith, Microservices, ServerlessREST, Message-based, RPCArchitectural process (e.g. RFCs, ADRs)
- Components and DependenciesPreferred data stores and systemsPreferred cloud providersManaging dependencies
- Testing and QualityTesting strategy and requirementsTest in prod / staging / developmentTest-driven developmentUnit and integration testingCode reviewObservabilityProduct usage metricsDocumentation
- ScalabilityPerformance and load testing strategyAuto-scaling approachCurrent / projected real world usage metricsCost constraints
- Security and RiskVulnerability detection and remediationCode reviewUser data managementAccess control
- ToolingSource code managementAutomationPlanning
- Technical Assertions"This is the way we do things here."Coding style[Choose boring technology](https://boringtechnology.club/)API or UI first
- Leveling and AssessmentSkills matrixInterviewing / HiringLeveling / promotionPeer reviewPerformance management / firing
In most organizations, a combination of formal and informal processes play out every day in order to reinforce (or not) a given set of technical choices. Team meetings, code reviews, Slack conversations, comments on tickets, RFCs, planning processes, pair programming, and countless others. Nowadays there is another process happening with greater frequency during software development- the use of AI coding assistants and conversational UIs. This presents a great opportunity for us to re-evaluate our approach to ensuring technical alignment.
### Technical Alignment and AI
As a starting point, we can continue to use the best practices and processes we've already got in place since many of them take the code as the point of collaboration and governance, regardless of how that code got written in the first place (inspiration striking on a mountain top or copy/pasting from Stack Overflow). In many ways generative AI is just another tool for writing code. But we need to adapt our approach to account for five key changes that are coming about thanks to AI:
- The volume of code is about to increase dramatically - this will push the limits of our current approaches to technical alignment. Any process that relies on code reviews will become a bottleneck.
- Motives - the profit motive of AI providers can create misalignment. Though potentially true of any cloud or devtool provider, the scale and scope of AI's impact on your codebase makes it especially susceptible. Think about social media for an example where profit motive damaged our values. Not because of clearly labeled sponsored posts but because of the more insidious algorithms that over-optimized for the wrong outcome- engagement.
- Confidently wrong - because gen AI has a tendency to be confident whether it's right or wrong, we lose a signal we often get from human authors- "can you give this a quick look" vs. "i could really use your help with this"
- Unclear authorship - when code is written by AI but copy/pasted by a human we get a false signal on authorship. I may have a certain set of expectations of Joan when she's writing backend code that may not apply to the portions of code she's authored with the help of AI.
- GenAI features in your own applications - as we start using generative AI more and more in the applications we build, application behavior will become less predictable. These models have inherent non-determinism built in, and so deterministic testing strategies won't work.
### Diving in on the Best Practices
So let's look at five best practices we've been using for years and how we should think about them in the age of AI coding assistants and conversational UIs, especially given these new challenges.
### Don't outsource code reviews or QA to AI tools
Because there will be much more code, much more AI-generated code, and much more confidently wrong AI-generated code, quality checks like code reviews, automated testing, and even manual testing will become dramatically more important. If we rely exclusively on AI tools to perform these quality checks then we are just kicking the can of alignment down the proverbial road. At a minimum we should be using different AI tools to help us perform quality checks than the ones we use to author code (see best practice #5).
Since the rise of agile, we've pushed more parts of the traditional development process into quality checks. System design, security/risk assessments, technical assertions, and cultural norms are often enforced within code reviews or automated tests. On the positive side, this reduces the number control points for software validation and alignment. But on the negative side, if we cede control and understanding of these points to our tools (e.g. AI), they are no longer effective as human control points.
Create and reinforce a culture that assigns value, importance, and prestige to rigorously reviewing, understanding, and testing system changes, regardless of where they come from. Recognize the added challenge of increasing non-determinism in systems as generative AI is used not only for building software but also as a key component of these systems.
### Encapsulate architecture and technical design decisions into your codebase.
AIs today mainly use the current codebase along with developer prompts as their context when answering questions or suggesting code. This includes a lot of valuable content (READMEs and comments as well as the code itself), but misses many key inputs that are more ephemeral in nature (whiteboards, design docs, UI mockups, roadmaps, legacy dependencies, and team conversations).
With developers carefully prompting and closely guiding AI assistants, those ephemeral inputs can be taken into account. But as our use of AI scales, they can increasingly get overlooked resulting in code that strays from our technical norms- needlessly introducing new dependencies, making code less readable, introducing technical risks or security vulnerabilities, or impacting scalability.
Our first best practice above acts as a way to catch these issues after the fact, once code has been written but before it's been merged and deployed. But we should also strive to improve the context upon which AI assistants operate. ChatGPT, Copilot, Gemini, and others are outdoing each other by increasing the size of the context window. But that's only part of the battle; if we don't fill that context window or if we fill it with the wrong content, like outdated Google and Notion docs, we'll get suboptimal results (the old garbage in, garbage out issue). The knowledge contained within foundational models goes a long way to combat this. But it can't make up for missing or inaccurate company and organization-specific context.
What to do? We actually need a mechanism for "publishing" the parts of these ephemeral architectural artifacts that matter. Code, Config, and Tests all now get "published" to source control and can serve as context for AI prompting. If there are non-code inputs we want everyone to use for context, we should publish those as well to the same source control system. Open source projects do this already with files like [README.md](http://readme.md/), [ARCHITECTURE.md](http://architecture.md/), and [contributor guides](https://github.com/microsoft/vscode/wiki/How-to-Contribute). Other good approaches include the use of [RFCs](https://dzone.com/articles/how-to-write-rfcs-for-open-source-projects) (requests for comments) or [ADRs](https://adr.github.io/) (architectural decision records)- though both of these are typically point-in-time documents and not evergreen system descriptions.
In general, with these types of non-code documents, we'll face the inevitable challenge of keeping them up to date even as the system changes. The [Code as Documentation](https://martinfowler.com/bliki/CodeAsDocumentation.html) philosophy attempts to address this challenge by eschewing extraneous specifications, architecture docs, and non-code artifacts. But in a world where more and more of the code is generated using AI, we need to make the ongoing investment in maintaining human-authored versions of our intent. We might even imagine a day when most code is written by AI agents; in this future vision, specifications and architecture/design docs become the primary artifacts that we humans author and maintain.
### Make the use of AI a more public event
Today, AI coding assistants and conversational interfaces are mainly used in private by a single individual. While developers may occasionally share their sessions with others, its more common for them to engage with AI privately and then share their resulting work product- code, comments, or documentation.
Because of the signaling challenges of unclear authorship noted above, this approach is not ideal from an organizational perspective. When John submits a PR, It helps reviewers and colleagues to know how much thought and consideration John put into his work. Based on past interactions, colleagues can make some reasonable assumptions about where John is an expert, where he's more of a novice, where his strengths lie and where a more thorough review may be needed. Use of AI coding assistants can invalidate those assumptions.
Many great engineering organizations favor transparency in their work. For example, technical and product discussions in public Slack channels and shared docs are preferred over DMs and private conversations. This increased transparency leads to better results in two ways: 1) more likelihood that decisions will happen with full context and 2) communicating in the open brings more sharpness to our thoughts.
If we think of AI as just another tool, then it shouldn't matter whether developers engage with it publicly or privately… does it matter if teammates know you use VSCode vs. Emacs? No. But coding AIs are somewhere between just another tool and a full-fledged colleague. They certainly have the power to influence our thinking and resulting work product more than "just another tool" could. Given this, we should err on the side of collaborating with coding AIs more transparently.
Developers can face an emotional challenge when doing this- you can ask any question of AI with no judgement. Even if you feel you're expected to be the expert on a topic, you can safely ask an AI about the basics of that topic. Move all of those conversations into a public forum and a lot of that safety goes away. So a subtle and thoughtful approach is needed. Start by relying on another tried and true practice, pair programming, and extend it to include pair prompting. Incorporate AI into existing public channels through integrations like the [ChatGPT app for Slack](https://slack.com/blog/news/why-we-built-the-chatgpt-app-for-slack). And don't force all AI conversations to be public, but work to make it safer and more normalized for your team to ask and prompt AIs in more open settings.
### Train developers on AI
We often expect our developers to build expertise with their tools on their own. But this results in missed opportunities for creating more alignment across our team and with the AI agents they use. As noted, AI is more than just another tool. It's a productivity booster, a subtle influencer, a workflow change, and a potentially large dependency all rolled into one.
As team members gain benefits from their use of AI tools, ask them to reflect on their experiences and think about what works well, what doesn't, and what creates the potential for future challenges. Support brown bags and other forms of knowledge sharing among colleagues to improve everyone's mindful use of these tools. Even just planting the seeds of thoughtful usage with your team members can have a positive influence on alignment.
Don't shy away from documenting guidelines and best practices. If you don't want employees sharing proprietary code or secrets with AI bots, or want to limit usage to certain vetted AI tools, let them know. If you want to require them to use corporate accounts instead of personal accounts, make it so. New technology can be exciting to use, but it's important to put guardrails in place that align that usage with the needs of the organization.
Finally, ensure you've got support channels in place for the use of these tools. Setup a Slack channel where people can turn for help with guidelines and best practices. Create clear responsibilities for managers and other leaders to help everyone on the team to get the most out of AI.
### Use a mix of tools
While it will increase costs, using a mix of AI tools will help mitigate some of the effects of misalignment. Different tools, especially if they rely on different underlying models, can have different behaviors with the biases and errors of one sometimes canceling out or highlighting the biases of another. Specifically, avoid using the same tool you use for authoring code when reviewing code. Your code reviews should ideally be a human-heavy process anyway, but using a different AI tool (and model) to summarize and explain aspects of the code to a reviewer can augment the human review process.
Encourage developers on your team to also use multiple tools when designing, coding, or testing your system. If there ever is a true AI uprising, our only hope will be to pit AI vs. AI as we watch from a safe distance.
### Extend What's Working Today
In general, these recommendations are meant to extend engineering best practices that you're likely already following. The addition of AI tools into the mix perhaps just creates more urgency and need for scale. Another way to approach the technical alignment challenge is to ask yourself, "What people, processes, and tools would I need to add or change if my engineering org were to double in size next week?". Though it may take more than a week, change is coming. And the typical indicators of organizational scale, like engineering headcount growth, may not clearly reflect the size and scope of this coming change.
---
# Stack Overflow in the AI Age
> It's not about AI vs. human generated content. Developer communities need to embrace human plus AI.
Published: 2024-04-24 - Author: jake - URL: https://withstoa.com/blog/stack-overflow-in-the-ai-age
Stack Overflow started in 2008 and has helped millions of developers, myself included, get answers to their coding questions. But there's a sea change in the industry, with most developers now using or planning to use AI tools in their development processes. One experienced developer I interviewed said his process has changed more in the past 18 months than it had in the last 18 years.

### Stack Overflow's Policy on AI Generated Content
In the face of this transformation, Stack Overflow has taken a [strong stand](https://stackoverflow.com/help/ai-policy) on the role of AI generated content in the community- there's no place for it. And they go on to say, "Users who ask questions on Stack Overflow expect to receive an answer authored and vetted by a human." Whether this is true or not, we know from Stack Overflow's own research that AI is a tool that most developers value.
### AI is a Tool that Most Developers Value
Stack Overflow Developer [Survey](https://stackoverflow.co/labs/developer-sentiment-ai-ml/) 2023:
- 70% are already using or plan to use AI tools in their development process: 44% use AI tools now and 26% plan to soon.
- 77% feel favorable towards using AI tools as part of their development workflow
- 42% trust the accuracy of the output of AI tools used in their development workflow.
GitHub Copilot [Research](https://github.blog/2023-10-10-research-quantifying-github-copilots-impact-on-code-quality/) (2023) affirms and extends these findings:
- 85% of developers felt more confident in their code quality when authoring code with GitHub Copilot and GitHub Copilot Chat.
- Code reviews were more actionable and completed 15% faster with GitHub Copilot Chat.
- 88% of developers reported maintaining flow state with GitHub Copilot Chat because they felt more focused, less frustrated, and enjoyed coding more, too.
### A Community that Embraces AI
AI is a tool like IDEs or interpreted languages or coding frameworks, all of which have their detractors but none of which are banned from use by Stack Overflow. Instead of pitting humans vs. AI in the battle of who can provide the best answers to coding questions, we should reframe the conversation to ask "what should a human community of developers look like given the huge impact AI is having on software development?"
While there are some obvious answers, like creating tags and collectives for AI technology, there are also some less obvious challenges that such a community could help tackle:
- How do we work together to combine the speed of AI generated answers with the accuracy of well-vetted human content? ([Grounding](https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/overview))
- How do we ensure that less experienced developers and those new to the discipline can still have a path to learn and grow?
- How can we avoid the [death spiral](https://techxplore.com/news/2023-06-ai-death-spiral.html#google_vignette) of AI-generated content diminishing the effectiveness of underlying models?
- How do we keep AI services aligned with our goals as a community? ([Alignment](https://en.wikipedia.org/wiki/AI_alignment))
- Given the proliferation of AI tools for developers, how can we move effortlessly between them while maintaining the context and knowledge we've created along the way?
### Working Together to Achieve Augmented Intelligence
**Grounding**
[Grounding AI](https://www.moveworks.com/us/en/resources/blog/what-is-grounding-ai) refers to the process of linking abstract knowledge in AI systems to tangible, real-world examples. It's a set of techniques that can be used to reduce AI hallucinations and add source citing to AI-generated responses. Many AI tools are making rapid progress in grounding their answers through [RAG](https://research.ibm.com/blog/retrieval-augmented-generation-RAG) (retrieval-augmented generation) and other means. But a community of human developers could take this a step further- correcting AI content, up/down-voting answers, suggesting follow-ups or refinements, and vetting responses against real-world scenarios.
**Helping Novices**
This community engagement with AI can help in even more critical ways. While correcting and clarifying answers are important, it is perhaps even more important to help people ask good questions in the first place.
> "There are no right answers to wrong questions." - Ursula K. Le Guin
The Stack Overflow survey shows differences in sentiment towards AI tooling based on developer experience, which starts to hint at a potential split between more and less experienced developers. Research from [McKinsey](https://www.mckinsey.com/capabilities/mckinsey-digital/our-insights/unleashing-developer-productivity-with-generative-ai) and [Ness Digital Engineering](https://www.forbes.com/sites/forbesbusinessdevelopmentcouncil/2024/04/17/unlocking-the-future-how-generative-ai-is-revolutionizing-software-engineering/?sh=23420527185f) indicate that in practice, different developer groups have significantly different outcomes when using AI tools. The McKinsey research shows examples of AI tools reducing the time to complete certain tasks by up to 50% when those tools are used by experienced developers, but adding 7-10% to task completion time when those same tools are used by devs with less than a year of experience.
A widening gap between junior and senior developers doesn't bode well for the industry where these same junior developers are the engineering leaders of tomorrow. And more so, it's overly simplistic to bucket developers as "junior" vs. "senior". We're all novices **and** experts depending on the topic and the circumstances- lifelong learning is one of the most appealing aspects of developing software.
Given this, our community can come together to help each other interact with AI on any software topic as if each of us was an expert on that topic. For example:
- Experts who asked a similar question then asked one of these follow-ups...
- Most experts who received an answer similar to yours modified the generated code in the following ways...
- When exploring this topic, experts also often explored these related topics...
- The following foundational concepts may help you better understand this response...
- The following historical context may help you better understand this response...
- Rephrasing your prompts in the following way may elicit a more accurate answer...
- Experts who asked a similar question preferred results from the following AI tools/models...
While some of these will require experts to proactively edit and correct AI responses, most of them can be achieved just by observing how the experts among us get the best out of current AI tooling. This should make it easy for our community to grow and improve rapidly.
**Avoiding the Death Spiral**
Stack Overflow's policy on AI generated content talks about the need for quality- for answers to be "factual, relevant, and complete". On this point, there's no argument. The research, both qualitative and anecdotal, indicates that accuracy of AI-generated answers is a real issue. And though not explicitly called out in the policy, the risk of AI models degrading over time due to a lack of human-generated training content is real.
To avoid this accuracy death spiral, the answer is to make it easier for humans to refine and edit content for accuracy; to separate the wheat from the chaff. Using human authoring as the only factor in determining good vs. bad content is inefficient. Instead, we should use the full set of signals available to us as the community interacts together with all content (both human and AI generated) to quickly produce the high quality data needed to continually improve answers.
**Continually Aligning**
On a larger scale than any one specific question or answer, we need to be constantly vigilant when it comes to the use of AI. As software developers we build systems that can have a highly leveraged impact on society. If we don't ensure that the AI tools we use are [aligned](https://en.wikipedia.org/wiki/AI_alignment) with our values, we run the risk of incrementally eroding those values. The software systems we build need to be secure, fair, transparent, useful, and safe and we need to be able to rely on our tools not to thwart those characteristics.
AI will cause many of us to bump up a level of abstraction as we plan and build software. In some ways this is similar to the bump in abstraction much of the industry experienced with the wide adoption of interpreted languages. But in other ways, this new abstraction is dramatically different because there is more chance for us as developers to implement algorithms without sufficiently understanding or vetting them. This can create subtle but insidious biases or behaviors in our software.
As a community, one of the most important things we can do is come together to help each other ensure we're being mindful as we implement AI-generated suggestions. Specifically, the shape of AI, including its associated high compute costs, has concentrated the foundational technology in the hands of a small number of large companies (some of whom are actually deeply interdependent). Even if these players are not bad actors, they become susceptible to exploitation by bad actors, with potential for far reaching effects. One of the best counterbalances to this over-concentration is an independent community that can participate alongside AI tools to reinforce our preferences and values.
**Making Context and Knowledge Portable**
Finally, we see challenges arising from the proliferation of AI tools for developers. The situation is unique in that there are a small number of foundational models and APIs powering a dizzying array of AI developer experiences. While the hyper-concentration can result in the Alignment problems noted above, the proliferation of choice leads to problems of developer experience and ease of use.
Today, developers could easily use a dozen disparate AI tools for helping them in their work, from general purpose AI chat interfaces to coding or platform specific experiences. With each new interaction, it's up to the developer to provide context to these tools. Currently, the best approaches make use of the project codebase as a way to create better context for AI generated answers. But this misses many other useful contextual inputs like the questions I've asked in the past, the code I deleted or never used, and the documentation and notes I have outside of my codebase. It also results in IDEs like VSCode getting bogged down by an unending set of AI extensions that can't interact with each other.
A modern developer community is as much about helping each other as it is about helping ourselves. And in this world of fractured AI tooling experiences, we should think about making our context and our learning portable. As we use AI, we are building up an augmented memory and a personalized knowledge base. Some aspects of these can help others as they follow similar paths, but just as importantly these can be useful to our future selves. As we start, pause, and re-engage on projects its invaluable to be able to retrieve our learnings even if specific AI tools have changed underneath us.
### A Modern Software Development Community
It's not about AI vs. Human generated content. New tooling and new technological breakthroughs almost always result in more opportunity for developers to express themselves and to create. The easier it is to create, the more we build, and the more diverse the community of builders becomes. With the rapid changes we've seen in software development it's time for developer communities that embrace these changes. Stack Overflow arose in the midst of changes 16 years ago when cloud and mobile were revolutionizing our industry and so can no doubt [adapt](https://stackoverflow.blog/2023/07/27/announcing-overflowai/) to the impact of AI today. But if the weight of its past causes it to continue on the path of human **vs.** AI, other communities will arise to embrace human **plus** AI.
---