diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..469b82d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,76 @@ +# ISM_SimulationChecker agent instructions + +These instructions apply to the whole repository. + +## GitHub pull requests and issues + +- Do not hard-wrap. Write each paragraph and each bullet as a single + line, however long. GitHub wraps them for display, and hard breaks + make later edits show up as reflowed paragraphs in the diff. +- Start with a paragraph summarizing what the pull request or issue is + about, then use sections for the detail. +- Use closing keywords for any issue the pull request fixes. +- Do not list individual commits in a pull request description. The + commits are already on the pull request; describe what the change + accomplishes as a whole instead. +- Do not describe testing in a pull request description. Testing goes + in its own `Testing` comment on the pull request. +- Drafts of descriptions, comments and plans are not repository + content. Never commit one. +- An issue should say what happens, what was expected instead, and + enough to reproduce it: the checker version, the command, and the log + lines or the file it was run on. + +## Writing for human readers + +These rules apply to anything a colleague reads: GitHub comments, pull +request descriptions, issues, plans. Not code comments or commit +messages, where a reader who wants the mechanism is already in the right +place. Per-artifact rules and worked examples are in +`.claude/skills//SKILL.md`, as plain markdown. Claude Code +loads the matching one automatically; other agents should read the +matching file before writing that artifact. + +There are two readerships. GitHub prose is read by the checker's +maintainers: developers who know the code's structure and the ISMIP7 +data request at a high level. The user documentation, the `--help` +strings and the checker's messages are read by modelers preparing a +submission, who never read the code and may not have English as a first +language. The `user-docs` skill has the rules for them. + +Never repeat explanations of existing, unchanged features already +explained in `docs`; link to the relevant page instead. Explanations are +appropriate where there is a change, particularly one of a conceptual +nature, and to highlight nuance that informs the current discussion. + +Write less; do not pack the same content into denser sentences. Keep +headings, tables and links. Colleagues mostly write unstructured prose, +and structure is an improvement on it. The problem is length. + +- **Lead with the answer.** The first two sentences say what you found, + changed, or propose. Setup and reproduction go last. +- **One point per paragraph, and few paragraphs.** Colleagues here write + one to three per comment; agent-written descriptions have run to two + thousand words. That gap is the complaint. Say each thing once. +- **Do not narrate the mechanism.** The chain of calls, and why the fix + is right, go in the commit message. Here, say what broke and where to + look. +- **Cut clauses that qualify rather than inform**, and any sentence whose + only job is to justify the one before it. One clause per sentence where + one will do. +- **Use backticks about half as often as feels natural.** They are for + what a reader would type or grep. Code blocks hold artifacts you did + not write, never authored prose. +- **One document, one decision.** Anything still relevant after this + merges is an issue, not a comment. + +Sign anything posted to GitHub on someone's behalf: + +``` +--- + +*Posted by on @'s behalf. The testing, analysis and wording +above are AI-authored; please check them accordingly.* +``` + +Name the agent, not the vendor: `Claude Code`, `Codex`, and so on. diff --git a/CLAUDE.md b/CLAUDE.md index db220c8..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,75 +1 @@ -# ISM_SimulationChecker agent instructions - -These instructions apply to the whole repository. - -## GitHub pull requests and issues - -- Do not hard-wrap. Write each paragraph and each bullet as a single - line, however long. GitHub wraps them for display, and hard breaks - make later edits show up as reflowed paragraphs in the diff. -- Start with a paragraph summarizing what the pull request or issue is - about, then use sections for the detail. -- Use closing keywords for any issue the pull request fixes. -- Do not list individual commits in a pull request description. The - commits are already on the pull request; describe what the change - accomplishes as a whole instead. -- Do not describe testing in a pull request description. Testing goes - in its own `Testing` comment on the pull request. -- Drafts of descriptions, comments and plans are not repository - content. Never commit one. -- An issue should say what happens, what was expected instead, and - enough to reproduce it: the checker version, the command, and the log - lines or the file it was run on. - -## Writing for human readers - -These rules apply to anything a colleague reads: GitHub comments, pull -request descriptions, issues, plans. Not code comments or commit -messages, where a reader who wants the mechanism is already in the right -place. Per-artifact rules and worked examples are in -`.claude/skills//SKILL.md`, as plain markdown; Claude Code -loads the matching one automatically. - -There are two readerships. GitHub prose is read by the checker's -maintainers: developers who know the code's structure and the ISMIP7 -data request at a high level. The user documentation, the `--help` -strings and the checker's messages are read by modelers preparing a -submission, who never read the code and may not have English as a first -language. The `user-docs` skill has the rules for them. - -Never repeat explanations of existing, unchanged features already -explained in `docs`; link to the relevant page instead. Explanations are -appropriate where there is a change, particularly one of a conceptual -nature, and to highlight nuance that informs the current discussion. - -Write less; do not pack the same content into denser sentences. Keep -headings, tables and links. Colleagues mostly write unstructured prose, -and structure is an improvement on it. The problem is length. - -- **Lead with the answer.** The first two sentences say what you found, - changed, or propose. Setup and reproduction go last. -- **One point per paragraph, and few paragraphs.** Colleagues here write - one to three per comment; agent-written descriptions have run to two - thousand words. That gap is the complaint. Say each thing once. -- **Do not narrate the mechanism.** The chain of calls, and why the fix - is right, go in the commit message. Here, say what broke and where to - look. -- **Cut clauses that qualify rather than inform**, and any sentence whose - only job is to justify the one before it. One clause per sentence where - one will do. -- **Use backticks about half as often as feels natural.** They are for - what a reader would type or grep. Code blocks hold artifacts you did - not write, never authored prose. -- **One document, one decision.** Anything still relevant after this - merges is an issue, not a comment. - -Sign anything posted to GitHub on someone's behalf: - -``` ---- - -*Posted by on @'s behalf. The testing, analysis and wording -above are AI-authored; please check them accordingly.* -``` - -Name the agent, not the vendor: `Claude Code`, `Codex`, and so on. +@AGENTS.md diff --git a/README.md b/README.md index b847d46..d938008 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,17 @@ used as submitted. A **warning** means it is usable but departs from what was asked for. Only errors make the command exit non-zero, so it can be run from a script. +## Update + +New releases come often while experiments are still being added. Update +before you check a submission: + +```bash +conda activate isschecker +conda update -c conda-forge isschecker +ismip7-compliance-checker --version +``` + ## Where to read more | | | diff --git a/docs/getting-started.md b/docs/getting-started.md index a5210bf..0ed2a89 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -14,7 +14,15 @@ do not mix. You get two commands: `ismip7-compliance-checker`, the checker, and `ismip7-generate-test-files`, which writes synthetic files the checker passes. -{doc}`user/installation` covers updating and installing from source. + +If you installed the checker earlier, update it before you check a submission: + +```bash +conda activate isschecker +conda update -c conda-forge isschecker +``` + +{doc}`user/installation` has more on updating, and on installing from source. ## Lay out your files diff --git a/docs/user/installation.md b/docs/user/installation.md index 6e96b7e..b11b08e 100644 --- a/docs/user/installation.md +++ b/docs/user/installation.md @@ -22,9 +22,13 @@ can be run from any directory. ## Updating +New releases come often while experiments are still being added. Update +before you check a submission: + ```bash conda activate isschecker conda update -c conda-forge isschecker +ismip7-compliance-checker --version ``` The conda-forge package is built from tagged releases, so it can be a release