{"slug": "stop-building-the-wrong-thing-how-i-use-spec-writer-and-planner-before-writing-a", "title": "Stop Building the Wrong Thing: How I Use @spec-writer and @planner Before Writing a Single Line of Code", "summary": "A developer wasted three days building a complex notification system with WebSocket updates and badge counts, only to learn the product team simply wanted an email when a task was assigned. To prevent this costly mistake, the developer created `@spec-writer` and `@planner`, tools that surface assumptions and produce a detailed specification before any code is written. The `spec` chatmode orchestrates both tools in sequence, requiring approval at each phase to ensure the right thing is built from the start.", "body_md": "I once spent three days building a notification system.\n\nReal-time WebSocket updates. Notification center with read/unread state. Badge counts. Persistence across sessions. It was clean, well-tested, well-reviewed code.\n\nThen I showed it to the product team.\n\n\"Oh — we just meant a simple email when someone assigns a task. We don't need any of that in the app.\"\n\nThree days. Gone. Not because the code was bad. Because I built the wrong thing.\n\nThis is the most expensive bug in software development — and it's never caught by tests, never caught by code review, never caught by a security audit. It's caught by showing someone the finished product and watching their face.\n\n`@spec-writer`\n\nand `@planner`\n\nexist to catch this bug before you write the first function.\n\nThis is Part 6 of the **copilot-workflow** series.\n\nYou wouldn't build a house without blueprints.\n\nNot because architects are bureaucratic. Because building walls is expensive and tearing them down is more expensive. A blueprint catches design problems when they're still just pencil lines — before concrete gets poured.\n\nSoftware is the same. The cost of changing a requirement on paper is five minutes. The cost of changing it in working code is hours. The cost of changing it in deployed production code with real users depending on it is days or weeks.\n\n`@spec-writer`\n\nis your blueprint. `@planner`\n\nis your construction schedule. Neither one writes a line of code. Both prevent you from building the wrong thing.\n\nThe `/spec`\n\nchatmode orchestrates `@spec-writer`\n\nand `@planner`\n\nin sequence. Each phase gates the next — nothing proceeds without approval.\n\nHere's what happens when you open the `spec`\n\nchatmode and describe what you want to build.\n\nBefore you write a spec, `@idea-refiner`\n\nhelps you figure out what you actually want.\n\nRaw idea: \"I want to add notifications.\"\n\nRefined idea (after the agent asks five sharpening questions):\n\nThis conversation takes 3 minutes. It just saved you 3 days.\n\nWith a clear direction, `@spec-writer`\n\nproduces the spec. But before writing a single section, it does something critical:\n\n```\nASSUMPTIONS I'M MAKING:\n1. Email is via an external service, not self-hosted SMTP\n2. Notifications only fire on task creation — not on updates or completion\n3. Assignee email is always available (users have verified emails)\n4. This is a backend-only change — no frontend work this sprint\n→ Correct any of these before I continue.\n```\n\nAssumptions are where projects go wrong. Surfacing them explicitly — before writing the spec — gives you a chance to correct course while it costs nothing.\n\nAfter confirmation, the full spec:\n\n```\n# Spec: Task Assignment Notifications\n\n## Objective\nSend an email to the task assignee within 30 seconds of assignment.\nSuccess: zero missed deliveries, email arrives in inbox (not spam).\n\n## Tech Stack\nNode.js 22, Express, Prisma (PostgreSQL), Resend for email delivery.\n\n## Commands\nBuild: npm run build\nTest: npm test -- --coverage\nDev: npm run dev\n\n## Project Structure\nsrc/\n  services/notification.ts   ← new file\n  jobs/send-notification.ts  ← new file (BullMQ worker)\n  routes/tasks.ts            ← modified (trigger on assignment)\ntests/\n  services/notification.test.ts\n  jobs/send-notification.test.ts\n\n## Testing Strategy\nUnit: notification service (mock Resend client)\nIntegration: route handler triggers queue (real DB, mock queue)\nE2E: not required this sprint\n\n## Boundaries\nAlways: validate assignee email before enqueue, log all sends\nAsk first: adding new email templates, changing delivery provider\nNever: synchronous email delivery (always async via queue)\n\n## Success Criteria\n- [ ] Email arrives within 30s of task assignment in manual testing\n- [ ] Zero missed deliveries in integration tests (100 consecutive)\n- [ ] No email sent on task updates — only on initial assignment\n- [ ] Failed delivery retried 3x with exponential backoff\n\n## Open Questions\n- None — assumptions confirmed above\n```\n\n**This is the gate.** The spec goes to the human. Nothing proceeds until it's approved.\n\nWith an approved spec, `@planner`\n\nproduces the implementation order.\n\nThe key insight: **vertical slices, not horizontal layers**.\n\nMost developers build horizontally: all database first, then all API, then all frontend. This means you have no working feature until everything is done. If something is wrong with the design, you discover it at the end.\n\nVertical slices mean each task delivers a working piece of functionality:\n\n```\n## Task 1: Notification service with Resend integration\nWhat: Create src/services/notification.ts that sends an email via Resend.\nAcceptance:\n- [ ] sendTaskAssignmentEmail(task, assignee) sends email via Resend API\n- [ ] Failed sends throw NotificationError with error details\n- [ ] Mock Resend client in tests — no real emails in test suite\nVerification: npm test -- --grep \"notification service\"\nFiles: src/services/notification.ts, tests/services/notification.test.ts\nSize: S\n\n## Task 2: Queue worker for async delivery\nWhat: Create src/jobs/send-notification.ts BullMQ worker.\nAcceptance:\n- [ ] Worker processes notification jobs from queue\n- [ ] Retries 3x with exponential backoff on failure\n- [ ] Logs success and failure with structured fields\nVerification: npm test -- --grep \"notification worker\"\nDependencies: Task 1\nFiles: src/jobs/send-notification.ts, tests/jobs/send-notification.test.ts\nSize: S\n\n## Checkpoint: After Tasks 1-2\n- [ ] All tests pass\n- [ ] Notification sends correctly in isolation\n- [ ] Review before proceeding\n\n## Task 3: Wire assignment route to notification queue\nWhat: Modify task assignment endpoint to enqueue notification.\nAcceptance:\n- [ ] POST /api/tasks/:id/assign enqueues notification job\n- [ ] Notification NOT sent on task update — only on assignment\n- [ ] Assignment succeeds even if queue is unavailable (fire-and-forget)\nVerification: npm test -- --grep \"task assignment\"\nDependencies: Tasks 1, 2\nFiles: src/routes/tasks.ts, tests/routes/tasks.test.ts\nSize: S\n\n## Checkpoint: Complete\n- [ ] All tests pass\n- [ ] Email received within 30s in manual test\n- [ ] No email on task update (verified manually)\n- [ ] CI green — ready for /ship review\n```\n\nThree tasks. Each one completable in a focused session. Each one leaves the system working. No XL tasks, no guesswork, no \"figure it out as you go.\"\n\nHere's what happens without spec-first development:\n\nThe spec doesn't add time to a project. It removes rework. The 15 minutes it takes to write a spec routinely saves 3-8 hours of misguided implementation.\n\nThe task breakdown saves a different kind of time: it stops you from building in the wrong order, then discovering a dependency you should have built first.\n\n**For a new feature:**\n\n```\n[In /spec chatmode]\nI want to add CSV export for the task list.\n```\n\nThe chatmode guides you through idea refinement, spec writing, and task breakdown. You approve each phase. Nothing gets implemented until the plan is complete.\n\n**For a bug with complex root cause:**\n\n```\n[In /spec chatmode]\nI need to redesign the task search — it's timing out on tables over 10k rows.\nThis needs a proper plan before I touch the index structure.\n```\n\n**For a refactor:**\n\n```\n[In /spec chatmode]\nThe auth middleware is 400 lines and doing too many things.\nI want to split it into separate concerns but keep behavior identical.\n```\n\nAfter `@planner`\n\nproduces the task list, there's one more agent worth invoking for high-stakes decisions: `@doubter`\n\n.\n\n`@doubter`\n\nis an adversarial reviewer — it finds what's wrong with your plan. Not \"is this good?\" but \"what could go wrong?\"\n\n```\n@doubter Here is my implementation plan for task assignment notifications.\nARTIFACT: [paste the task list]\nCONTRACT: Zero missed deliveries, email within 30s, no sync blocking of the assignment API\n```\n\nIt might surface: \"Task 3 says assignment succeeds even if queue is unavailable — but if the queue is unavailable for 30 minutes, those notifications are silently lost. Is that acceptable, or do you need a dead-letter queue?\"\n\nThat's a decision you want to make in the plan, not discover in production.\n\n```\nVague idea\n    │\n    ▼\n@idea-refiner → sharp concept + Not-Doing list\n    │ human approves direction\n    ▼\n@spec-writer → assumptions surfaced + spec written\n    │ human approves spec\n    ▼\n@planner → ordered tasks with acceptance criteria\n    │ human approves plan\n    ▼\n@test-engineer → failing tests (Prove-It)\n    │\n    ▼\nImplement → make tests pass\n    │\n    ▼\n/ship chatmode → SHIP / DO NOT SHIP verdict\n    │\n    ▼\nMerge\n```\n\nEvery arrow is a gate. Every gate has a human approval. The code is the last step, not the first.\n\n`@spec-writer`\n\n, `@planner`\n\n, `@idea-refiner`\n\n, `@doubter`\n\n, and the `/spec`\n\nchatmode are all included.\n\n👉 [github.com/panditAbhis/copilot-workflow](https://github.com/panditAbhis/copilot-workflow)\n\n**Next (and final) in the series:** Part 7 — A complete session walkthrough. Real feature, all 8 steps, start to merge.\n\n**Series navigation**", "url": "https://wpnews.pro/news/stop-building-the-wrong-thing-how-i-use-spec-writer-and-planner-before-writing-a", "canonical_source": "https://dev.to/panditabhis/stop-building-the-wrong-thing-how-i-use-spec-writer-and-planner-before-writing-a-single-line-of-1jd0", "published_at": "2026-06-12 14:17:13+00:00", "updated_at": "2026-06-12 14:41:40.699246+00:00", "lang": "en", "topics": ["ai-tools", "ai-products", "ai-agents", "large-language-models", "generative-ai"], "entities": ["@spec-writer", "@planner", "copilot-workflow"], "alternates": {"html": "https://wpnews.pro/news/stop-building-the-wrong-thing-how-i-use-spec-writer-and-planner-before-writing-a", "markdown": "https://wpnews.pro/news/stop-building-the-wrong-thing-how-i-use-spec-writer-and-planner-before-writing-a.md", "text": "https://wpnews.pro/news/stop-building-the-wrong-thing-how-i-use-spec-writer-and-planner-before-writing-a.txt", "jsonld": "https://wpnews.pro/news/stop-building-the-wrong-thing-how-i-use-spec-writer-and-planner-before-writing-a.jsonld"}}