hm-l2-test-driven-execution

Files (15)

• SKILL.md
• evals.json · evals/
• .gitkeep · metrics/
• rich-eval-rubric.json · metrics/
• rich-gate-scorecard.md · metrics/
• coverage-verification.md · references/
• red-green-refactor.md · references/
• source-synthesis.md · references/
• validate-rich-package.sh · scripts/
• validate-skill.sh · scripts/
• task_plan.md
• .gitkeep · templates/
• test-case-template.md · templates/
• .gitkeep · workflows/
• tdd-session-workflow.md · workflows/

SKILL.md (first lines)

# Test-Driven Execution

## Overview

Execute runtime-truthful RED/GREEN/REFACTOR work from locked requirements. This skill owns test-first execution, invalid RED detection, coverage evidence, regression handling, and honest blocked handoffs. It does **not** author ambiguous requirements; use `hm-spec-driven-authoring` first when acceptance criteria are missing or unclear.

This package synthesizes three inspected third-party patterns:

| Source pattern | Adopt / adapt decision | Local transformation |
|---|---|---|
| `addyosmani/agent-skills@test-driven-development` | Adopt comprehensive TDD, Prove-It bug-fix pattern, test sizes, state-over-interactions, DAMP tests, real/fake/stub/mock preference; adapt browser tooling to available tools. | Adds bug reproduction first, test-size labels, boundary-mock policy, and runtime verification warnings. |
| `helderberto/skills@tdd` | Adopt one-test-at-a-time vertical TDD, public-interface discipline, and refactor-after-green rule. | Adds no-batch RED enforcement, public contract focus, and deep-module/testability checkpoints. |
| `jellydn/my-ai-tools@tdd` | Adapt action/status vocabulary and test-template package idea; reject hard-coded slash-command wrappers. | Adds portable session state, workflow template, and runner-agnostic test template. |

## Entry Gate

Proceed only when there is at least one locked requirement, bug reproduction, acceptance criterion, or explicit behavior contract.

Before writing tests:

1. Confirm the desired behavior and failure mode are observable.
2. Confirm implementation has not already been written for the slice. If it has, either delete/revert the implementation for a true RED cycle or label the work as test-after and do not claim TDD.
3. Identify the project test runner and coverage options.
4. If requirements are ambiguous, stop and hand off to `hm-spec-driven-authoring`.
5. If work spans sessions, persist RED/GREEN/REFACTOR status through `hm-planning-persistence` (.hivemind/state/planning/<session-id>/progress.md) or a local progress table.

## Boundary Rules

| Nearby workflow | Boundary |
|---|---|
| `hm-spec-driven-authoring` | Owns requirement and acceptance-test derivation. This skill consumes locked requirements. |
| `hm-planning-persistence` | Owns durable task/progress files in `.hivemind/state/planning/<session-id>/`. This skill records test phase state into that mechanism when needed. |
| Manual-only QA | Manual exploration may inform a bug, but it is not RED/GREEN/REFACTOR execution. |
| Test-after work | Useful, but not TDD. Do not claim RED evidence if tests were written after implementation. |
| Generic code review | Review can assess quality after tests pass; it does not replace fresh test output. |

## RED/GREEN/REFACTOR Gates

Default rule: one test, minimal code, then next test. Do **not** batch multiple RED tests and then implement them together unless the requirement is inseparable and you document why.

### Red Phase

Write the smallest test that fails for the right reason before implementation changes.

```bash
npm test
pytest
go test ./...
```

**Gate:** The test must fail before implementation. If it passes, STOP. The RED test is invalid or the feature already exists. Rewrite the test or re-scope the slice before continuing.

Record:

```yaml
phase: red
requirement_id: REQ-...
test_size: small | medium | large
public_interface: <API/CLI/UI/function/event>
command: <exact command>
observed_failure: <excerpt>
failure_reason_valid: true | false
```

### Green Phase

Write the minimal implementation that makes the failing test pass. Avoid unrelated cleanup.

```bash
npm test
pytest
go test ./...
```

**Gate:** If the target test still fails, debug the behavior. Do not refactor before green.

Keep GREEN implementation minimal: no unrelated cleanup, no broad rewrites, no private-interface-only proof.

### Refactor Phase

Clean only after green. Re-run the target test and the relevant broader suite.

**Gate:** If refactor breaks tests, revert the refactor or split it into smaller steps.

Refactor only after green output exists in the current session. Re-run the focused test and the relevant broader suite or explain why the broader suite is out of scope.

## Prove-It Pattern for Bugs

Use this when the task starts from a defect rather than a new feature:

1. Reproduce the bug with a failing test or the smallest automated command that captures the bad behavior.
2. Confirm the failure is meaningful and would fail without the fix.
3. Apply the minimal fix.
4. Re-run the reproduction test, then the relevant regression suite.
5. Record whether the bug is now covered by a permanent regression test.

If the bug can only be reproduced manually, label the evidence `manual-reproduction` and do not claim automated TDD until an automated RED test exists.

## Runtime-Truthful Testing

Prefer tests that exercise real behavior. Mock only transport boundaries, clocks, external services, or expensive infrastructure when the mock does not hide the behavior under test.

Evidence labels:

- `runtime-truthful`: test exercises the behavior through real public interfaces or realistic integration seams.
- `transport-mocked`: external transport is mocked but domain behavior is real.
- `mock-heavy`: many internals are mocked; cannot by itself prove runtime behavior.
- `manual-only`: useful observation, not automated proof.

Mock-heavy tests may support debugging but cannot close runtime-truthful acceptance criteria without complementary evidence.

Use the preference order adapted from the inspected TDD sources:

1. Real implementation through public interface.
2. Fake implementation for expensive external systems.
3. Stub for deterministic boundary values.
4. Mock only for transport, clock, external service, or failure injection boundaries.

## Test Size and Readability Labels

From shynlee04/hivemind-plugin, MIT.

More from shynlee04/hivemind-plugin