Turn a PRD into a coding-agent implementation plan

Planning path

• Normalize the product contract
• Isolate ambiguities
• Form reviewable tasks
• Map dependencies
• Write acceptance criteria
• Preview GitHub issues

1. Normalize the product contract

A PRD is usually written for several audiences. It may mix the customer problem, business target, interface ideas, implementation preferences, and launch wishes. Before creating tasks, rewrite it as a small contract that preserves the source while exposing what is missing.

2. Put ambiguities in a queue, not in the code

A useful plan makes uncertainty more visible. Translate vague adjectives and overloaded verbs into decisions with measurable consequences.

• “Fast” becomes a target, percentile, device, network, and measurement point.
• “Secure” becomes actors, protected data, denied operations, audit needs, and relevant threat or policy constraints.
• “Sync with Notion” becomes manual paste, Markdown import, one-way API pull, two-way synchronization, conflict behavior, and authorization.
• “Real-time” becomes polling, server events, sockets, acceptable delay, reconnection, and stale-state behavior.
• “Admin can manage users” becomes the exact actions, role hierarchy, self-demotion rule, audit record, and failure states.

Mark an ambiguity as blocking when different answers change schema, authorization, integrations, or public behavior. A non-blocking assumption can remain in the plan only when it is reversible and clearly labeled.

3. Form tasks around reviewable outcomes

One task should create one coherent outcome that a reviewer can inspect. Avoid tasks that are either a vague feature name or a miniature project containing schema, API, UI, background work, migration, and tests.

4. Add dependencies before you sequence the work

Document order is not implementation order. Build a dependency graph from contracts and state outward, then identify work that can proceed in parallel.

• Schema and migration before code that persists or queries the new state.
• API or event contract before independent producer and consumer implementations.
• Authentication and authorization rules before admin, sharing, export, and destructive actions.
• Parser and validation before persistence of imported data.
• Core implementation before end-to-end tests, but test fixtures and acceptance cases can be prepared earlier.
• Instrumentation before relying on an operational dashboard or alert.
• Fallback and rollback behavior before a risky migration or broad release.

Give every task a dependency value, even when it is None. A blank dependency cell hides whether sequencing was considered.

5. Write acceptance criteria that can fail

Criteria should describe the externally observable behavior, not merely repeat the implementation action. Include the actor, starting state, action, result, and relevant denial or failure path.

Task: Enforce organization-scoped project access

Acceptance criteria
- A signed-in member can read projects for their organization.
- The same member cannot read or mutate another organization's project by ID.
- An unauthenticated request receives the declared authorization response.
- The UI renders empty, denied, and dependency-failure states without exposing data.
- Automated tests cover owner, same-organization member, cross-organization member, and anonymous cases.

A criterion such as “permissions work” cannot reliably fail and therefore cannot establish completion. If a requirement changes persistent state, include reload or subsequent-read evidence. If it changes money, identity, authorization, deletion, or external messages, include the negative and recovery paths.

6. Estimate complexity without inventing a schedule

Use Small, Medium, and Large to communicate relative implementation complexity. State the factors: number of components, uncertainty, migration risk, external dependencies, authorization, data loss, billing, and verification breadth.

• Small: localized, well-understood change with narrow tests and no meaningful migration or permission risk.
• Medium: several components or new error states, a modest schema/API change, or permissions that need focused testing.
• Large: cross-cutting architecture, external integration, risky migration, role-model change, broad compatibility, or unresolved requirements.

Do not translate those labels into dates unless team capacity, codebase maturity, review time, deployment constraints, and parallel work are known.

7. Preview the issue set before creating anything

GitHub supports issue templates and forms, issue hierarchy, dependencies, and command-line issue creation. Those are useful destinations for a reviewed plan, not substitutes for one. GitHub’s documentation shows that gh issue create can set title and body non-interactively and can also express parent and dependency relationships.

1. Show the complete proposed task table.
2. Resolve blocking ambiguities and adjust task boundaries.
3. Confirm the target repository and whether issues, sub-issues, dependencies, labels, milestones, or projects are appropriate.
4. Preview every title and body, including acceptance criteria and dependency references.
5. Check for duplicates and existing work.
6. Ask for explicit confirmation immediately before creation.
7. Record the created URLs and compare them with the approved set.

For repeated intake, GitHub issue forms can standardize inputs and validations through YAML files in /.github/ISSUE_TEMPLATE. The current GitHub documentation notes that issue forms remain in public preview, so keep the plan portable as Markdown rather than depending on one UI feature.

Use the plan as a verification contract

When implementation begins, update the plan with the actual files changed, decisions made, deviations, commands run, and evidence produced. A coding agent should not claim a task complete because code exists; it should show how the stated acceptance criteria were exercised.

Turn the method into a repeatable workflow

Common questions