Plan Py4vasp

Planning a py4vasp change

A py4vasp plan is an ordered list of chunks — not a description of the finished code with the tests bolted on at the end. A chunk is normally one method of one class (or one narrow behavior): small enough that its tests, its implementation and its commit stay reviewable together.

This skill produces that list and stops. Each chunk is then carried out by the tdd-py4vasp skill (RED → GREEN → refactor → commit), one at a time.

All paths below are relative to the repo/worktree root.

1. Read before you plan

Never plan from the request alone. Establish four things first:

• Does it exist already? Grep for the method/quantity name across src/py4vasp and tests. Partial implementations and near-duplicates are common and change the chunking completely.
• The sibling to copy. Find the closest existing quantity or method and read both its implementation and its test. src/py4vasp/_calculation/symmetry.py + tests/calculation/test_symmetry.py is a good default pair.
• The seams. How does data actually reach the class — raw.access, a FileSource, a dispatcher, @quantity injection? Name the exact file and line the new code hangs off.
• What the request leaves open. Collect the genuine design questions and put your recommended default next to each, so the user can answer with "defaults, except 3".

Questions are half of planning

A request phrased as a question — "are there other things to consider?", "what would it take?", "query me on the open questions" — is still a planning turn. Answer the questions, with your recommended default beside each, and then close with the chunking anyway:

• If the open questions do not change the shape of the work, give the chunk list outright and mark which chunks the answers would affect.
• If they do change the shape (they decide whether a helper module exists at all, say), give the chunk list for the part that is already settled and name the specific answers you need before the rest can be chunked.

What you must not do is answer the questions and stop there. That is how a change ends up planned implementation-first later, in a turn where nobody remembers to chunk it.

2. Cut the work into chunks

• One method or one narrow behavior each. If a chunk needs the word "and" to describe it, split it.
• Each chunk must be independently committable and revertible — green suite at every chunk boundary.
• Order pure logic before wiring. Chunks that touch only a helper module are testable without any public API change; put them first so feedback is fast and early commits are safe.
• Error and edge-case behavior is its own chunk when the errors carry real logic (ambiguity, validation, rejection), not an afterthought inside another chunk.
• The docstring + runnable doctest is part of the chunk that adds the public method, never a separate "docs at the end" chunk.
• Aim for 3–7 chunks. More than that and the request probably needs splitting into two rounds; fewer than two and you likely do not need a plan at all — go straight to tdd-py4vasp.

3. Write each chunk in this shape

Numbered, and for every chunk state all four:

N. <behavior, one line>
   Test:  tests/<path>::<test name(s)>  — what the assertion actually checks
   Code:  src/py4vasp/<path>  — the method/class added or changed
   Also:  any second place that must change for the test to be writable

That Also: line is where py4vasp plans usually go wrong — see the facts below. If a chunk has no Test: line you have not finished planning it.

4. The shape to avoid

Do not produce a plan that describes the implementation in full and then carries a trailing ## Tests section listing the test files to add. That is an implement-then-test plan; it reads fine and it silently discards TDD, because by the time anyone reaches the test section the code is already written. The tests belong inside each chunk, named before its implementation.

Equally: no chunk whose description is "write the tests" or "add test coverage". Coverage is a property of every chunk, not a phase.

5. Present the plan, then stop

Put the chunk list in the todo list, present it, and wait for sign-off before any code is written.

If plan mode is active, this chunk list is the plan you hand to ExitPlanMode — ordered chunks with tests named, plus the design decisions and open questions. Approval of the plan is the sign-off. Do not describe the tdd-py4vasp loop as a final step of the plan; it is how each chunk gets done.