The Dev Quality Assistant: Test Planning Before Code Touches the Repo

Last month, I watched our team ship a feature in 3 days that would've normally taken 3 weeks. Same quality, same thoroughness, but zero of the usual "oh crap, we broke production" moments.

The difference? We planned our tests before we wrote a single line of code.

I know, I know. Planning tests first sounds about as exciting as flossing. But it's the difference between shipping with confidence and shipping with anxiety.

Let me tell you about the cycle I've lived through dozens of times (and you probably have too):

1. Product creates a PRD for a shiny new feature
2. Engineering gets excited and starts building immediately
3. Feature gets shipped to staging looking beautiful
4. QA finds 5 critical bugs that make you question your life choices
5. Engineering scrambles to fix them (usually late at night)
6. More bugs surface in production because Murphy's Law is real
7. Team realizes there are no tests covering the edge cases
8. Someone says "we should really write tests" (spoiler: they never get written)
9. Rinse and repeat until you're all dead inside

If you've lived this loop, you know the result: fragile code, manual testing bottlenecks, and that constant low-level anxiety that something's going to break.

This isn't about perfectionism or slowing teams down. It's about defining correctness before building, the same way you wouldn't start construction without blueprints.

Here's what I'll show you: exactly how we use the Dev Quality Assistant to pre-plan tests, why it's become non-negotiable in our build process, and how you can steal our approach for your own workflow.

