Skip to content
Skills Library
Programming · Building & coding

test-first

/test-first

[Orbit 2.4.1 Implementation] Red → green → clean; test from a spec scenario; characterization test for old code. Use when: «TDD», «сначала тест», «напиши тесты», «красный-зелёный-рефакторинг»; test first, TDD, write tests before code.

Licence
MIT
Last repository change
09.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

[Orbit 2.4.1 Implementation] Red → green → clean; test from a spec scenario; characterization test for old code. Use when: «TDD», «сначала тест», «напиши тесты», «красный-зелёный-рефакторинг»; test first, TDD, write tests before code.

Original author description

[Orbit 2.4.1 Implementation] Red → green → clean; test from a spec scenario; characterization test for old code. Use when: «TDD», «сначала тест», «напиши тесты», «красный-зелёный-рефакторинг»; test first, TDD, write tests before code.

How it works

  1. When to use
  2. Inputs
  3. Procedure
  4. Output
  5. Example
  6. Check
  7. Pitfalls
  8. Portability
  9. What's improved vs the source
  10. Based on
Original SKILL.md headings · 163 lines, 1,333 words
SKILL.md preview
---
name: test-first
description: '[Orbit 2.4.1 Implementation] Red → green → clean; test from a spec scenario; characterization test for old code. Use when: «TDD», «сначала тест», «напиши тесты», «красный-зелёный-рефакторинг»; test first, TDD, write tests before code.'
---

# test-first — test first, then code

> **Orbit · ② Build · step 2.4.1 Implementation**
> **Input:** a plan task ← `build-mcp`, `rebuild-design`
> **Output:** code + tests → next `run-plan`
> **Works with:** `prove-done`, `find-root-cause`
> **Shared rules:** reply in the user's language per `speak-plain`; generated content defaults to English; act within `stay-in-scope`; artifacts go to `.orbit/` (contract: `ARTIFACTS.md`).

Red → green → clean for any behaviour change. The main rule: **if you did not watch the
test fail for the right reason, you do not know what it tests.** A test written after the
code passes by construction and proves nothing. This skill turns a spec scenario into a
test, the test into minimal code, and the run into evidence.

## When to use

- Any behaviour change: a new feature, a bug fix, a risky refactor.
- A plan task names a WHEN/THEN scenario — the test is that scenario, named as behaviour.
- Existing code has no tests and must be changed: a characterization test first.
- Exceptions, only with the person's explicit consent: a throwaway prototype
  (`prototype-fast`), pure markup without logic, or config verified by deployment.

## Inputs

- The plan task: `.orbit/task/<id>/plan.md` — files, scenario, check command.
- The spec scenario in WHEN/THEN form: `openspec/changes/<id>/` or the spec named in the
  plan. No scenario → ask for it; a test without one is a guess.
- The module interface from `shape-modules` — tests check behaviour through the interface,
  not internals.
- The test layout and runner: `ls tests/`, the command in `package.json` /
  `pyproject.toml`, and `rg -n "def test_|it\(" tests/ | head -20` for style.
- For old code: the current output for real inputs, so the characterization test records
  what is, not what should be.

## Procedure

1. **Pick one scenario and name the test as behaviour.** `returns_400_when_email_empty`,
   `exports_header_only_for_empty_report`. If the name needs "and", it is two tests; each
   test carries one clear failure message.
2. **Write the test (red).** Assert the WHEN/THEN outcome through the public interface;
   real data where possible, mocks only at seams (database, network, time).
3. **Watch it fail — for the right reason.** Run the test and read the failure. Passes
   immediately → it tests existing behaviour or nothing. Fails on import/compile →
   scaffold until it fails on the assertion.
4. **Write the minimal code to pass (green).** Nothing "while I am here": no extra option,
   no refactor of the neighbourhood, no speculative abstraction. Green means the one test
   plus the suite.
5. **Watch it pass, and all other tests too.** Run the whole file or suite, not only the new
   test. Another test broke → fix it now; a green new test on a red suite is not done.
6. **Clean.** Remove duplication, improve names, extract only what is actually repeated —
   run the tests before and after; both green. Clean is a separate step from green.
7. **Log the evidence.** Append command → output → conclusion to
   `.orbit/task/<id>/evidence.md`, then tick the task in `.orbit/task/<id>/plan.md`.
8. **A bug is a reproducing test first.** Write the test that fails on the bug, watch it
   fail, fix, watch it pass. The test stays in the suite forever — that is the regression
   guard.
9. **Old code without tests: characterization first.** Record input → current output even
   if the current behaviour looks odd (`extract-rules`). It protects the behaviour you do
   not intend to change, and it is the baseline for the refactor.
10. **Pick the level deliberately:** pure logic tests (most), orchestration with stubs
    (fewer), integration with real infrastructure (a few, e.g. Testcontainers). A slow
    integration test for pure logic wastes the suite; mocked-only tests cannot prove the SQL.
11. **Red flags — stop, back to step 1:** "I'll write tests later", "passed on the first
    run — great", "I'll adjust the test so it passes". Each turns the suite into a
    description of the code instead of its requirements.

## Output

Code plus tests in the repo, the evidence entry and the plan tick:

```python
# tests/test_signup.py
def test_returns_400_when_email_empty():
    response = client.post("/signup", json={"email": "", "password": "x" * 12})
    assert response.status_code == 400
    assert response.json()["error"] == "email_required"
```

