TDD Py4vasp

Test-driven development for py4vasp — one chunk

Carry one chunk from failing test to commit. A chunk is normally one method of one class (or one narrow behavior): you write its tests, watch them fail for the right reason, implement until they pass, refactor away duplication, and commit. Then you stop — the next chunk is a fresh pass.

Tests are run with the wrapper .claude/skills/tdd-py4vasp/run_tests.py, which imports py4vasp from this checkout's src (see Gotchas). All paths below are relative to the repo/worktree root.

0. Scope check — what is this chunk? (do this first)

Decide which of three situations you are in before writing anything:

• An approved chunk list exists. Take the next unstarted chunk and only that one. Its test names are already written down; honor them.
• The request is itself one chunk — one method, one narrow behavior, a focused bug fix with a single reproducing test. Treat the request as chunk 1 of 1 and continue to step 1.
• The work is bigger than one chunk — several methods, a new quantity end-to-end, more than one class, error handling with real logic of its own, or you cannot name the chunk's test in one line. Stop. Do not start coding. Chunk the work with the plan-py4vasp skill, get the chunk list signed off, then come back here for chunk 1.

That last branch is the fallback that matters: a chunk you cannot describe in one sentence is a plan you have not written yet. Reaching for it is cheap; discovering it four files into an implementation is not.

Take it even when you could plausibly implement the whole thing in one pass — the value of the chunk list is that the user sees the shape of the work while changing it is still free. If you genuinely cannot pause for sign-off (a non-interactive or delegated run), you still produce the chunk list first and state it up front, then work it one chunk at a time with a commit each — never a single sweeping commit.

Then, for the chunk you settled on:

1. RED — write the test(s) and watch them fail

Write the test(s) for this chunk only, following the conventions below. Run just those tests and confirm they fail for the right reason — a real AssertionError or the missing-method AttributeError, not a typo, bad import, or wrong fixture. A test that errors before reaching its assertion is not a valid RED; fix the test first.

python .claude/skills/tdd-py4vasp/run_tests.py tests/calculation/test_symmetry.py::test_read -q

Run only the tests you expect to fail. If your change may have side effects elsewhere, add those specific untouched tests to the same run to watch them stay green — but do not run the full suite here.

2. GREEN — implement the minimum to pass

Write the simplest implementation that makes the RED tests pass. Re-run the same selection until green. Resist implementing the next chunk's behavior because it is obvious and nearby — it will arrive without a failing test to justify it.

python .claude/skills/tdd-py4vasp/run_tests.py tests/calculation/test_symmetry.py -q

3. REFACTOR — remove duplication (code AND tests)

With tests green, remove duplication introduced by this chunk and against existing code the new code now overlaps with. Apply the same to the tests: pull shared setup into fixtures and use @pytest.mark.parametrize — this codebase is fixture-heavy, mirror it. Re-run the chunk's tests to confirm still green.

4. COMMIT — one commit for this chunk

Commit the tests + implementation + refactor together, locally, on the current branch. Match the repo's message style (Feat:, Fix:, Refactor: prefix):

git add -A && git commit -m "Feat: add Symmetry.multiplicity"

Do not push or open a PR — that is a separate, later step (push-py4vasp). For a multi-line message use git commit -F <file> or a heredoc, never git commit -m @'...'@ in the Bash tool (it wraps the message in literal @).