Worked Example

The raw idea

This is a normal starting point. It contains a user pain, a proposed solution, and a rough cadence. It is not yet a technical spec. It does not say who receives the email, what counts as an update, where data comes from, how unsubscribes work, what happens for inactive projects, or how success is verified.

If you hand this directly to a coding agent, the agent has to invent product rules, data boundaries, delivery timing, email content, and tests. Some of those inventions might be reasonable. That is exactly the problem: reasonable is not the same as agreed. The Spec Builder exists for this moment: it forces the rough idea into sections that expose missing decisions.

Step 1: Extract the product decision

Before writing the spec, separate the product decision from the implementation. Here, the product decision might be: "Active workspace members should receive a weekly summary of project changes they are allowed to see, unless they have opted out of product emails."

That sentence still needs product validation, but it is much stronger than the raw idea. It names recipients, cadence, permission sensitivity, and an opt-out rule. Those choices should come from the PRD or product owner, not from the implementer during coding.

Step 2: Name the implementation boundary

Now define where implementation can happen. In a real repo, this section would name exact files. For this example, assume the existing system has projects, project events, workspace members, email preferences, and a background job runner.

Step 3: Write testable requirements

Requirements should remove decisions that would otherwise be made during implementation. Use MUST only for acceptance-blocking behavior. The requirement IDs let reviewers discuss one line without arguing about the entire spec.

REQ-1: The system MUST send one weekly digest email to each active workspace member who has not opted out of product emails.
REQ-2: The digest MUST include only projects the recipient can access at send time.
REQ-3: The digest MUST include project events from the previous Monday 00:00 UTC through Sunday 23:59 UTC.
REQ-4: If a recipient has no visible project events for the period, the system MUST NOT send a digest.
REQ-5: The email MUST include an unsubscribe link that uses the existing email-preference mechanism.
REQ-6: The job SHOULD record sent, skipped-empty, skipped-opt-out, and failed-delivery counts.

Step 4: Describe the design surface

A spec does not have to dictate every class name, but it should identify the contracts that matter. For the digest, the risky parts are eligibility, permissions, date windows, email content, idempotency, and observability.

Step 5: Add examples

Examples expose hidden decisions. A weekly digest has obvious happy-path behavior, but the important examples are edge cases: no updates, private project visibility, opt-outs, deleted projects, and re-running a failed job.

Example A: visible updates
Given a workspace member can access Project Alpha
And Project Alpha has three events in the previous UTC week
When the weekly digest job runs
Then the member receives one digest listing those three events

Example B: permission filtering
Given a workspace member can access Project Alpha but not Project Beta
And both projects have events in the previous UTC week
When the weekly digest job runs
Then the member's digest includes Project Alpha events
And excludes Project Beta events

Example C: idempotent retry
Given a digest delivery record already exists for the member and week
When the weekly digest job is retried
Then no duplicate email is sent

Step 6: Make verification explicit

The final spec should tell the implementer how to prove the work. For agent work, this should be direct enough that the final report can list the exact command output and any manual checks.

Verification
- Unit tests cover recipient eligibility, opt-out skip, empty digest skip, permission filtering, and idempotent retry.
- Email preview renders HTML and plain-text versions.
- Job test verifies counters for sent, skipped-empty, skipped-opt-out, and failed-delivery.
- Manual check in staging sends a digest to a test workspace with two visible projects and one hidden project.
- Build, lint, and the existing notification test suite pass.

The final compact spec

# Technical Spec: Weekly Project Digest Email

Status: Draft
Owner: Product + Engineering

## Summary
Send active workspace members one weekly email summarizing visible project events from the previous complete UTC week.

## Problem
Users miss important project updates when they do not check the activity page regularly.

## Goal
Increase awareness of project activity without sending duplicate, private, or opt-out-violating email.

## Non-goals
- No new notification preference UI.
- No daily or real-time notifications.
- No permission model changes.

## Requirements
REQ-1: Send one weekly digest to active members who have not opted out.
REQ-2: Include only events from projects visible to the recipient at send time.
REQ-3: Use previous Monday 00:00 UTC through Sunday 23:59 UTC.
REQ-4: Do not send when there are no visible events.
REQ-5: Include an unsubscribe link using the existing preference mechanism.
REQ-6: Record sent and skipped counters.

## Design
- Query existing project event records.
- Reuse project activity visibility policy.
- Persist delivery records keyed by recipient, workspace, week start.
- Use existing email infrastructure.

## Acceptance examples
[Include examples A, B, and C from above.]

## Verification
[Include test and staging checks from above.]

What changed from the raw idea?

The final spec does not merely add detail. It assigns decisions to the right layer. Product owns the recipient and cadence decisions. Engineering owns the data source, idempotency, permissions, and verification. The coding agent or engineer receives a task with enough context to implement without inventing product policy.

That is the craft move. A good spec does not make the work large; it makes the work determinate.

Agent handoff excerpt

Once the spec is approved, the implementation prompt should be shorter, not longer. It can point to the spec, name the allowed files, and require a verification report.

Implement the Weekly Project Digest Email spec.

Use the existing notification job and email-template patterns.
Do not add notification preference UI.
Do not change project permission behavior.

Before finishing, run the notification unit tests and build.
Report files changed, verification output, deviations from the spec, and remaining risks.

GitHub's Copilot instruction docs and OpenAI's AGENTS.md docs both reinforce the value of persistent repository context. The task brief should avoid repeating permanent repo rules and focus on the change-specific decisions.