I once spent three days building a notification system.

Real-time WebSocket updates. Notification center with read/unread state. Badge counts. Persistence across sessions. It was clean, well-tested, well-reviewed code.

Then I showed it to the product team.

"Oh — we just meant a simple email when someone assigns a task. We don't need any of that in the app."

Three days. Gone. Not because the code was bad. Because I built the wrong thing.

This 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.

@spec-writer and @planner exist to catch this bug before you write the first function.

This is Part 6 of the copilot-workflow series.

The Architect's Blueprint Analogy

You wouldn't build a house without blueprints.

Not 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.

Software 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.

@spec-writer is your blueprint. @planner is your construction schedule. Neither one writes a line of code. Both prevent you from building the wrong thing.

The /spec Chatmode: Three Phases, One Command

The /spec chatmode orchestrates @spec-writer and @planner in sequence. Each phase gates the next — nothing proceeds without approval.

Here's what happens when you open the spec chatmode and describe what you want to build.

Phase 1: @idea-refiner — Sharpen Before You Specify

Before you write a spec, @idea-refiner helps you figure out what you actually want.

Raw idea: "I want to add notifications."

Refined idea (after the agent asks five sharpening questions):

• Who: task assignees, not managers
• What: email only, no in-app UI this sprint
• Success: assignee receives email within 30 seconds of assignment, 0 missed deliveries
• Not doing: unsubscribe management, notification preferences, real-time push

This conversation takes 3 minutes. It just saved you 3 days.

Phase 2: @spec-writer — Surface Every Assumption

With a clear direction, @spec-writer produces the spec. But before writing a single section, it does something critical:

ASSUMPTIONS I'M MAKING:
1. Email is via an external service, not self-hosted SMTP
2. Notifications only fire on task creation — not on updates or completion
3. Assignee email is always available (users have verified emails)
4. This is a backend-only change — no frontend work this sprint
→ Correct any of these before I continue.

Assumptions are where projects go wrong. Surfacing them explicitly — before writing the spec — gives you a chance to correct course while it costs nothing.

After confirmation, the full spec:

# Spec: Task Assignment Notifications

## Objective
Send an email to the task assignee within 30 seconds of assignment.
Success: zero missed deliveries, email arrives in inbox (not spam).

## Tech Stack
Node.js 22, Express, Prisma (PostgreSQL), Resend for email delivery.

## Commands
Build: npm run build
Test: npm test -- --coverage
Dev: npm run dev

## Project Structure
src/
  services/notification.ts   ← new file
  jobs/send-notification.ts  ← new file (BullMQ worker)
  routes/tasks.ts            ← modified (trigger on assignment)
tests/
  services/notification.test.ts
  jobs/send-notification.test.ts

## Testing Strategy
Unit: notification service (mock Resend client)
Integration: route handler triggers queue (real DB, mock queue)
E2E: not required this sprint

## Boundaries
Always: validate assignee email before enqueue, log all sends
Ask first: adding new email templates, changing delivery provider
Never: synchronous email delivery (always async via queue)

## Success Criteria
- [ ] Email arrives within 30s of task assignment in manual testing
- [ ] Zero missed deliveries in integration tests (100 consecutive)
- [ ] No email sent on task updates — only on initial assignment
- [ ] Failed delivery retried 3x with exponential backoff

## Open Questions
- None — assumptions confirmed above

This is the gate. The spec goes to the human. Nothing proceeds until it's approved.

Phase 3: @planner — Tasks You Can Actually Execute

With an approved spec, @planner produces the implementation order.

The key insight: vertical slices, not horizontal layers.

Most 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.

Vertical slices mean each task delivers a working piece of functionality:

## Task 1: Notification service with Resend integration
What: Create src/services/notification.ts that sends an email via Resend.
Acceptance:
- [ ] sendTaskAssignmentEmail(task, assignee) sends email via Resend API
- [ ] Failed sends throw NotificationError with error details
- [ ] Mock Resend client in tests — no real emails in test suite
Verification: npm test -- --grep "notification service"
Files: src/services/notification.ts, tests/services/notification.test.ts
Size: S

## Task 2: Queue worker for async delivery
What: Create src/jobs/send-notification.ts BullMQ worker.
Acceptance:
- [ ] Worker processes notification jobs from queue
- [ ] Retries 3x with exponential backoff on failure
- [ ] Logs success and failure with structured fields
Verification: npm test -- --grep "notification worker"
Dependencies: Task 1
Files: src/jobs/send-notification.ts, tests/jobs/send-notification.test.ts
Size: S

## Checkpoint: After Tasks 1-2
- [ ] All tests pass
- [ ] Notification sends correctly in isolation
- [ ] Review before proceeding

## Task 3: Wire assignment route to notification queue
What: Modify task assignment endpoint to enqueue notification.
Acceptance:
- [ ] POST /api/tasks/:id/assign enqueues notification job
- [ ] Notification NOT sent on task update — only on assignment
- [ ] Assignment succeeds even if queue is unavailable (fire-and-forget)
Verification: npm test -- --grep "task assignment"
Dependencies: Tasks 1, 2
Files: src/routes/tasks.ts, tests/routes/tasks.test.ts
Size: S

## Checkpoint: Complete
- [ ] All tests pass
- [ ] Email received within 30s in manual test
- [ ] No email on task update (verified manually)
- [ ] CI green — ready for /ship review

Three 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."

The Anti-Pattern This Prevents

Here's what happens without spec-first development:

1. You understand the requirement loosely
2. You start coding based on your interpretation
3. Three days in, you show someone
4. They say "oh, we meant something simpler" (or more complex)
5. You rewrite

The 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.

The 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.

Using /spec in Practice

For a new feature:

[In /spec chatmode]
I want to add CSV export for the task list.

The chatmode guides you through idea refinement, spec writing, and task breakdown. You approve each phase. Nothing gets implemented until the plan is complete.

For a bug with complex root cause:

[In /spec chatmode]
I need to redesign the task search — it's timing out on tables over 10k rows.
This needs a proper plan before I touch the index structure.

For a refactor:

[In /spec chatmode]
The auth middleware is 400 lines and doing too many things.
I want to split it into separate concerns but keep behavior identical.

What @doubter Adds

After @planner produces the task list, there's one more agent worth invoking for high-stakes decisions: @doubter.

@doubter is an adversarial reviewer — it finds what's wrong with your plan. Not "is this good?" but "what could go wrong?"

@doubter Here is my implementation plan for task assignment notifications.
ARTIFACT: [paste the task list]
CONTRACT: Zero missed deliveries, email within 30s, no sync blocking of the assignment API

It 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?"

That's a decision you want to make in the plan, not discover in production.

The Full Workflow in One Picture

Vague idea
    │
    ▼
@idea-refiner → sharp concept + Not-Doing list
    │ human approves direction
    ▼
@spec-writer → assumptions surfaced + spec written
    │ human approves spec
    ▼
@planner → ordered tasks with acceptance criteria
    │ human approves plan
    ▼
@test-engineer → failing tests (Prove-It)
    │
    ▼
Implement → make tests pass
    │
    ▼
/ship chatmode → SHIP / DO NOT SHIP verdict
    │
    ▼
Merge

Every arrow is a gate. Every gate has a human approval. The code is the last step, not the first.

Get the Template

@spec-writer, @planner, @idea-refiner, @doubter, and the /spec chatmode are all included.

👉 github.com/panditAbhis/copilot-workflow

Next (and final) in the series: Part 7 — A complete session walkthrough. Real feature, all 8 steps, start to merge.

Series navigation