[OmarAlJarrah]

Summary

Reviews and fixes here spend much of their time rediscovering how work in this repository is verified: which probe answers a claim, which controls a differential needs, which reader of a construct a change missed. Those lessons live only in reviewers' heads and in the history of PRs that fixed defects after their first push. This adds them as skills under .claude/skills, which coding agents load when a task matches. Each skill's body loads on demand and its reference files load one at a time.

Skill	Loads when	Holds
morphic-verifying-changes	writing a test, a verifier, a lint or archtest rule or a skill's script, fixing a defect, claiming something is caught, comparing with main, stating a count	what done means here (nothing left to find, a defect main shares fixed or filed, a fix at the type that owns the broken state); claim → probe table; rules for claims, counts that drift, sweeping every site, tests, assertions, checks that reach what they claim, planting defects in a throwaway worktree and reading the test command's own output, differentials, toolchain traps; sweep.py, which prints facts and leaves their meaning to the reader
morphic-reviewing-prs	reviewing a PR or its final state	the review passes, a first round that checks every class of claim in full and reviews its own fixes before pushing them, probes that found what earlier rounds missed, and the verifying and shipping rules a review applies, by path
morphic-shipping-prs	committing, writing commit messages or PR text, opening or updating a PR, merging main in, splitting a change into commits	commit, title, body and closing-keyword rules, what a commit may hold, recorded decisions, what a merge of main can lose, and the review's first round run by the author before the first push; the push checklist of commands, which a review also runs
morphic-changing-the-ir	work under ir/ or pass/, the IR and emitter design documents, IRVersion	the design steps and what an IR change drags along, version collisions between open PRs, the hand lists a new field meets, invariants a type held, what the verifier and codecs must reach
morphic-measuring-performance	a speed or memory change, a cost or allocation test, a benchmark, a claim that a change is faster or cheaper	claim → measure table; tests that pin a cost, and where cost hides
morphic-openapi-compiler	touching compilers/openapi, its corpus or its keyed docs	where the rules, library behaviours and tests live; lowering, diagnostics, grammar and load-phase rules
morphic-curating-skills	a lesson worth keeping, or an edit under .claude/skills	where a lesson goes, the rule format and limits; skills_lint.py, which checks both

The rules come from two sources: defects past PRs fixed after their first push, and probes that later review rounds found effective. Every rule has one format (a heading, a stable key, then Rule, Why and an optional Probe), stays within 150 words, and cites in its Why the PRs or issues whose work showed the failure, which an item's record may not describe. A lesson has one home: rules teaching the same thing from both sources are merged, and each sits in the skill whose trigger fires when it applies, so the counting and sweeping rules an author needs live in verifying-changes, and the commit and PR rules in shipping-prs, which reviews read by path. A skill links to CLAUDE.md, docs/compilers/openapi.md and docs/parser-library.md rather than restating them; parser-library behaviours stay in that page. CLAUDE.md gains two paragraphs. One says where the skills are, for agents that do not discover them on their own. The other says they are experimental: an agent treats what a skill says as a claim to check, confirming what a script prints with a probe of its own and a rule's fact about the code on main, says after using a skill how it served, and files each flaw as a skills: issue under the repository's filing rules. The tracker and label commands CLAUDE.md and docs/micro-compiler-plan.md quote now pass --limit 1000, as the skills' copies do: gh stops at a default number of results and, outside a terminal, says nothing of the rest.

Decisions to look at

