tdd-test-writer

name	tdd-test-writer
description	Use when a behavior-changing task needs failing tests first, RED/GREEN handoff, or automated behavior gates before implementation.

TDD Test Writer

When to Use

Use this skill when:

• the user asks for TDD, RED/GREEN, failing tests first, or behavior-gated implementation
• a behavior-changing task has a stable automated test surface and needs a strict implementation contract

Do not use this skill when:

• the task does not match the trigger conditions above

Use this skill to complete the RED phase of TDD: define behavior with tests first, verify they fail for the right reason, then hand off implementation with objective pass criteria.

Oasis7 Bounded Usage

Use this skill by default only when all of the following are true:

• the task changes product, runtime, API, or UI behavior
• there is a stable automated test surface for that behavior
• a narrow RED command can be run locally in the current task worktree

Do not treat this skill as a universal gate for:

• documentation / governance / planning-only tasks
• pure refactors with no behavior change
• tasks whose only verification surface is manual, flaky, or not yet repo-owned

When you skip RED phase in oasis7, record the skip reason in project.md, handoff, or GitHub task issue evidence comments.

When To Use

Use this skill when the user asks for:

• test-first development
• TDD / RED-GREEN-REFACTOR workflow
• writing tests that implementation agents must satisfy
• bugfixes that need regression tests before code changes

Also use it in oasis7 when a behavior-changing implementation task already has a stable automated harness and the repo workflow needs a behavior-first guard before production edits.

Required Rules

1. Do not modify production code while running this skill.
2. Use subagent role tdd_test_writer for RED-phase test authoring whenever available.
3. Write behavior-focused tests, not placeholders.
4. Every new/updated test must fail before handoff.
5. Failures must come from missing or incorrect production behavior, not broken tests.
6. Prefer deterministic, targeted test commands over full-suite runs when possible.
7. For bugfix tasks, add a regression test that captures the reported failure mode.
8. In oasis7, this skill complements test_tier_required/full; it does not replace them.

Workflow

1. Define Behavior Contract

• Convert user request into explicit acceptance criteria.
• Identify happy path, edge cases, and negative-path expectations.
• If requirements are ambiguous, record ASSUMPTION: lines in output.

2. Delegate Test Authoring To tdd_test_writer

• Spawn a tdd_test_writer subagent with task scope, target files, and acceptance criteria.
• Require the subagent to write/update tests only (no production code changes).
• Require command output proving RED-state failure for the new tests.
• If tdd_test_writer is unavailable, continue directly and note FALLBACK: tdd_test_writer unavailable.

3. Discover Existing Test Conventions

• Detect framework and runner from the repo (for example vitest, jest, pytest, go test, cargo test).
• Follow existing directory, naming, and fixture conventions.
• Reuse existing helpers instead of introducing duplicate test utilities.

4. Author RED-Phase Tests

• Create or update test files that encode the behavior contract.
• Keep tests small and intention-revealing (clear names and assertions).
• Include at least one negative-path assertion where applicable.
• Avoid network/time randomness; mock or fixture external systems.

5. Verify RED State

• Run the narrowest command that executes the new tests.
• Confirm they fail for the expected behavioral gap.
• If failure is caused by test syntax/setup, fix tests and rerun.

6. Produce Implementation Handoff

Return a block that implementation agents must follow. The handoff must include:

• subagent used (tdd_test_writer) or explicit fallback reason
• exact test files created/updated
• exact verification command(s)
• short failure summary proving RED state
• immutable test constraint (do not edit tests unless requirement changes)
• pass criteria that define task completion

Required Output Format

TDD RED PHASE COMPLETE

## Authoring Mode
- Subagent: tdd_test_writer
- Fallback: [only if subagent unavailable]

## Test Files
- [path]

## Verification
- Command: [exact command]
- Result: FAIL (expected)
- Failure reason: [1-2 lines tied to missing behavior]

## Implementation Contract (for next agent)
1. Do not modify these tests: [paths]
2. Implement production changes only in: [paths or modules]
3. Completion gate: [exact command] passes with no test weakening.
4. Run broader safety check: [secondary command]
5. Return evidence: changed files + command output summary.

## Assumptions
- ASSUMPTION: [only if needed]

Quality Bar

• Tests fail before implementation and are reproducible locally.
• Assertions are specific enough to prevent false positives.
• Regression coverage is present for bugfix-driven tasks.
• Handoff is precise enough that another agent can execute without clarifications.

Guardrails

• Do not weaken tests to make GREEN easier.
• Do not use TDD as a hard gate when no stable automated harness exists.