workflow-write-test

name	workflow-write-test
description	Create executable RED specifications before implementation, or record valid Smelter TDD exemptions.
version	0.55
type	workflow
consumes	tasks.md OR implementation-plan.md
produces	executable specification tests (RED), test_cycles entries
default_pattern	C
default_agent	executor
supports_patterns	["A","C"]
team_template	{"C":{"parallel_split_by":"file","agents":["executor"],"aggregator":"executor","sync_point":"test suite ready"}}
can_delegate_to	["tdd-guide","test-driven-development"]
gate	{"postcondition":[{"test_files_exist":true},{"min_cases":10},{"all_red":true},{"test_cycle_entries":">=1 with action=added_case"}]}
exempt_if_surface	["css","style","typography","i18n","copy","typo","dialogue"]

workflow-write-test

Overview

Write an executable specification before any implementation file changes. The output is a failing test suite that specifies the requested behavior with concrete examples, then records RED evidence for the next skill.

Use Specification by Example, BDD, and ATDD principles: clarify behavior through examples, formulate those examples as tests, and automate them before coding.

Core principle: If you didn't watch the executable specification fail for the intended missing behavior, you don't know if it tests the right thing.

Violating the letter of this rule is violating the spirit of this rule.

Announce at start: "I'm using workflow-write-test to write failing executable specifications before source code changes."

Plan source by mode

Read the active mode's persisted planning source before writing tests:

• /fix → tasks.md is the compact v0.55 checklist; use investigation.md only as supporting evidence.
• /implement → implementation-plan.md is the source of the file map, chosen approach, task queue, and test strategy.
• /brainstorm does not invoke this skill directly; its tasks.md is consumed later by /implement as requirements context.

Use the persisted plan as input only. If the behavior cannot be expressed as a failing test, stop and route back for clarification instead of coding.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write implementation code before the executable specification? Delete it. Start over. No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

Implement fresh from the executable specification. Period.

Executable Specification Contract

Every new or modified test must specify externally observable behavior, not implementation details. Prefer Given/When/Then for scenarios or Arrange/Act/Assert for unit-level specs.

Each spec must include:

• Behavior being specified
• Concrete domain values, not vague placeholders
• Initial state and trigger action
• Expected observable outcome
• Meaningful boundary, edge, and error examples
• Exact RED command and failing output before implementation

Do not assert private helpers, internal call order, temporary structure, or other implementation details unless they are the public contract. Open behavior questions block coding; return to clarification rather than inventing behavior.

Minimum Cases Per Category (10+ total)

Category	Minimum
happy path	2+
boundary	2+
error path	2+
edge case	2+
integration	1+

A test file with 9 cases fails the gate. A test file with 10 happy-path cases and no boundary/error coverage also fails because the distribution check runs.

Choose the lowest-level test that fully specifies the behavior:

• Pure logic/state transition: unit executable spec
• API/CLI/hook/script: integration or E2E executable spec
• Service boundary: contract test
• UI behavior: user-observable E2E spec
• Complex output or legacy behavior: approval, snapshot, or characterization spec

Red Flags - STOP

Thought	Reality
"I'll write tests after the code compiles"	That's not TDD. Delete the code, write the executable spec first.
"Just this once, the code is trivial"	Triviality is rationalization. Write the test.
"I'll keep the existing code as reference while writing the test"	Don't look at it. Implement fresh from tests.
"10 cases is overkill for this change"	The gate checks distribution, not just count. Plan distribution before writing.
"Tests don't need to fail — I know the function works"	Watch it RED. Tests that are GREEN on first run test nothing.
"Mocks are fine for this test"	Prefer real code. Mocks hide the bug the test should catch.
"The test can describe internals"	Specs describe behavior. Implementation details make tests brittle.

Rationalization Prevention

Excuse	Reality
"I'm confident it works"	Confidence ≠ evidence. Run the test RED, then GREEN.
"I'm tired"	Exhaustion ≠ excuse. TDD is the speed shortcut, not the slowdown.
"The spec already tests this"	workflow-write-test produces NEW RED cases for the current change. Existing tests are not new evidence.
"Integration tests are enough"	Integration ≠ unit. Distribution requirement is there for a reason.

When modifying existing features

• Search related existing tests
• Modify existing tests to reflect the new executable specification so they go RED (action: modified_case)
• Link case_name to the task/bug id

Surface Exemption

When the upstream investigation or plan records exempt.tdd: true, this skill is skipped by the Smelter workflow prompt and flow advances to the next node.

Exempt surfaces: CSS/style, typography, i18n/copy-only, typo, pure dialogue. The exemption must be declared up-front; the executor cannot demote TDD mid-flow.

Parallel execution (Pattern C)

When Pattern C is chosen with parallel_split_by: file:

• A separate agent writes each test file
• The aggregator (executor) verifies test suite integrity

After Output

Append a ## RED Evidence section to the relevant artifact (test-plan.md, implementation-plan.md, or tasks.md):

{ "file": "...", "action": "added_case", "case_name": "...", "run_result": "fail", "error": "..." }

workflow-coding reads this artifact. Without at least one { action: added_case|modified_case, run_result: fail } entry for the executable specification, coding must refuse to start.

Fail routing

• /fix gate failure because the bug is not reproducible or expected behavior is unclear → workflow-investigate
• /implement gate failure because the task queue or test strategy is incomplete → workflow-implementation-plan
• TDD exemption mismatch → active mode recovery; do not demote TDD inside this skill

Terminal State — Required Next Skill

REQUIRED NEXT SKILL: workflow-coding

Do NOT:

• Skip to workflow-agent-review or beyond — implementation has not happened yet
• Stop after tests are RED, report "tests ready", or ask "shall I implement?"
• Offer A/B/continue choices — Iron Law #1 forbids pausing at non-human-check stages

The RED tests are the gate. workflow-coding consumes them immediately.