byrd-tdd-process

Byrd Development Process v4 (TDD)

The canonical reference is docs/Development-Process-draft-v4.md. This process aligns with Martin Fowler's Red -> Green -> Refactor TDD cycle, augmented with Byrd-specific AI-safety gates (mocks-first validation, full-suite regression gates, and requirement traceability).

When to Use

• Implementing any new functional or technical requirement in this repo.
• Fixing a bug, changing behavior, or adding to a public surface (types, methods, controllers, services).
• Writing or updating any implementation plan. Per the global rule, no plan is exempt regardless of size, urgency, or scope.

When Not to Use

• Pure documentation edits, requirements wording, or session-log housekeeping that touch no code and no test.
• Mechanical, behavior-preserving renames or formatting where existing tests already fully cover the surface.
• Read-only investigation, diagnosis, or research where you produce no source change.

Inputs

• The Functional Requirement(s) being satisfied: FR-MCP-* from docs/Project/Functional-Requirements.md.
• The Technical Requirement(s): TR-MCP-* from docs/Project/Technical-Requirements.md.
• The Testing Requirement(s): TEST-MCP-* from docs/Project/Testing-Requirements.md.
• The active iteration / slice scope (which tests must be green to exit) from MCP TODO state.
• The target test project (for example tests/QBrainAi.Support.Mcp.Tests) and the production project under change.

Critical Rules

• Requirements drive tests. Tests are derived from functional and technical requirements and their acceptance criteria, never from implementation details. If a requirement is missing, capture it first (see Requirements step) before writing the test.
• Tests come first (Red). Write acceptance unit tests covering the full acceptance criteria BEFORE writing implementation code. The test must fail for the right reason before you implement.
• Validate with mocks (Byrd augmentation). Make the new tests pass against mocks/stubs first, proving the test and the contract are correct, before wiring real logic.
• Then implement (Green). Only after the mock-backed tests are correct do you write the real production code that makes them pass without mocks. Refactor tests and production code as part of the cycle to keep the design clean.
• All tests green to exit a phase. The entire unit-test suite for the current increment AND all prior work must pass before leaving an Implementation slice. Per AGENTS.md (Byrd Test Gate), skipped tests are not passing tests: the gate requires zero failures and zero skips in the executed scope. Deferred work belongs in MCP TODO/requirements state, never in a skipped-test placeholder.
• Integration tests come after units. Implement integration tests only after all unit tests pass across the codebase. The Nuke Test target excludes *.IntegrationTests; run those separately.
• Traceability is mandatory. Every new public type and member needs XML doc comments (TreatWarningsAsErrors + CS1591 fail the build), and every new FR/TR/TEST id must be referenced in source/test doc-comments and validated by ./build.ps1 ValidateTraceability.
• Do not ship code you have not verified compiles and passes. Correctness over speed.
• Use pwsh.exe (PowerShell 7+) for all scripts. No em-dashes in any output, code comment, or commit message.
• Defective requirements are expected. If writing the test surfaces a paradox, ambiguity, or wrong rule, refine the requirement (and its FR/TR/TEST docs) rather than weakening the test.