Simulate User Py4vasp

Simulating a py4vasp user

plan-py4vasp, tdd-py4vasp and review-py4vasp all judge a change from the inside: code, tests, coverage, house rules. A change can pass every one of them and still be unusable, because none of them asks the only question a user asks — can I work out how to do this from the documentation?

This skill answers that by dispatching a subagent that role-plays a user with no access to the source. It is a validation gate, not an exploration: you write the premise, dispatch it, verify it stayed inside the rules, and act on what it reports. All paths are relative to the repo/worktree root.

When it is required

Whenever the diff touches the user interface:

• a public method or class (no leading underscore) under src/py4vasp/_calculation/ whose signature or docstring changed, or one that was added. The docstring counts because it is the documentation a user reads: a branch can rewrite thirty of them, leave every def line untouched, and change the interface completely.
• any change to src/py4vasp/cli.py
• any change under docs/

A change confined to private helpers, the raw schema, the demo data or the tests does not need it. push-py4vasp treats this as a blocking gate and its driver prints USER SIMULATION REQUIRED: YES/NO, so the decision is a fact rather than a judgement.

Step 0 — do NOT run this from plan mode

Check first. A subagent inherits plan mode from the session that dispatches it, and a simulated user in plan mode cannot write a POSCAR, cannot use -o/--output, and cannot read an input file from disk — i.e. it cannot exercise the surface a real user touches most. In the trial run that produced this skill the agent tried to work around the restriction with a process substitution, which is not something any user would do, and the resulting traceback leaked source code to it.

If plan mode is on, say so and stop. Run the simulation from normal mode.

Step 1 — write the premise (without naming the API)

The agent must discover the feature, because discoverability is the thing under test. Give it exactly what a colleague would have said in one sentence — the capability, never the command or method names:

A colleague mentioned that the latest py4vasp can create KPOINTS files for you — both for a band structure along the high-symmetry path and for a regular k-mesh — and that it works from the command line as well as from Python.

Derive that sentence from the MR description, not from the diff. If you catch yourself writing generate_kpath, delete it.

Step 2 — dispatch

Use the Agent tool with subagent_type: general-purpose and the default model. Never fork: a fork inherits your context, which contains the implementation, and the whole exercise collapses. Capability is not what makes a simulation unrealistic — access is — so do not reach for a weaker model either; a capable agent constrained to the documentation writes a far more useful report.

The prompt must contain all six blocks below. Copy them; the wording matters.

1. The persona. A computational materials scientist who runs VASP, comfortable with the shell and Python, has never seen py4vasp's source and never will. Then the premise from Step 1.

2. The isolation contract. Allowed, because it is what a real user has: py4vasp --help and every subcommand's --help; help(obj) and obj? at the Python prompt (docstrings are user-facing documentation); the sources under docs/; README.md. Forbidden: any file under src/ or tests/; git history, diffs, commit messages, branch names; .claude/; any plan, issue or notes file. And the clause that matters, because this is how leaks actually happen: if a tool result shows you source code — a traceback will — stop reading it and write that down in your report.

3. Behave like a person, not an agent. A handful of actions in a natural order. No enumerating the package, no reverse-engineering intent from the repository. When the documentation does not answer a question, that is a finding to report — not a puzzle to solve by digging.

4. The environment. py4vasp is usually a development checkout here, so spell out the invocation and tell the agent to treat it as the real command:

export PYTHONPATH=<checkout>/src
PY=<path to the venv>/bin/python
$PY -m py4vasp --help          # the command line interface
$PY -c "import py4vasp; ..."   # the Python interface

Give it a working directory of its own (/tmp/.../user-trial-<feature>), explicitly grant it permission to write files there, and forbid modifying anything in the checkout.

5. The task. Work out from the documentation how to use the feature and note what had to be guessed; write your own input file and use the feature on it; do whatever you would normally do to convince yourself the result is right, and say whether you could; make one or two mistakes a real user plausibly makes and see whether the message tells you what to fix; try both interfaces if both exist.

6. The deliverable. Five sections, in this order:

• A. Narrative — what you did, in order, with the exact commands, including the dead ends.
• B. Findings — each with the command, what you expected, what happened, and what would have helped; ranked would have stopped me versus annoying; documentation gaps are first-class findings; and for each, would an ordinary user have noticed this at all?
• C. Verdict — can a user who only reads the documentation succeed? yes / partly / no, and why.
• D. Documentation trail — every source consulted, in order, and whether it helped.
• E. Confessions — anything you did that a real user could not; any rule you broke; any false alarm you raised and then retracted; and every moment you wanted to read the source, and what question drove the urge.

Close with: do not soften the report to be agreeable; blunt is useful.

Sections B-"ordinary user", D and E are what turn a report into evidence. The trial run's most valuable line was the agent volunteering that an ordinary user would not have caught its own worst finding, because the only symptom was a space-group label nobody checks by eye. D localises the documentation gap to the exact channel. E is where the leaked traceback got reported.