Skip to content

Commit 484e7ff

Browse files
MendixMauclaude
andauthored
process(pr-template, release-process): five-row Impact block on every PR and review (#388)
Every Direct-lane PR and every review fills Process, Dependencies, Context cost, Behaviour, Runtime; RELEASE-PROCESS §4a holds the rule and a bad/good example; CONTRIBUTING lists it as its own merge criterion. Review: independent review MERGE (4 files, +41; render-routing invocation and A/B method pointer verified; merge-tree clean) with four wording fixes applied in ff47b94 (Context "none" when no routed file; agent-read process docs are NOT RUN not n/a; own CONTRIBUTING item; Direct-lane wording). e1f116f: a generated on-demand routing row alone does not require the A/B (found applying the block to 11 open PRs). Context cost 0 (baseline 73,522 / 80,000). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VJgWP5vEoAsNsJYqCDMGNw
1 parent 868b3cb commit 484e7ff

4 files changed

Lines changed: 49 additions & 2 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,17 @@ Nothing to fill in — the field-evidence line inside the file is the whole bar.
1010

1111
**What changed and why (one paragraph):**
1212

13+
**Impact** — all five rows, every Direct-lane PR. "none" or "NOT RUN: <reason>" is legal; a blank row is
14+
not. Reviewers check each row against the diff (`docs/RELEASE-PROCESS.md` §4a).
15+
16+
| Row | Answer |
17+
|---|---|
18+
| **Process** — human steps or gates added/removed; does anything new block; new stage artifacts | |
19+
| **Dependencies** — shared files touched (`_common.sh`, `exec.sh`, `skill-routing.tsv`, …); order vs other open PRs; new tools/platform assumptions; new artifact reads + their producer | |
20+
| **Context cost** — always-loaded words per role at the affected stage(s), base → head, and baseline total vs 80,000, pasted from `bin/render-routing.sh --check` on both — or "none: no routed or always-loaded file touched" | |
21+
| **Behaviour** — A/B result for agent-read text (`process/preflight-skill-baseline-2026-08-31.md`), or "NOT RUN: <why>", or "n/a: scripts only" (process docs that review agents read are agent-read text) | |
22+
| **Runtime** — seconds/resources added or saved per exec, gate or check: measured, or "n/a" | |
23+
1324
**Field evidence** — which real project this ran against / was observed in, and what it measured
1425
or fixed there (CLAUDE.md → "Shipping an instrument", rule 4; required for any instrument change):
1526

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m
1919

2020
## Unreleased
2121

22+
- process(pr-template, release-process): **every Direct-lane PR and every review fills a five-row Impact block: Process, Dependencies, Context cost, Behaviour, Runtime.** "none" or "NOT RUN: <reason>" is legal, a blank row is not. Context cost is pasted from `bin/render-routing.sh --check` on base and head, never estimated; a missing or estimated row is a review finding. The Behaviour A/B (`process/preflight-skill-baseline-2026-08-31.md`) is required for baseline-routed text and agent stubs, recommended for situational skills, NOT RUN with a reason for process docs review agents read, n/a for scripts only; Context cost may be "none" when no routed or always-loaded file is touched. `docs/RELEASE-PROCESS.md` §4a holds the rule and a bad/good example; `CONTRIBUTING.md`'s reviewer list points there. No CI check: `bin/check-pr-discipline.sh` reads the git diff, not the PR body. Field evidence: three PRs reviewed on 2026-10-15 with no process cost stated (#375 added a human step per re-baseline, #384 adds 1–11 s per exec), both found by chance. — maintainer request, MendixMau
2223
- learn(learned-detection-gaps, testing-shape, ui-loop): **a class on a snippet call never reaches the DOM; a 403 bounce and a widget-pinned session probe both read as sign-outs; app restarts matched a "signs me out" report by timing.** Detection-gaps row: `Class` on a `SNIPPETCALL` is green through check, exec, mxbuild, lint and DESCRIBE, and absent in the browser ([#336](https://github.com/MendixMau/mxcli-project-toolkit/issues/336)). Testing-shape §4 gains two false-red rows: `login.html?messageCode=403` with the session kept ([#338](https://github.com/MendixMau/mxcli-project-toolkit/issues/338)), and instruments pinned to one grid name or a typed menu list (1/7 and 7/34 false FAILs after a redesign, [#339](https://github.com/MendixMau/mxcli-project-toolkit/issues/339)). ui-loop: say so before a restart while a human uses the app ([#337](https://github.com/MendixMau/mxcli-project-toolkit/issues/337)) — three-app field run, 2026-10-14
2324
- log(bug-logs): **upstream draft for `mxcli run --local --watch`: a theme-only rebuild deletes `dist/pages` and still reports a successful reload** ([#284](https://github.com/MendixMau/mxcli-project-toolkit/issues/284)). `bug-logs/pending-github-issues/watch-theme-rebuild-drops-dist-pages.md`, status DRAFT — NOT FILED: the repro (one SCSS edit, every page 404s on `dist/pages/<Page>.js`, a restart restores all 135 bundles; twice in one app on mxcli v0.26.0 / Mendix 11.15.0), the other change classes watch serves stale, the timing table (reload 35 builds median 3.8 s, restart 44 builds median 19.2 s, max 55.2 s, 928 s total) and the upstream questions: why a restart is about 5× a reload, and whether a recreated microflow keeps its old compiled version by name. The toolkit side is already on master (exec.sh restart verdicts, `app-restart.sh`, ui-loop.md "What watch picks up"). Field evidence: the 2026-10-12 three-app UX run and its 2026-10-14 recurrence, as recorded in #284. — field retro #284, MendixMau
2425
- fix(close-task): **`close-task.sh` resolves `checkpoint.sh` instead of printing it bare.** The script ships at `claude-hooks/bin/checkpoint.sh` and reaches `~/.claude/bin` only via the opt-in `bin/install-claude-hooks.sh --basic`, so a project without the hooks got a `checkpoint.sh --write` step it could not run. `close-task.sh` now looks in PATH, then `~/.claude/bin`, then `$MXTK_ROOT/claude-hooks/bin`, and prints the full path it found, single-quoted so a path with spaces survives copy-paste. If none is found it prints `checkpoint.sh not installed — run <toolkit>/bin/install-claude-hooks.sh --basic, or skip: RESUME.md is the resume source` and carries on; the exit code still means only "writes owed". `close-the-loop.md` step 4 says the same. The `~/.claude/bin` copy (`claude-hooks/bin/close-task.sh`) now prints its sibling `checkpoint.sh` by full quoted path, because `~/.claude/bin` is usually not on PATH. Fixture `tests/wave2/test-close-task-checkpoint.sh` (14 cases, including a space and `'` in HOME and the toolkit path; 11 fail on master). Field evidence: the reporter's existing-app run, where the closing agent had to skip the step with no pointer. — joshuamoesa (#358)

‎CONTRIBUTING.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,9 +79,11 @@ follow `README.md` → "How to add a new skill" including the routing-table row.
7979
`CLAUDE.md` → "Shipping an instrument — field-proof before merge".
8080
3. A `CHANGELOG.md` line is present and credits the source.
8181
4. Scoped fixtures for the touched files were run, and named in the PR.
82-
5. Squash by default; a merge commit only for a branch whose every commit is already clean —
82+
5. The PR's Impact block has all five rows filled and each matches the diff
83+
(`docs/RELEASE-PROCESS.md` §4a); a missing or estimated Context cost row is a finding.
84+
6. Squash by default; a merge commit only for a branch whose every commit is already clean —
8385
see below.
84-
6. A name found in a PR is rewritten by hand, in the PR, with a placeholder (`ClientX`) —
86+
7. A name found in a PR is rewritten by hand, in the PR, with a placeholder (`ClientX`) —
8587
never auto-replaced. Auto-replace breaks paths, fixtures and credit lines, and the real
8688
name stays recoverable from history either way.
8789

‎docs/RELEASE-PROCESS.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,39 @@ eight moves. A `ready` PR with no activity for 14 days gets `verdict/promote-to-
8787
`CHANGELOG.md`. Over the cap: split the PR or stack it (each layer green on its own, split plan
8888
stated in the PR body before work starts). `size/*` labels this from the diff.
8989

90+
## 4a. The Impact block — what a change costs, stated before review
91+
92+
Every Direct-lane PR fills the five Impact rows in `.github/PULL_REQUEST_TEMPLATE.md`
93+
(Process, Dependencies, Context cost, Behaviour, Runtime), and every review re-checks them.
94+
Why: on 2026-10-15 three PRs were reviewed without anyone stating their process cost; #375
95+
added a human step per re-baseline and #384 added 1–11 s per exec, and both were found only by
96+
chance.
97+
98+
The reviewer, for each of the 5 rows, reads the diff and confirms or corrects the answer:
99+
100+
1. **Process** — every new human step, gate, blocking path or stage artifact in the diff is named.
101+
2. **Dependencies** — every shared file in the diff is listed; every new artifact read names
102+
the mandatory step that produces it (CLAUDE.md → "Shipping an instrument", rule 5).
103+
3. **Context cost** — when any routed or always-loaded file changes, the numbers are pasted from
104+
`bin/render-routing.sh --check` run on base and on head; otherwise "none: no routed or
105+
always-loaded file touched" is the answer. A missing row, or an estimate instead of the pasted
106+
output, is a review finding.
107+
4. **Behaviour** — an A/B per `process/preflight-skill-baseline-2026-08-31.md` is **required**
108+
for a change to always-loaded / baseline-routed text or an agent stub, **recommended** for
109+
situational skill text, **NOT RUN with a reason** for process docs and templates that review
110+
agents read (they are agent-read text, so never "n/a"), and **n/a** for scripts only.
111+
A stub change that is only a generated on-demand routing row (`render-routing.sh` output,
112+
Context cost 0) is not an agent-stub change for this purpose: Behaviour is **NOT RUN: on-demand
113+
row only**, not required.
114+
5. **Runtime** — measured seconds per exec/gate/check, or "n/a" with nothing on a hot path.
115+
116+
The review ends with 5 of 5 rows confirmed; "NOT RUN: <reason>" counts, a blank does not.
117+
118+
| | Context cost row |
119+
|---|---|
120+
| ✗ bad | "Small — a few lines in one skill." |
121+
| ✓ good | "`learned-mdl-preflight.md` +42 words; mdl at Stage 5 30,185 → 30,227; baseline 73,522 → 73,564 (budget 80,000). `render-routing.sh --check` on base and head." |
122+
90123
## 5. Model tiers, by purpose
91124

92125
Described by what each tier is for, not by vendor or model name — a session on any harness

0 commit comments

Comments
 (0)