• Tracking part of .claude/. refactor: remove duplicated code and scaffolding across the repository #97 ignored .claude/ as agent scratch space, and repo: static coverage badge and internal gitignore entries #91 asked that .gitignore list only project content. Skills are reviewed project content that agents read in place, so .gitignore now ignores .claude/* and re-includes .claude/skills/; everything else there stays ignored. A clone whose own .git/info/exclude lists .claude/ has to narrow it to .claude/*, because an excluded directory is never searched for the negation: such a clone keeps the tracked skills, but a new skill file is missing from git status and refused by git add. The comment beside the rule in .gitignore says so.
• Skills stay apart from the codebase. Nothing in the gate reads .claude/skills: archtest's walks and the keyed-doc citation checks skip dot-directories, and the scripts are not Go. skills_lint.py holds every path in a code span, test, § section and #key a skill names to the tree, and the scripts to their form; morphic-curating-skills says to run it after every edit, and how to run each skill's script tests. The push checklist chains each push on the same lint, and a review runs it on the PR's tree, so a code change that renames a test or path a skill names meets it before its push and in its review.
• Reviews run on the tree as it will land. The review skill checks the PR out merged into main, with the commands it gives, so every probe and the comparison with main see what merging would produce, not a branch that also undoes main's newer commits. A head that already contains main merges as a no-op, and CI's run on it covers that tree; a head that conflicts is reviewed alone and the conflict reported.
• The first review round is the review. Before that rule existed, this PR's own review took nine rounds. Rounds sampled a class of claim before a later one swept it: citations were read for 58 of the 203 rules before all 383, and the full read found a misattribution the sample had missed. A finding fixed in one file, restated library behaviour, met the same in another six rounds later. Fixes went out unreviewed, so later rounds found defects they had added: a body example the scripts listed as a closing reference, a command that failed from the repository root, and a sentence saying the lint ran on every branch. The review skill now has the first round check every member of every class of claim and review its own fixes before pushing them, sweep-every-site-of-the-mechanism now triggers on a review's finding as on a fix, and the shipping skill has the author run that round before the first push.
• A citation names the work, and the Probe checks the rule. Many process lessons came from the work on a PR rather than from its record: feat!: model OAuth flows fully and validate every lowered object #878's record never mentions the fold that reverted fix(compilers/openapi): warn on a construct a later version added #870 while it was prepared, and pass: give transform passes a sanctioned way to replace and remove types #966's and fix(compilers/openapi): refuse a tagged mapping before it faults #475's never mention the stash a pop applied. Their records show the fix and not the slip behind it, so marking each citation by whether its record shows the clause would rest on judgments with no crisp answer, which a later comment on the item could undo. A Why's #N names the work a failure showed in instead, which still exposes a citation naming the wrong item, and a rule is checked by its Probe; the curating skill states it in the rule format, and CLAUDE.md beside the skills.
• Every finding is fixed or justified. The review skill ranks findings issue:, nit:, suggestion: and question: to order the work, not to decide what may ship: as CLAUDE.md requires, every issue: and nit: is fixed or justified in writing before merge.
• Breaking API is read with apidiff. Whether a change needs ! turns on the exported API it removes or changes. The breaking-change rule's probe runs the Go team's apidiff, pinned to a version, on export data written at the merge base and at the head: it type-checks both sides and applies Go's compatibility rules, so it sees interface methods, fields, grouped members and declarations moved to another package. It misses a struct tag, which TestIRVersion_PinsTheEncodedShape holds in ir. A script that parsed go doc instead took 283 lines, and review found it crashing on a valid signature layout; the command replaced it. The rule calls a method added to an exported interface breaking only when the interface has no unexported method: apidiff reports the same addition compatible on an interface sealed by an unexported method, as each sum in ir is, and incompatible on an open one, where the rule had called every such addition breaking.
• Two scripts, where twelve were written. A script stays only where it does what an agent cannot do reliably by running a command and reading its output: hold an invariant through a crash, count or compare exactly, or check every member of a large set. It prints facts, never a verdict parsed from a tool's output. Two meet that bar: sweep.py, which builds two binaries and compiles a corpus with each in parallel, comparing their outputs byte for byte, and skills_lint.py, which holds every name the skills cite to the tree. Ten more were dropped. Seven, about 1,400 lines with 1,150 lines of tests at ee6fdd2f, gave confident wrong answers where a command or an existing tool did the job. Three, mutate.py, preflight.py and artifact_scan.py, about 650 lines with 900 lines of tests at 8beb0309, each ran a tool and parsed its output into a verdict, and that parsing was where review kept finding defects; an agent reading the output itself does better. A defect is now planted in a throwaway worktree, which makes unnecessary the restore mutate.py existed to guarantee, and the push checklist and the artifact grep are commands in the shipping skill: the checklist holds each commit subject and the title, as the squash lands it, to the form and the cap, as preflight.py did, and the body's sections, which it also checked, are a rule the shipping skill states. The rules that named the dropped scripts give the commands instead, and the curating skill holds any new script to the same bar.
• Scripts are Python 3.14, standard library only. Each declares requires-python = ">=3.14" in a PEP 723 script block, which uv run and pipx run read and the lint requires, and every command runs it as python3.14. Each is also executable and starts with #!/usr/bin/env python3.14, which the lint requires too, so one run as ./script.py takes the same interpreter. An older python3, such as the 3.9 macOS ships with its developer tools, fails at import with exit status 1 or 2, and 1 is the status each script gives a finding or a difference, so no command leaves the interpreter to chance; a missing python3.14 exits 127. Python is not among CONTRIBUTING.md's prerequisites; CLAUDE.md names 3.14 beside the skills. A first version in bash kept hitting differences between macOS and Linux shells (sed -i, timeout, awk record separators, bash 3.2 arrays); the standard library covers the same work on both. Each script has a unittest file beside it. The Agent Skills specification's own validator, skills-ref, needs third-party packages, so the lint checks the specification's frontmatter rules itself.

