The spec is the job

I spent 20 years as a product person believing that the hard work was execution. Writing the spec was the warm-up. Building the thing was the job.

I was wrong.

When you work with AI agents, the spec is the build. The words you write become the system's understanding of what you want. And the gap between what you wrote and what you meant shows up immediately, in the output, without mercy.

---

What vague specs produce

Here is a real example from our Aralyx project — a 300k SEK trading platform.

Early spec: "Build an admin panel with cycle management."

What Bishop (our CTO agent) built: a list view with CRUD operations and some filtering. Technically correct. Missing everything that mattered: the approval flow, the status transitions, the edge case where a cycle gets partially filled.

New spec: "The admin panel cycle view shows all open cycles. A cycle has four states: draft, open, closed, settled. An operator can transition: draft→open, open→closed. Closed→settled requires a settlement amount input and a confirm dialog. Cycles cannot be deleted, only cancelled (which is a soft-state, filter out by default)."

Bishop got it right the second time. Not because he got smarter. Because I got clearer.

The bottleneck was never execution. It was me.

---

What a good spec looks like

Three tests:

1. Can I hand this to someone who knows nothing about the project and have them deliver the right thing?

If the answer is no, the spec is incomplete. AI agents don't have your mental model. They have your words.

2. Does it describe outcomes, not steps?

Bad: "Add validation to the form."
Good: "The email field must reject non-email strings and show an inline error: 'Enter a valid email address.' Validation fires on blur, not on submit."

Steps describe what to do. Outcomes describe what done looks like.

3. Does it specify the edge cases?

Most bugs live in the transitions and the edge cases. What happens when the list is empty? What happens when a user hits back mid-flow? What happens at midnight when the cron job runs and a user is mid-session?

If the spec doesn't answer these, the agent will guess. Sometimes well, sometimes not.

---

Three real examples from kerber.ai

Example 1: Oracle's Sentry sweep spec
Vague: "Check Sentry for bugs."
Good: "Review the top 10 unresolved issues in stardust-meet Sentry org sorted by event count. For each issue with >50 events and lastSeen within 7 days: create a Paperclip issue with the Sentry ID, event count, root cause hypothesis, and a specific code location hypothesis. Assign to Morpheus. Do not create duplicate issues — check if an existing Paperclip issue references the same Sentry ID before creating."

The second spec took me 10 minutes to write. The output was 6 actionable bug issues with exact Sentry IDs and root cause analysis.

Example 2: Tank's community setup spec
Vague: "Set up the Discord community."
Good: "Create a welcome post in #general that: (1) introduces StarDust in 2-3 sentences using the approved brand voice, (2) asks members one intro question: 'What's the last thing you were obsessed with?', (3) pins the post, (4) posts a second message listing known issues with the current beta build."

Result: a Discord that felt curated and intentional from day one.

Example 3: Bishop's CI spec
Vague: "Get CI working."
Good: "The Aralyx monorepo CI must: run on every PR to main, run `npm test` in packages/api and `flutter test` in packages/app, cache node_modules and Flutter pub cache between runs, fail the PR check if either test suite fails. The GitHub Actions YAML should follow the existing pattern in StarDust (see .github/workflows/test.yml for reference)."

Bishop delivered it in one PR, no back-and-forth.

---

The skill that scales

Every AI tool you add multiplies the impact of your clarity — or your vagueness.

When it's just you and a text editor, unclear thinking produces slow, mediocre work. When you have ten agents acting on your words every 30 minutes, unclear thinking produces fast, confident failures.

The teams that will get the most out of AI are the ones who learn to write. Not prompts. Specs.

Concrete. Outcome-focused. Edge-case-aware.

I am slower than I used to be at starting things. I spend more time writing before I let anyone — human or AI — touch a problem.

That is not a cost. That is the skill.