The Problem: Test-After-Build (And Why It's Expensive)

Let me paint you a picture of how this usually goes wrong.

The Typical Pattern (You've Been Here)

Product writes a PRD: "Users should be able to archive projects." Seems simple enough, right?

Engineering implements it. Archive endpoint? Check. UI updates? Check. Manual testing shows it works. Ship it!

Then the bug reports start rolling in: "I archived a project and lost all my tasks."

Oops. Nobody thought about cascading deletes. Cue the post-mortem, the emergency fix, and the promise to "write tests next time."

The reality: next time never comes because there's always a new feature to ship.

Why This Pattern Fails Every Single Time

No Tests == No Definition of "Done": Without tests, "done" means "it worked when I tried it once." You're essentially shipping undefined behavior and hoping for the best.

Edge Cases Are Afterthoughts: Humans are notoriously bad at remembering edge cases when we're in the flow of building. "What if the project has 1,000 tasks?" "What if the user is a viewer, not an owner?" These questions only surface after the bugs do.

Tests Become Debt: If tests are optional, they never get written. There's always a new feature, a new deadline, a new fire to put out. Testing becomes "we should really do this someday" debt that compounds faster than credit card interest.

Manual Testing Doesn't Scale: Every new feature adds to the manual test matrix. Eventually, QA becomes a bottleneck and teams start cutting corners. I've been there, it's not pretty.

The Solution: Dev Quality Plan as a Pre-Code Gate

Here's what we changed: We treat the dev quality plan the same way we treat the PRD, it's a mandatory deliverable before implementation starts.

Our pipeline now looks like this:

1. Product Spec (PRD/ADR) → What we're building and why
2. Dev Quality Plan ← NEW GATE (what tests, quality checks, deploy steps)
3. Implementation → Write code guided by the test plan
4. Quality Checks → Run lint, tests, deploy checklist
5. Ship (with actual confidence this time)

The dev quality plan sits between spec and code. It's the bridge that translates "what we're building" into "how we know it's correct."

What Goes in the Plan (The Four Required Sections)

Our dev quality plan (we call it Rule 125, template at docs/templates/DEV-QUALITY-TEMPLATE.md) has four sections that we never skip:

1. Feature Snapshot

This grounds everything in context:

• Brief description (one paragraph, no novels)
• Affected surfaces (API, UI, database, third-party integrations)
• Owners (which engineers, which agents, who's responsible for what)

2. Automated Test Suggestions (The Meat and Potatoes)

This is where the magic happens. We map out three tiers of tests:

Functional Tests (The Happy Path):

• What acceptance criteria from the PRD need test coverage?
• For each criterion, what's the specific test scenario?
• What tooling makes sense (unit, integration, e2e)?
• Where exactly should we implement this (file path, test suite)?

Edge Case Tests (The Unhappy Path):

• Error handling (invalid input, missing data, timeouts)
• Boundary values (empty arrays, max string length, negative numbers)
• Permissions (user not authenticated, wrong role, cross-org access)
• Localization fun (timezones, date formats, currencies)

Regression / Non-Functional Tests:

• Performance (load time, query efficiency)
• Accessibility (keyboard nav, screen reader, WCAG compliance)
• Contract tests (API shape, backward compatibility)

3. Code Quality & Lint Guidance

This covers the non-testing quality stuff for the specific feature:

• State management: How should state be handled? (Context, Zustand, server state)
• Data fetching: Use tRPC, React Query, or plain fetch?
• Security: What auth checks are required?
• Accessibility: Any ARIA labels, keyboard shortcuts, focus management?
• Error handling: How should errors be displayed? Logged?

Plus references to existing lint rules (ESLint configs, Prettier, TypeScript strict mode, custom rules).

4. Deployment Confidence Checklist

Step-by-step pre-push and post-deploy checks that make "done" unambiguous:

Pre-Push:

• All tests pass (npm test)
• No TypeScript errors (npm run type-check)
• Linting passes (npm run lint)
• Feature flag created (if applicable)
• Database migrations run successfully
• Docs updated (API docs, user guide)

Post-Deploy:

• Smoke test in production (archive a test project)
• Check error logs (Sentry, CloudWatch)
• Monitor key metrics (archive event count, API latency)
• Watch for support tickets (the ultimate quality metric)

Rollback Plan:

• Toggle feature flag off (if flagged)
• Revert database migration (if needed)
• Communicate to users (status page, email)

The Enforcement Mechanism (Making It Actually Happen)

Here's the critical part: the dev quality plan is a hard blocker.

In 000-orchestration.mdc (our central foreman), we added:

MANDATORY BUILD OUTPUTS:
- Before implementation: DEV-QUALITY-<feature-slug>.md must exist
- Before merging: All tests from the plan must pass
- Before deploying: Deployment checklist must be completed

If the Dev Quality Assistant hasn't completed the plan, the Implementer can't start coding. Period. It's a hard gate, not a suggestion.

And honestly? This was the key. Without enforcement, it's just another best practice that gets ignored when deadlines loom.

Real-World Example: Building a Multi-Tenant Invite System

Here's a real dev quality plan we created last month. This should make it concrete.

Context: We needed to add the ability for organization owners to invite new members via email. Sounds simple, right? (Famous last words...)

Step 1: Feature Snapshot

Step 2: Automated Test Suggestions

Functional Tests:

1. Owner can send invite → Integration → api/invites.test.ts
2. Invite email is sent via Resend → Integration → api/invites.test.ts (mock Resend)
3. Invite token is valid for 7 days → Unit → invites.test.ts
4. Accepting invite adds user to org → E2E → e2e/invites.spec.ts
5. User sees new org in org switcher → E2E → e2e/invites.spec.ts

Edge Case Tests (this is where we catch the expensive bugs):

1. Non-owner cannot send invite → Returns 403 → Integration → api/invites.test.ts
2. Inviting existing member returns error → Integration → api/invites.test.ts
3. Expired invite token returns error → Unit → invites.test.ts
4. Malformed email returns 400 → Integration → api/invites.test.ts
5. User already in 5 orgs (limit) cannot accept → E2E → e2e/invites.spec.ts
6. Invite to non-existent org returns 404 → Integration → api/invites.test.ts

The Result

Total time to create the dev quality plan: 45 minutes.

Time saved during implementation:

• Engineer knew exactly what tests to write (no guessing games)
• Caught 3 edge cases during coding that would've been production bugs
• Deployment was confident (all checklists passed)
• Zero bugs reported in the first two weeks

ROI: 45 minutes of planning saved ~10 hours of debugging and rework.

Those are the kind of numbers that make you a believer.

How to Implement This (Without Overthinking It)

Here's your practical roadmap for adding the Dev Quality Assistant to your workflow:

1. Create the Template

Start with our template or build your own. The key sections you can't skip:

• Feature snapshot
• Automated test suggestions (functional, edge, regression)
• Code quality & lint guidance
• Deployment confidence checklist

Don't overthink this. A simple Markdown template is fine.

2. Make It a Hard Gate

Add a workflow rule: "No implementation starts until the dev quality plan exists."

This could be:

• A Jira/Linear workflow state (Spec → Quality Plan → Implementation)
• A pull request template check ("Link to dev quality plan")
• A code review requirement (if no plan exists, PR gets blocked)

The key: someone is accountable for completing the plan before code starts.

3. Assign Ownership

Designate who creates the dev quality plan. Your options:

• Test Engineer (if you have one)
• Dev Quality Assistant (an AI agent guided by the template)
• Tech Lead (for complex features)
• Implementer (for simple features)

We use a mix depending on complexity, but someone's always on the hook.

4. Use the Plan as a Living Checklist

As the engineer implements the feature, they use the plan as their definition of done:

• Write the test for "Owner can send invite" → Check
• Write the test for "Non-owner gets 403" → Check
• Add PostHog logging → Check
• Verify modal accessibility → Check

The plan becomes their roadmap to shipping with confidence.

5. Update the Plan as You Learn

Sometimes during implementation, you discover new edge cases or realize a test isn't feasible. That's fine, update the plan.

The goal isn't a perfect plan upfront. It's a living plan that guides quality decisions.

Real-World Results (The Numbers)

Since implementing the Dev Quality Assistant three months ago, here's what we've seen:

Impact on velocity:

• Time to create plan: 30-60 minutes per feature
• Time saved debugging: ~8 hours per feature (average)
• Time saved in QA: ~4 hours per feature (fewer manual test cycles)

Net result: ~10-12 hours saved per feature, plus higher quality and way fewer 3am "production is down" Slack messages.

Trade-Offs and Limitations (Being Honest)

The Dev Quality Assistant isn't free. Here's what it costs:

Upfront Time Investment: 30-60 minutes per feature to create the plan. For small features (one-line changes), this can feel like overkill.

Requires Testing Knowledge: Not everyone knows how to design good tests. Junior engineers might struggle to map acceptance criteria to test cases. You need training or an experienced Test Engineer to guide.

Can Create Rigidity: If the plan is too detailed, it constrains implementation choices. You need to balance guidance with flexibility.

Doesn't Catch Everything: The plan only covers what you think to test. Novel bugs or edge cases you didn't anticipate still slip through. You still need exploratory testing and user feedback.

When to Skip It

We use lighter plans (or skip entirely) for:

• Prototypes / spikes (not production-ready)
• Trivial changes (copy updates, styling tweaks)
• Internal tools (lower quality bar)
• Reversible experiments (easy to rollback)

But anything touching user data, payments, or core workflows gets the full treatment.

What's Next for Us

The Dev Quality Assistant has become one of our most valuable practices. It's the reason we ship features with confidence and rarely see "how did this bug make it to production?" post-mortems.

We're now working on:

• AI-generated plans: Using Claude to auto-generate test suggestions from PRDs
• Test coverage tracking: Dashboards showing which features have full vs. partial coverage
• Quality scores: Numeric scoring for test completeness, lint compliance, deployment readiness

Your Turn

If you want to ship higher-quality code faster, I encourage you to implement a Dev Quality Assistant. Start with a simple template, make it a gate before implementation, and use it as a checklist.

The question isn't whether this takes time upfront, it does. The question is whether you'd rather spend 45 minutes planning tests or 10 hours debugging production issues.

What if every feature had a clear definition of "done" before the first line of code was written? That's the promise of planning quality upfront.

And honestly? Once you experience shipping with this level of confidence, it's hard to go back to the old way.