A two-level scoping discipline used to lock down what an AI coding agent should build before any code is written, replacing one-shot vague prompting (see Vibe Coding). Part of the AI-Native Developer Workflow.
Precision is aimed at user-facing scope and acceptance criteria, not implementation detail — technology choices are left to the agent/architect discussion rather than pinned down by the human.
Early planning and architecture documents are treated as disposable "seed" material used only to generate an initial task backlog. They are not maintained as living documentation, because in practice they desynchronize from the evolving codebase. Once the backlog exists, the task tracker (e.g. GitHub issues) becomes the durable source of truth going forward, not the original planning docs.
Grooming is the PM-role practice of rewriting a raw issue into a spec before implementation starts: goal, description, checkable acceptance criteria, and an explicit out-of-scope list. "I would really challenge here every single line." Checkable acceptance criteria are concrete, verifiable pass/fail conditions, framed so "someone should be able to point at the screen and say yes or no" — specific enough to double as the later QA checklist. Ideas that surface during grooming but fall outside the issue's scope get spun off as separate follow-up issues rather than folded in, keeping each spec focused.
Two established requirement-writing frameworks show up inside grooming without needing new tooling, since agents already know them: the user story pattern ("As a user, when I want to do X, I do Y") for phrasing acceptance criteria from the user's point of view, and Jobs-to-be-Done (JTBD) for expressing the underlying job a user is trying to accomplish.
Groomed issues get a simple MVP / post-MVP label: the core backlog is tagged MVP, and anything descoped or agent-proposed during grooming is tagged post-MVP, keeping the must-build set visible.
Performed by the PM role in Agent Team Personas.
Grooming instructions should explicitly list what NOT to implement, not just what to build. Left unconstrained, agents tend to add extra "good ideas" beyond the stated scope, which inflates maintenance burden later. Example from a demo spec: "No part of the flow touches email. There is no mail back end, no verification, no self-serve password reset."
Acceptance criteria should be phrased so they're checkable by inspection: "Make acceptance criteria checkable. Someone should be able to point at the screen and say yes or no." This checkability is what lets the Agent Team Personas QA persona return a binary pass/fail instead of a subjective judgment.
The classic linear process — spec → wireframe → data model → build — isn't obsolete under AI-assisted prototyping, it's radically compressed: the same decisions still happen, just in minutes instead of weeks, via Context Engineering assembling functional/visual/data context before a build step. Process order becomes organic rather than fixed: teams often prototype first and get customer reaction, then write a leaner PRD supplying only what the prototype alone can't (problem statement, success metrics, strategic fit) — all artifacts together, not any one alone, give the complete picture.
At Notion, Ryan Nystrom dictates a feature idea by voice into Whisper, hands the raw transcript to an AI coding agent (Codex) to draft a written spec, then points the same agent back at that spec file and says "build it" — collapsing design-doc writing, review meetings, and implementation into one loop ("no more waiting for the meeting, no more waiting for review").
Notion applies the same discipline at the organizational level: when rebuilding its internal AI agent harness, the team wrote markdown specs first — borrowing the "skills and progressive disclosure" structuring pattern from coding-agent design itself — rather than starting from code. These specs are checked into the repo as a living "agent specs" library that Codex can one-shot-build from, and the library doubles as the project's changelog.
Related: Model Selection for Pushback (Codex), Multi-Tool Workflow Decomposition ('Hack Your Own Multi-Agent System').
Notion checks a folder of specs into the repo itself — one markdown document per behavior of an AI agent feature (e.g., Notion AI's modes). Each spec is the primary artifact: when behavior needs to change, the spec is edited first and the coding agent resyncs the code from it, rather than editing code directly. Because the spec's edit history lives in version control, that history doubles as a changelog: "The spec is the source of truth, the spec as the change log."
A comprehensive spec includes not just the desired behavior but code pointers (where the relevant code lives) and — most importantly — a verification section: how correctness will be checked. Defining verification is treated as the core design deliverable of writing the spec, prioritized ahead of or alongside describing behavior itself, and revisited first when anything about the spec is unclear.
To make verification concrete, Notion built custom CLI tooling that lets an agent exercise the actual live product (send test queries, toggle modes, inspect transcripts) so it can check its own implementation against the spec before finishing: "Build it. And it basically one shotted this because the entire spec file is so comprehensive."
One example spec in the library is Ask mode, a restricted read-only mode for Notion AI that bans all mutating tools.
Nystrom frames version-controlled, plain-English specs as having a secondary audience beyond the engineers implementing them: because they're readable prose rather than code, they can be handed to non-engineers (e.g., marketing, for release notes) directly, which raw source code cannot.