How to Turn a Vague App Idea Into a Clear Spec

TL;DR

Wayfinder turns a broad, uncertain software idea into a decision-complete specification by exploring the codebase and questioning the project lead about unresolved choices. The demonstrated workflow maps a low-friction short-video creator for an existing course video manager, covering data modeling, vertical rendering, burned-in captions, and potential publishing to TikTok and YouTube Shorts without implementing the feature yet.

Transcript

What's up, pals? How we doing? I've not got long. I've got about an hour to chat about Wfinder. I'm uh I'm kind of excited about this one. It's an absolute banger. The tool's really fun and I'm just going to jump in straight away, start using it. Wavefinder for those who don't know is a um it's a sort of evolution of the grill me skill and it's a w... Read More

Key Insights

• Wayfinder is a pre-specification tool that explores a codebase and questions the project lead to transform a broad requirement into a map of resolved decisions. Its immediate goal is not working code, but a specification-ready understanding of the destination and the path required to reach it.
• The destination of the demonstrated Wayfinder session is a decision-complete specification for a short-video creator inside an existing course video manager. Implementation is explicitly outside the session's scope, allowing attention to remain on product boundaries, architectural choices, prior art, and unresolved requirements.
• The proposed short videos are existing video records with a distinguishing attribute rather than an entirely separate entity. Reusing the current videos table could preserve established application logic while enabling different presentation, processing, and publishing behavior for vertical portrait clips.
• Short-video creation is intended to have extremely low friction and no required relationship to a pitch. Pitches currently package and plan more expensive long-form videos, while the desired short-video flow should let the creator act immediately after having an idea.
• The initial publishing targets are TikTok and YouTube Shorts. Instagram is not an immediate priority because the creator reports having no following there, although researching multiple platform integrations remains valuable because database-backed content could potentially be distributed to additional platforms cheaply.
• The rendering pipeline needs to produce vertical videos with burned-in subtitles or captions. A previous workflow already used a Remotion project and a command-line process that selected a recently updated OBS recording and added subtitles, providing prior art that may be extracted from a deprecated monorepo.
• The key to keeping an agent aligned during planning is active human leadership. The creator argues that the project lead must drive the session, monitor the model, answer its questions, and prevent drift instead of passively expecting skills or guardrails to maintain direction automatically.
• The broader development flow moves from Wayfinder to a specification, then to tickets, implementation, and code review. Wayfinder is especially useful when the idea contains enough uncertainty and scope that reaching an implementable plan will probably require more than one coding session.

Questions & Answers

Q: What is Wayfinder used for in software development?

Wayfinder is used during the pre-specification stage to turn a broad and uncertain software idea into a decision-complete map. It first investigates the surrounding codebase, discovers available structures and prior work, and then questions the project lead about unresolved choices. Its output is intended to support a later specification, not to implement the requested feature during the mapping session.

Q: How does Wayfinder turn a vague idea into a specification?

Wayfinder begins by exploring the repository and grounding the request in the existing application. It then identifies a frontier of open decisions and breaks the broad requirement into smaller, focused grilling sessions. The project lead answers questions about scope, data relationships, user experience, integrations, and prior art until the result is sufficiently resolved to convert into a formal specification.

Q: How should short videos fit into the existing video data model?

The emerging decision is to represent a short video as an existing video record with a different attribute, using the same videos table rather than creating a wholly separate entity. The transcript notes that this attribute must support proper display in tables and enable different ways to process, present, render, and publish the content across short-video platforms.

Q: Should short videos require a pitch before creation?

Short videos should not require a pitch relationship in the proposed workflow. Pitches are described as packaging and planning for longer-form videos that are more expensive to create and need greater preparation. By contrast, the desired short-video experience should be highly immediate, allowing the creator to act on an idea without first completing a formal planning stage.

Q: What should the short-video rendering pipeline produce?

The rendering pipeline should turn source material into a vertical portrait video with burned-in subtitles or captions. The course video manager may reuse prior work from a Remotion project in the deprecated Total TypeScript monorepo. That earlier workflow used a command-line process to select a recently updated OBS video and add subtitles, though the creator notes that it needed tuning.

Q: Which publishing platforms are included in the proposed scope?

TikTok and YouTube Shorts are the principal platforms identified for the specification. The creator also wants research into what other platforms expose and how easily they can be integrated. Instagram is not an immediate focus because the creator says there is no following there, but broader distribution may become inexpensive once the content and publishing data exist in the database.

Q: How can a project lead stop an AI agent from drifting during planning?

The project lead should actively supervise and direct the planning conversation. The transcript frames the human as the lead and the agent as the junior, meaning the human must monitor the work, answer questions concretely, correct mistaken recommendations, and keep the destination clear. Skills and guardrails assist the process, but they do not replace engaged leadership during the planning phase.

Q: What workflow follows a completed Wayfinder session?

After Wayfinder creates the map, the next step is to convert that map into a specification. The specification is then transformed into implementation tickets, followed by implementation and code review. The creator distinguishes this process from immediate coding because a large, uncertain idea may require more than one coding session, making a durable specification useful for resuming work later.

Summary & Key Takeaways

• Wayfinder operates before specification and implementation. It explores the existing codebase, identifies the frontier of unresolved decisions, and conducts a focused grilling session with the project lead. The intended output is a decision-complete map that can be converted into a specification and handed to an implementation agent during later coding sessions.

• The demonstration applies Wayfinder to a proposed short-video creator inside an existing course video manager. Key product questions include whether short videos reuse the current videos table, whether they require pitches, how they appear in the interface, and how creators can begin recording or editing with extremely low friction.

• The emerging scope includes vertical portrait rendering, burned-in subtitles, and potential publishing to TikTok and YouTube Shorts. Existing Remotion code in a deprecated Total TypeScript monorepo may provide prior art for the rendering pipeline. The planned workflow proceeds from Wayfinder to specification, tickets, implementation, and code review.