Here's a pattern I use while vibe coding: * **Start with a "loose" prompt**. For example: "Make me a GTD app, using React Native, with a Supabase backend. It should have projects and next actions, every NA should be associated with a project". * **Iterate** - both on functionality (e.g. adding user management, a "waiting for", email summaries), on the interaction design (how tables are represented), on visuals (make it wider/narrower). I figure out how I want the product to look like as iterate. * **Retrofit the spec** At the end of the entire process, prompt v0 to give me the prompt that would yield this product in one shot. At the bottom of this I'm attaching the spec that got created that way. And lo and behold, the resulting app looks... quite different! ![[GTD-1.png]] *The iterated version* ![[GTD-2.png]] *One-shotted version from spec* ### All specs have gaps I've been a PM for over a decade. The PRD that v0 generated is actually *relatively* tight. I've seen a lot worse -- this meme is 20 years old! ![[Specs.png]] The gaps could be mitigated with mocks, and you can make it a lot tighter, but to make it at 100% fidelity, including what happens in each error state, you'd have to... just write the code! ### The gaps are a feature, not a bug Just like "thermodynamics is explained by statistical mechanics" (Douglas Hofstadter), the PRD is a useful abstraction for the code. It can't be definitive. It's a more useful artifact to talk about when discussing with VPs, designers. Think of it like connect-the-dots, there's an infinite ways to interpolate these points to make it a dinosaur, but it'll always be a dinosaur: ![[Specs-2.png]] ### The conversion is lossy both ways When we translate spec to code, it should ostensibly be non-lossy. Like you could verify if it's "up to spec". A good designer will do it and be on the dev team's case, too. When we translate code to spec it's *inherently* lossy because we're going back to the points, and there might be something that we liked in that particular interpolation that's not reflected. And again, the same spec can be implemented in infinite ways (the looser the spec, the more degrees of freedom). ### Specs are sometimes harder to read than their results It takes an engineer or to read through a spec and imagine how the product would look like. Most humans would feel more comfortable looking at the result and saying "yeah that looks right" (mocks close most of this gap). Same with laws, it's actually hard to read the law and figure out what its consequences will be - it's much easier to live in a society and observe the impact on the behavior. Even with models, for all the descriptions of a model spec, or reading system prompts, it's much easier to see the model in the wild and understand the "vibe" of it. I suspect this is for the same reason few-shotting is a good prompting technique, it's harder for system 1 to grok the abstract rules than to intuit the pattern from examples. ### Specs are defined iteratively Even before vibe coding days, a good PM doesn't make a PRD that is *too* tight, for a few reasons: * The reality is that there's some amount of information that's going to emerge only when you look at the explorations, when things come in front of you * You want to let designers (and ultimately engineers) to have some part in connecting the dots * You want to save your brain cycles for the more important parts This is on steroids in vibe coding days. Trying to create the below spec from the first go feels both exhausting and unproductive. #published 2025-06-08 ---- ## Product Requirements Document: GTD Application **1. Introduction** This document outlines the requirements for a web application designed to help users implement the "Getting Things Done" (GTD) productivity methodology. The application provides tools for capturing, organizing, and reviewing tasks, projects, and other commitments. It leverages a modern web stack for a reactive user experience and uses a backend service for data persistence and user management. **2. Goals** * Provide a digital platform for users to manage their tasks and projects according to GTD principles. * Enable secure user authentication and data isolation. * Offer dedicated sections for core GTD lists: Next Actions, Projects, Waiting For, and Areas of Focus. * Allow users to easily view, add, edit, and organize their GTD items. * Provide data export/review capabilities through JSON viewing and email reports. * Deliver a clean, intuitive, and responsive user interface. **3. User Stories / Features** * **3.1. Authentication:** * As a user, I want to be able to sign up for a new account. * As a user, I want to be able to log in to my existing account. * As a user, I want my session to persist so I don't have to log in repeatedly. * As a user, I want my data to be private and only accessible after logging in. * As a user, I want to see my user profile information (e.g., email, avatar). * As a user, I want to be able to log out. * **3.2. Dashboard & Navigation:** * As a user, I want a central dashboard or starting page upon login. * As a user, I want clear navigation, likely via a sidebar, to access different sections of the application (Next Actions, Projects, etc.). * As a user, I want consistent page titles reflecting the current section. * As a user, I want a consistent layout across the application's main views. * **3.3. Next Actions Management:** * As a user, I want to view a list of all my Next Actions. * As a user, I want to add new Next Actions with relevant details (description, possibly context, project link, due date). * As a user, I want to edit existing Next Actions directly within the list view (inline editing). * As a user, I want to mark Next Actions as complete or possibly defer them. * As a user, I want to delete Next Actions. * As a user, I want to reorder my Next Actions (potentially via drag-and-drop). * **3.4. Projects Management:** * As a user, I want to view a list of all my Projects. * As a user, I want to add new Projects with relevant details (name, desired outcome). * As a user, I want to edit existing Projects. * As a user, I want to mark Projects as complete or possibly put them on hold. * As a user, I want to delete Projects. * As a user, I may want to associate Next Actions with specific Projects. * **3.5. Waiting For Management:** * As a user, I want to view a list of items I am waiting for from others. * As a user, I want to add new "Waiting For" items (description, person delegated to, follow-up date). * As a user, I want to edit existing "Waiting For" items. * As a user, I want to mark "Waiting For" items as received/resolved. * As a user, I want to delete "Waiting For" items. * **3.6. Areas of Focus Management:** * As a user, I want to define and view my high-level Areas of Focus or Responsibility. * As a user, I want to add new Areas of Focus. * As a user, I want to edit existing Areas of Focus. * As a user, I want to delete Areas of Focus. * **3.7. Data Viewing & Export:** * As a user, I want a dedicated view to see my raw GTD data in JSON format. * As a user, I want the ability to trigger an email report containing my GTD data summary. * **3.8. UI/UX Enhancements:** * As a user, I want the application's favicon to dynamically update, possibly indicating pending actions or application state. * As a user, I expect the application to use a modern UI theme and components. **4. Non-Functional Requirements** * **4.1. Technology Stack:** The application must be built using Next.js (App Router), TypeScript, Supabase (Backend/Database/Auth), Shadcn UI (Component Library), and Tailwind CSS (Styling). * **4.2. Persistence:** All user data (Actions, Projects, etc.) must be securely persisted in the Supabase database. * **4.3. Security:** Authentication must be handled securely by Supabase Auth. Data access must be restricted to the logged-in user (likely via Supabase Row Level Security). * **4.4. Usability:** The interface should be intuitive and follow common web application patterns. Inline editing and drag-and-drop (where applicable) should enhance ease of use. * **4.5. Responsiveness:** The application should be usable on various screen sizes (desktop, tablet, mobile). * **4.6. Maintainability:** Code should be well-organized into logical directories (pages/routes, components, library functions, types). TypeScript should be used for type safety. **5. Design & UI** * Utilizes the Shadcn UI component library, providing pre-built but customizable components (buttons, tables, inputs, etc.). * Styled with Tailwind CSS utility classes. * Features a theme provider for consistent styling. * Employs reusable table components (`BaseTable`, `ActionTable`, `ProjectTable`) with features like inline editing (`EditableCell`) and drag-and-drop (`DraggableTable`). * Uses a sidebar (`Sidebar`) for primary navigation within a dashboard layout (`DashboardLayout`). **6. Data Model (Inferred - Requires verification from `lib/types.ts`)** * **User:** Handled by Supabase Auth (id, email, etc.). * **Project:** Likely includes fields like `id`, `user_id`, `name`, `description`, `status`, `created_at`, `updated_at`. Possibly an `order` field. * **Action (Next Action):** Likely includes fields like `id`, `user_id`, `description`, `status` (e.g., 'next', 'completed'), `project_id` (nullable FK), `context` (nullable), `due_date` (nullable), `created_at`, `updated_at`. Possibly an `order` field. * **WaitingFor:** Likely includes fields like `id`, `user_id`, `description`, `delegated_to` (nullable), `follow_up_date` (nullable), `status`, `created_at`, `updated_at`. * **AreaOfFocus:** Likely includes fields like `id`, `user_id`, `name`, `description`, `created_at`, `updated_at`. **7. Technical Stack Summary** * **Framework:** Next.js (v13+ with App Router) * **Language:** TypeScript * **Backend & Database:** Supabase * **Authentication:** Supabase Auth * **UI Library:** Shadcn UI * **Styling:** Tailwind CSS * **State Management:** React Context (`AuthContext`, `GTDContext`) * **Email:** Resend * **Package Manager:** pnpm * **Deployment:** Likely Vercel (presence of `vercel.json`)