docs(tdd): make the spine language-neutral, add four language references
The discipline in tdd was already language-agnostic; the checklist under it was not. A Python user inherited a mandatory `go test -race` box they can never tick and never got told that `mypy --strict` belongs in the red gate. Per #18's own comment and writing-skills' Multi-Language Dilution warning, the main SKILL.md keeps ONE canonical inline example (Go, the default stack) and the other four languages live in reference files: python, typescript, rust, java. The RED run drove every change. A subagent given a Python task with the Go-only skill reported, in its own words: - "Everything from L169 to L244 is Go-only, and the verification checklist at L326 silently inherits that Go-ness — which is why a Python user ends up with a mandatory box (-race) they can never tick and a required gate (mypy --strict) that isn't listed at all." - "For a brand-new function, the first RED is always a collection-time ImportError... The only clean resolutions are a stub that raises NotImplementedError (production code before a red test?) or accepting ImportError as a legitimate red. The skill picks neither, and this is the single biggest gap." It now picks: that red is legitimate, and writing a stub to satisfy the runner is the Iron Law with extra steps. - The Go table-driven exemplar branches on a `wantErr` column inside the loop. Translated literally that is a conditional assertion folding two behaviours into one test — which this skill's own quality table forbids. The agent caught itself mid-translation; both SKILL.md and python.md now say not to port it. Also: the checklist names the static-analysis gate per language instead of assuming `go vet`, and says to strike the concurrency box deliberately where no equivalent exists — a box that cannot be ticked teaches people to skip checklists. Refs #18 Bump-Type: minor
This commit is contained in:
+37
-6
@@ -100,13 +100,21 @@ go test -run TestRetryOperation_RetriesThreeTimes ./...
|
||||
```
|
||||
|
||||
Confirm:
|
||||
- Test fails (not compilation errors)
|
||||
- Failure message is expected
|
||||
- Fails because feature is missing (not typos)
|
||||
- Test fails, and fails because the feature is missing
|
||||
- The failure message is the one you expected
|
||||
- It is not failing on a typo in the test itself
|
||||
|
||||
**Test passes?** You're testing existing behavior. Fix test.
|
||||
|
||||
**Compilation errors?** Fix errors, re-run until it fails correctly.
|
||||
**Failing because the thing does not exist yet?** That is a legitimate red — a Go
|
||||
compile error for an undefined function, a Python `ImportError` for a module you have
|
||||
not written, a TypeScript "cannot find module". Read the message, confirm it names the
|
||||
unit you are about to build, and proceed to GREEN. **Do not write a stub to make the
|
||||
runner happier.** A stub is production code written before a failing test, which is the
|
||||
Iron Law with extra steps.
|
||||
|
||||
**Failing on a typo or a broken import elsewhere?** Different thing. Fix it and re-run
|
||||
until the failure is the one above.
|
||||
|
||||
### GREEN - Minimal Code
|
||||
|
||||
@@ -166,6 +174,23 @@ Keep tests green. Don't add behavior.
|
||||
|
||||
Next failing test for next behavior.
|
||||
|
||||
## Other languages
|
||||
|
||||
The discipline above is language-neutral; the examples below it are Go, because Go is
|
||||
this fleet's default stack and one good example beats five mediocre ones.
|
||||
|
||||
For anything else, the per-language conventions live in reference files — load the one
|
||||
you need rather than translating Go idioms by eye. Translation is where the mistakes
|
||||
happen: the Go table-driven exemplar below branches on a `wantErr` column inside the
|
||||
loop, which is idiomatic Go and an anti-pattern in pytest, where it produces a
|
||||
conditional assertion and folds two behaviours into one test.
|
||||
|
||||
- `references/python.md` — pytest, `@pytest.mark.parametrize`, `mypy --strict` in the
|
||||
RED gate, `pytest.raises(..., match=)`, fixtures vs helpers
|
||||
- `references/typescript.md` — vitest/jest, `it.each`, `expect(...).rejects`
|
||||
- `references/rust.md` — `#[cfg(test)]` modules, table-driven via arrays, `#[should_panic]`
|
||||
- `references/java.md` — JUnit 5, `@ParameterizedTest`, `assertThrows`
|
||||
|
||||
## Go-Specific TDD Notes
|
||||
|
||||
### Table-Driven Tests (Preferred Pattern)
|
||||
@@ -329,8 +354,14 @@ Before marking work complete:
|
||||
- [ ] Watched each test fail before implementing
|
||||
- [ ] Each test failed for expected reason (feature missing, not typo)
|
||||
- [ ] Wrote minimal code to pass each test
|
||||
- [ ] All tests pass: `go test ./...`
|
||||
- [ ] Race detector clean: `go test -race ./...`
|
||||
- [ ] All tests pass
|
||||
- [ ] The language's static gate is clean — `go vet`, `mypy --strict`, `tsc --noEmit`,
|
||||
`cargo clippy`. A red type-check is a red build; it does not wait for GREEN.
|
||||
- [ ] The language's concurrency gate is clean **where one exists and applies** —
|
||||
`go test -race`, `cargo test` under Miri for unsafe code. There is no equivalent
|
||||
for a pure Python function, and a checklist box that can never be ticked teaches
|
||||
people to skip checklists. Tick it or strike it deliberately; do not leave it
|
||||
hanging.
|
||||
- [ ] Tests use real code (mocks only if crossing a system boundary)
|
||||
- [ ] Edge cases and errors covered
|
||||
|
||||
|
||||
Reference in New Issue
Block a user