```markdown
## 2026-11-08 21:20 — task 2: signup validation
$ pytest tests/test_signup.py -q
1 failed  (assert 201 == 400)      ← watched it fail on the assertion
$ pytest tests/test_signup.py -q
1 passed
$ pytest -q
86 passed, 0 failed                ← suite green after the change
Conclusion: empty email → 400 with the spec's error code; task 2 done.
```

Next: `run-plan` continues the plan; `prove-done` re-runs the evidence before review.

## Example

Task from `plan.md`: "reject signup with an empty email; check `pytest tests/test_signup.py`".

1. Spec scenario: **WHEN** email is empty **THEN** the API returns 400 `email_required`.
2. Write `test_returns_400_when_email_empty` and run it:
   `pytest tests/test_signup.py -q` → `1 failed (assert 201 == 400)` — the right assertion.
3. Add the smallest guard in the signup handler (edge validation only):
   `if not payload.email: raise ValidationError("email_required")` mapped to 400.
4. Run `pytest tests/test_signup.py -q` → `1 passed`; then `pytest -q` → `86 passed`.
5. Clean: reuse the existing `ValidationError` mapper instead of a second branch; run the
   suite again → still `86 passed`.
6. Log the three commands and outputs in `.orbit/task/<id>/evidence.md`; mark task `[x]` in
   `.orbit/task/<id>/plan.md`. Later it guards the regression: a refactor that drops the
   guard turns it red before review.

## Check

```bash
pytest tests/test_signup.py -q              # or npm test -- signup
pytest -q                                    # the whole suite, not only the new test
git diff --stat                              # code changed; test was added first
rg -n "def test_returns_400|it\(.returns 400" tests/   # test name states behaviour
rg -n "^## .*task" .orbit/task/<id>/evidence.md        # fail → pass → suite recorded
```

Pass rule: the test was observed failing on the assertion before the code, then passing; the
full suite is green; the name states a behaviour, not an implementation detail; a bug fix
carries the reproducing test; a legacy change carries the characterization test. No
test is adjusted to fit the implementation. Evidence exists per cycle; red-flag phrases mean
the cycle was not followed.

## Pitfalls

- **Writing the test after the code.** It passes immediately and proves nothing; the red
  observation is the whole method.
- **Failing for the wrong reason.** An import error or a typo in the test is not a red test;
  fix until the assertion itself fails.
- **Green with a broken suite.** The new test passes and three old ones fail — broken, not
  progress.
- **Minimal code that is not minimal.** Adding options "for the future" turns TDD into
  speculative design; make only the test pass.
- **Skipping clean.** Duplication stays and the suite documents a mess; refactor with green
  tests on both sides.
- **Mocks everywhere, internals asserted.** Mock only at the seams and test through the
  interface; a test that mocks the subject, or asserts private fields and call order,
  freezes the implementation.
- **A bug fix without the reproducing test.** The bug returns next quarter; the test is the
  fix's proof and its regression guard.
- **"Tests later".** The later never comes, and the plan's check command has nothing to run.

## Portability

Works in any language and agent: the cycle is a discipline, not tooling. Use the repo's
runner (`pytest`, `npm test`, `go test`, `cargo test`) and its test layout; no subagent or
slash command is needed. Evidence in
`.orbit/task/<id>/evidence.md` is plain Markdown read by `prove-done`, reviews and
`handoff-session`, so the red → green history survives a session break.

## What's improved vs the source

- Tests come straight from spec scenarios — trace "requirement → test → code" across the
  pipeline.
- A path for existing code without tests (characterization test) and three test levels.
- Evidence goes into the shared `evidence.md`, read by `prove-done` and reviews.
- "Watch it fail for the right reason" is explicit, including the compile-error trap; red
  flags are named.

## Based on

- [Superpowers](https://github.com/obra/superpowers) — method «test-driven-development» (MIT). Rewritten in our own words and improved — see "What's improved".

Versions

RepositoryScoreLicence
This page · tojim00d/Orbit-skills100MIT
NoobyGains/godmode100MIT
Cynnamoroll/factory-stack100MIT
claude-world/director-mode-lite100MIT
duthaho/claudekit100MIT
DemonPalace/DoneCheck90MIT

Database snapshot: 13.11.2026 · package version 6bacfd8c55a8 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100tdd
    Test-driven development workflow. Use when the user asks to "write tests first", "TDD", "add test coverage", "test this function", or wants to develop a feature test-first.
  • 100tdd
    Test-Driven Development enforcement skill. Activates full TDD mode. Activate when: TDD, test-driven, test first, red-green-refactor, write tests first.
  • 95tdd-workflow
    Test-Driven Development workflow enforcement skill. Use when explicitly asked for TDD methodology, test-first development, red-green-refactor cycle, or TDD implementation. Triggers on keywords like "start TDD", "test-driven development", "write tests first", or in Chinese "開始…
  • 100tdd
    Use this skill whenever the user wants to write code using TDD, test-driven development, or test-first methodology. Triggers on: "/tdd", "let's do TDD", "write a failing test", "red green refactor", "test-first", "start a TDD cycle", or any request to implement a feature by…
  • 90TDD Methodology
    This skill should be used when the user asks to "write tests first", "use TDD", "test-driven development", "red green refactor", "test first", "add unit tests before code", "write regression test first", "safe refactor with tests", or when TDD mode is active and the user makes…
  • 100dino-test-driven-development
    Write failing test BEFORE implementation, match project conventions from tea-rags search of existing tests (mocks, helpers, assertion style, fixtures) to fit local norms. Triggers on "write a test", "TDD", "напиши тест", "сначала тест", "failing test first", "RED phase", "add…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.