AgentSkillsCN

chemthermo-change-loop

在本化学热力学代码仓库中实施或审查变更时，请务必遵循仓库契约：首先通读“.agents/brain/brain.md”，严格遵守SI单位与公共API的不变性原则，以精简且可运行的垂直切片形式交付代码，并通过与CI等效的质量门控（ruff format、ruff format --check、ruff check、pyright、pytest）进行检验；同时，确保可编辑与不可编辑安装的烟雾测试顺利通过，并在架构或公共API发生变更时，及时更新ADR与脑图文档。

SKILL.md
--- frontmatter
name: chemthermo-change-loop
description: Use when implementing or reviewing changes in this Chemical-Thermodynamics repository. Apply the repo contract by reading .agents/brain/brain.md first, preserving SI-unit and public-API invariants, shipping thin vertical slices with a runnable golden path, running CI-equivalent quality gates (ruff format, ruff format --check, ruff check, pyright, pytest), verifying editable and non-editable install smoke checks, and updating ADR/brain docs when architecture or public API changes.

Chemthermo Change Loop

Inputs

  • •User request and acceptance criteria
  • •Files expected to change
  • •Whether public API or architecture boundaries are affected
  • •Local environment status (Python 3.11+, editable install)

Workflow

  1. •Establish scope and constraints.
  • •Read README.md and .agents/brain/brain.md before structural edits.
  • •If the change is architectural or API-facing, read relevant ADRs in .agents/brain/adr/.
  • •Confirm scope policy remains consistent across docs: VLLE and PC-SAFT are in scope, and no thermodynamic capability class is categorically out of scope.
  1. •Classify the change.
  • •Treat edits touching src/chemthermo/__init__.py, src/chemthermo/eos/__init__.py, or src/chemthermo/vlle/__init__.py as public API-sensitive.
  • •Treat changes to solver/model internals as invariant-sensitive (SI units, composition validation, deterministic flash behavior).
  • •Treat notebook edits as hygiene-sensitive (strip outputs, keep runnable narrative).
  1. •Implement a thin vertical slice.
  • •Prefer the smallest end-to-end usable increment over scaffold-only work.
  • •Declare the slice explicitly before implementation: "After this change, user can X by running Y."
  • •Keep interfaces and behavior coherent across code, tests, and examples.
  • •Avoid opportunistic refactors unrelated to the requested change.
  1. •Validate in escalating order.
  • •Run focused tests for touched modules first.
  • •Run canonical bootstrap, CI gates, and golden path from .agents/dev-contract.md.
  • •Run installability checks from .agents/dev-contract.md (pip install -e ".[dev]" path and pip install . smoke via tools/smoke_install.py).
  • •Use the cheap-check subset in .agents/dev-contract.md during iteration, then run full CI gates before finalizing.
  • •If validation extras are installed, run optional reference checks under tests/validation/.
  1. •Update docs and decision records.
  • •Update README/examples/notebooks docs when user-visible behavior changes.
  • •Update .agents/brain/steering-brief.md when architecture context changes.
  • •Add or update an ADR for public API or architectural decisions.
  1. •Report outcomes clearly.
  • •Summarize what changed, what was validated, and any known risks.
  • •Include thin-slice evidence from .agents/dev-contract.md (slice declaration, golden path, focused tests, CI checks, install smoke).
  • •If any checks were skipped, state exactly which checks and why.

Mandatory completion checklist (hard gate)

  • •Slice declaration is present: "After this change, user can X by running Y."
  • •At least one golden-path command/test was run and outcome reported.
  • •Focused tests for touched behavior were run and outcomes reported.
  • •CI-equivalent checks were run and outcomes reported.
  • •Editable and non-editable install smoke checks were run and outcomes reported.
  • •User-visible behavior changes include docs updates in the same slice.

Notebook-specific checklist

  • •Keep notebooks in notebooks/ runnable top-to-bottom.
  • •Preserve concise markdown context for each code block.
  • •Ensure outputs are stripped before commit (nbstripout workflow).
  • •Keep supporting utilities in notebooks/_nb_utils.py or regular modules when reuse is needed.

Guardrails

  • •Do not invent thermodynamic constants, component data, or external-reference results.
  • •Do not loosen CI or invariant checks unless explicitly requested.
  • •Keep commits small and logically grouped.
  • •Keep the working tree clean at handoff.