Test plan

• skills_lint.py is clean, and catches each planted defect: a missing path in backticks or in prose, a missing test, § section, #key and skill; a machine path; a memory-style link; a reference file no SKILL.md names; a script that is not Python 3.14, has no test beside it, declares no requires-python = ">=3.14" script block, has no #!/usr/bin/env python3.14 first line, or is not executable; and an import outside the standard library. Frontmatter is held to the Agent Skills specification and to what a YAML parser reads whole: a name of 1-64 lowercase letters and digits joined by single hyphens, only the specification's fields and each once, and no plain value holding an unquoted : , a trailing : or #, which a YAML parser refuses or reads as a comment that cuts the value; ten planted defects in those checks each turn the suite red, and a : planted in a real skill's description is reported at its line. A quoted name or description is read as YAML reads it, so a description quoted as the lint advises passes, where the lint had read the quotes raw and reported it as not starting "Use when"; a quoted value is matched as YAML closes it, so one ending in an escaped quote, which YAML cannot parse, is refused, and a comment may follow the closing quote. A block scalar is refused with the advice to write the value as one plain or quoted line, and the body's word limit is still checked. Ten planted defects in that reading each turn the suite red. A bad link target is reported once. A file named without its directory, such as sweep.py, must be a file the tree holds, and each script must be named in its SKILL.md; that check once found a script named in no skill. Paths inside commands are checked too, placeholders such as <spec> and {owner} aside. A POSIX bracket class is not taken for a link. A rule is cited as references/<file>.md#<key>: a citation whose file holds no such rule is reported, so is a bare span naming a rule key without its file, and renaming a key or citing the wrong file on the real tree is caught at the citing line. Each rule is held to the format: a heading with no key, a key used twice across the skills, an extra or missing bullet, a stray line, a Why citing no PR or issue, and a rule over 150 words are each reported, and planting a defect in each of those checks turns the suite red. The prose check found one rule still naming scripts/check-coverage.sh, removed in build: judge the coverage profile with golang.org/x/tools/cover #828. A code span a line break splits is reported once, outside fenced blocks, because every check reads one line at a time and never reads such a span: the check found one, a gh issue list command no sweep of the skills' commands had read. It reads a fence as CommonMark does (backticks or tildes, indented up to three spaces, opened by no backtick run whose info string holds a backtick, and closed only by a bare run of the same character at least as long), and three planted defects in the check and six in its reading of fences each turn the suite red. A § section citation holds spaces a wrap can fall on, so its check reads on into the next line and reports a citation once, at the line it starts on; none is split today. Two planted defects in it each turn the suite red, and a third, continue for its break, survives because it changes nothing. A path in a code span or a command is held to the tree whatever its first segment: with barrier/ renamed to guard/ the rule citing barrier/text.go read clean, and so did a misspelt compiler/openapi/..., and both are now reported. What a span holds that names no path is told apart by its form (a pointer, flag, pathspec magic, pattern, URL or placeholder) or by a named first segment (a remote's branch, a Go package, a diagnostic code), and seventeen planted defects in that each turn the suite red. A § that follows no document's name, as the second of "ir-design §15 ... and §16" did, is reported, an RFC counting as a document; three planted defects in it each turn the suite red. A description over 500 characters, the limit the curating skill now states with its reason, is reported at 501 and not at 500; the 1,024-character frontmatter cap, which no source gave and no test reached, is gone. The lint takes no argument: --help prints its usage and any argument is refused with exit 2, where --help had run the whole lint and an option it lacks, such as --strict, had exited 0 as a clean lint; two planted defects in that refusal each turn its suite red. A path, link target, skill or command name and cited reference is held to the files git lists, untracked ones included, and to the directories above them, where the lint had read the disk: with an ignored file on disk under docs/superpowers/, a code span and a link naming it had read clean, and both are now reported as ignored by git, and a link out of the repository as missing. Ten planted defects in that holding, a fallback to the disk at each of its six sites among them, each turn its suite red. A span under .git/ names git's own files, which every clone has and a worktree keeps elsewhere, and is left out of that holding: the lint had called .git/info/exclude ignored by git in a clone and missing in a worktree, and dropping the exemption turns its suite red. Git's file list is read whole, with ls-files -z: git quotes and escapes a name holding a non-ASCII letter, so a tracked file named that way had been missing from the tree, and dropping -z turns its suite red. The lint holds a path in a span up to its # entry, :line or glob, and the real skills rely on the entry and the glob, without which it reports 11 and 2 false findings; no test held the three cuts, nor the skip of a tracked test file deleted from disk, without which the lint exits 2 in the middle of a change that removes one. The clean fixture now names each form and the tree test deletes a tracked test file, and a planted defect in each of the four turns the suite red.
• sweep.py over testdata (213 specs, compiled in parallel): with base equal to head, nothing differs, it exits 0, and both sides' exit-code distributions and IR byte totals print. With IRVersion planted at 9.9.9 in a throwaway worktree, 210 of them differ and it exits 1; the other 3, refused alike on both sides, agree, and results.tsv shows their exit codes. A document written as JSON, even one saved as .yaml or .yml, is judged by its top-level keys, and any other by a version key ending at its colon: the sweep had taken the 56 conformance goldens for specs, since their coordinate keys such as "openapi:schema" read as version keys, and counted them among 269, and it missed a minified spec in a corpus of about two thousand published ones. Over that corpus it now gains that spec, drops eight files that are not specs, and keeps a JSON spec saved as .yaml. A spec, YAML or JSON, saved with a byte-order mark is found too, as the compiler reads past the mark; six planted defects in the detector each turn its suite red. A -t or -j under 1 is a usage error, and five planted defects in that logic each turn its suite red. The sweep judges nothing: under an unknown compile flag every spec exits 2 on both sides, and it reports that no spec differs and exits 0, while the distributions it prints, 2 for all 213 and no IR bytes, show that neither build compiled anything; the differentials reference gives morphic's exit codes as compile --help states them, where it had said a spec with findings exits 1, though one with only warnings exits 0, and says that agreement on 2, 137 or a negative code says nothing. A spec file given as the corpus is read as one document, where it had been searched as a directory and drawn "no OpenAPI or Swagger documents", and dropping that read turns its suite red; run from ir/ on one conformance spec at -b HEAD, the sweep reads no difference. Its hint for a spec that differs names the IR pair beside the diagnostics, where it had named the diagnostics alone, which show nothing for a difference in the IR only; reverting the hint turns its suite red. Its report is now pinned whole: four planted defects, printing no IR bytes, reading both totals from one side, dropping the list of differing specs and writing absolute paths, had passed its suite, whose test of results.tsv keyed on spec names, and each now turns it red, the test resolving its root as the sweep resolves each spec. --help prints the docstring, whose usage line runs from the repository root and which says what each option does and which files are read, where it had listed the option letters alone. The base worktree is removed afterwards.
• The revert probe in tests-that-bite.md, run on fix(cmd/morphic)!: report a stop only for a run it stopped #1136's fix, reverts its code alone in a detached worktree, keeping its tests and fixtures, and six cmd/morphic tests go red.
• The rules' statements about how the code behaves were probed on main rather than read: where harness.Check stops, how the canary classifies a child's crash and quiets the collector, how the TypeDef kind lists find members, what OnVerify wraps, how costAround averages, what the shape pin prints, and that no conformance spec holds an alias all hold. One did not: a stale entry is refused in idPositions and stringLists and passes only in integerFields, which the IR skill now says, where it had said no table notices one. Each Why changed since the citation reading was checked against its item's work: one credited feat(ir)!: flatten composition with defined order and override #1141 with a full disk emptying a file, where feat(ir)!: flatten composition with defined order and override #1141's full disk left a mutant planted and the emptied file was a probe on chore(skills): add the repository's agent skills #1143, and one cited chore(skills): add the repository's agent skills #1143 without saying what its work showed; both now say it. Two more named no failure at all, for feat!: own I/O in the engine and lower each file of a split spec #1009 and feat(compilers/openapi)!: resolve schema $refs in the compiler #1016, and now say what each showed. irverify: a stale integerFields entry for a deleted field passes #1148 tracks making integerFields refuse a stale entry too, and the rule cites it until that lands.
• Each quoted probe runs from the repository root as written. The go test and go build templates that named no package failed there with "no Go files", and now name ./<pkg>; the version-claim loop reads every open PR rather than gh's default 30; and the apidiff comparison is the pinned go run command, which reports feat(ir)!: type the inferred-marker list and verify its form #1142's changes to ir, where it had named an apidiff binary no setup installs. recorded-base's probe reads from the merge base: in a scratch repository, a two-dot diff against origin/main listed main's newer file after a correct fold, while the three-dot diff lists the branch's file alone there and the reverted file after a fold onto a moved main. count-work-not-wall-clock leaves its assertion to marginal-growth-on-one-path: it had prescribed work(2n) <= 2*work(n) + c, while the test it cites asserts a ratio of totals and the next rule says such a ratio lets a quadratic term hide behind fixed cost. perf-guards-measure-the-defect had a cost test time the function under test, and nondeterministic-tests-proven-stable said how to build a timing ratio, where the measuring skill pins a cost by counting work and no test on main times a ratio; a benchmark now times and a cost test counts, and the timing sentence points at the counting rule. The tracker searches the skills quote pass --limit 1000: outside a terminal gh lists 30 with no sign of the cut, while a search for Unmodeled matches 131 issues.
• Every rule and skill body was reread against what a sentence must do: be checkable, live in one home, and be specific. Five rules whose Rule is no check gained a probe, three of them run on main (both planted defects in barrier's cut fail a test, a file referenced as ./a.yaml and ./x/../a.yaml is one source, and load refuses an alias cycle as openapi/cyclic-ref). acyclic-trees now cites the parser-library entry it rests on, environment-independent-tests covers every platform branch, two hedges became statements, and a new rule, fix-at-the-invariants-owner, records openapi: a $ref back into a schema still being lowered crashes the compiler #749's lesson. verifying-changes and the OpenAPI skill now open with the bar their work is held to. No rule puts a count beside the list it counts, as derive-never-maintain asks: four did ("the other two tables", "all three sizes", "all four documents", "two suffixes"), and a scan of every number in the skills' prose outside the Why lines found no other.
• The push checklist's artifact grep finds thirteen of the fourteen lines the dropped scan's tests planted, all but a generated-by line naming no assistant, flags none of the eight they kept clean, such as .claude/skills, CLAUDE.md, a brief description and a golden generated with -update, does not match its own text, and finds nothing in this PR's commit messages, added lines, title or body. Run as the shipping skill gives it under bash and zsh on this branch, the checklist prints only the lint's clean line. Its subject check reads the title too, with the number the squash appends, where the checklist had measured the title's length alone: a prose title, one of 65 characters before the number and one ending in a period each print, and one of 64 does not. It passes --no-merges, since a first version flagged the branch's merges of main, whose subjects no form fits.
• The commands that replaced the review, version-claim and API scripts were run as the skills give them: the review setup on this PR (the second fetch leaves the PR's head in FETCH_HEAD, and the merge is a no-op), the gh pr diff loop for version claims (it lists feat(ir)!: scope servers to operations by ID, home wire facts #1144 among the five open PRs, and names a PR whose diff did not load, tried with a number no PR has), and the apidiff commands on fix(compilers/compile)!: give a shared primitive no source #551's commit (NewTypes: changed from func(int) *Types to func() *Types), on fix: close the losslessness gaps and the guards that missed them #185's, which moved CanonicalWords into ir (CanonicalWords: removed), and on refactor(compilers/openapi): extract the lowering context #218's, which retyped the grouped constants GroupByPathPrefix and GroupByTags in compilers/openapi onto an internal type, each reported. After the cut the lint is clean and each kept script's suite passes.
• A script that crashes exits 2, which neither script uses for a finding or a difference: a test runs sweep.py with git missing and the lint with an unexpected error, and dropping either guard turns its suite red.
• The scripts' unit tests pass under Python 3.14, none skipped, and planted defects (the bare-name and script-mention checks and load_tree in skills_lint.py) each turn a suite red, as do four planted in the lint's 3.14 checks (the script block, the standard library, the rule bounds and the parse target) and four in its first-line and mode checks (either check removed, the first line matched anywhere in the file, and the shebang naming python3); a script made not executable on the real tree is reported. Both scripts were run on the final tree from ir/, both as python3.14 <script> and through their own first line; the runs above that predate the 3.14 requirement were made under 3.9.
• Each suite was run under the standard library's trace, and every decision path it left unexecuted gained a test: in skills_lint.py, a skill with no SKILL.md, a frontmatter that never opens or never closes, the skips for URL links and __pycache__, the wiring that hands the real tree to the checks, a tree declaring no test, each exit status and an unexpected error; in sweep.py, an exit-code difference, flags after -- reaching each compile, the warning for a base the branch lacks, the run that builds both sides and removes the base worktree, and each exit 2. Re-planted on the final tree in a throwaway worktree, with each suite's own output read, thirty-five planted defects, twenty-four in skills_lint.py and eleven in sweep.py, each turn a suite red, and a comment-only control in each passes. That control first failed in the sweep's suite: a test expected spec paths relative to its temporary directory, which under macOS's default /tmp, a symlink, they are not, and it now resolves that directory as the sweep resolves each spec. Fifteen more planted on the final tree each turn a suite red, seven in skills_lint.py and eight in sweep.py, among them the eight that the first two bullets name as having passed; two survive that are equivalent: a relative import, which fails in any script run as __main__, and -j, which changes no output. What trace still lists as unexecuted runs only in the suites' subprocesses.
• The gh commands CLAUDE.md quotes were run with and without a limit. gh label list read 30 of the 34 labels and left out priority:P1 to priority:P4, which every issue carries; gh issue list --state open --json title read 30 of 250 open issues; and the decision search, which read open issues only, found 2 of the 16 issues for ir.Naming, without compilers/openapi: the webhooks group is named as if the source declared it #184, the closed issue its own example cites. With --limit 1000, and --state all for the decision search, each reads every result, compilers/openapi: the webhooks group is named as if the source declared it #184 included.
• make gate passed on the first commit; no step reads the new files. The branch's later changes touch only .claude/skills, CLAUDE.md, the status line of docs/micro-compiler-plan.md and the comment on the .claude rule in .gitignore; of those, internal/archtest reads the two documents, and internal/keydoc and TestLoweringSpec the citations in them, and each passes on the final head. main is merged in, and the lint and the artifact grep are clean on the merged tree.