Skip to content

chore(agents): add blast-radius skill, comment and testing rules, PR body structure - #2537

Merged
r0b1n merged 1 commit into
mainfrom
r0b1n/pstack-explore
Nov 18, 2026
Merged

r0b1n merged 1 commit into
mainfrom
r0b1n/pstack-explore

Conversation

@r0b1n

@r0b1n r0b1n commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

Pull request type

No code changes (changes to documentation, CI, metadata, etc.)


Why

Agents (and people) working in this repo keep running into the same problems:

  • "Small" changes to shared packages, widget XML or CSS classes break consumers or existing Mendix apps.
  • Code gets cluttered with comments that narrate the code.
  • Tests pin the implementation instead of the behavior.
  • PR descriptions don't say what was verified.

This PR is inspired by pstack, an MIT-licensed set of agent skills. I adapted a few of its ideas to our stack. This is a derived work, not a copy, so pstack is credited only here and not in the files themselves.

What changed

  • New blast-radius skill (.agents/skills/blast-radius/). It finds what a change could break outside its diff:

    • workspace consumers
    • the XML contract with existing apps
    • theme classes and design properties
    • modules that bundle the widget
    • two-way attribute sync
    • keyboard, touch and assistive-tech input

    It then proves the facts the change is safe because of by running code against both the change and its base.

  • AGENTS.md gets two new sections:

    • Code Comments: keep comments to a minimum, and use them only to explain why.
    • Testing: test behavior, not implementation, using a "break the behavior / change the internals" check for every test.
  • PR template: "Description" is replaced by the sections Why / What changed / Scope / Tradeoffs / Blast radius / Verification. Verification includes what used to be "What should be covered while testing?". implementation-plan.md now points to the template instead of keeping a stale copy of it.

  • code-review skill: flags narrating comments, commented-out code and suppressions without a reason, and tests pinned to the implementation. It asks about an empty Blast radius section when shared exports, XML or classes change.

Scope

Agent docs and skills, plus the GitHub PR template. No package code.

Tradeoffs

  • I didn't adopt pstack as a plugin. It's tied to Cursor (Bugbot, Automations, a Gemini model on review panels), and its autonomous merge playbooks conflict with .claude/rules/security.md.
  • I took a softer comments rule than pstack's "no comments" reviewer: comments that explain why are kept.

Blast radius

  • The PR template changes for everyone, including PRs written by people, not just agents. Nothing in CI parses the old "Description" or "What should be covered while testing?" headings (I checked .github and automation).
  • The code-review skill runs in CI (ClaudeReview.yml). The new checks are Low severity, or Questions only, except a lint suppression on a correctness rule without a reason, which is Medium.

Verification

I ran blast-radius blind on three past widget-plugin-grid changes. Each agent checked out the old commit and couldn't see later history.

  • 2f2fbd49d (click classification). It caught the detail === 0 / screen-reader regression that a later commit (68109637c) partly reverted, proven in Chromium. It missed the touch double-tap case. It also found a spec that flakes under turbo load, and a wrong OpenSpec scenario.
  • 78775eb33 (pagination attribute sync). It found and proved 3 of the 6 issues fixed in the following days: attribute writes reverted on setProps, the -1 total-count placeholder written to the attribute, and a preset value overwritten at setup.
  • 692365a52 (a setLimit guard, used as a control). It correctly judged the change safe and raised no false alarms.

I folded what these runs taught us back into the skill: review the whole PR range, rerun every proof on the base, check per-package Tests: lines, and the list of input, browser and attribute-sync checks.

…body structure

- New blast-radius skill: find what a change breaks outside its diff
  (consumers, XML contract, themes, bundling modules, input/a11y) and
  prove the safety facts by running code against the change and its base.
- AGENTS.md: Code Comments (explain why only) and Testing (behavior, not
  implementation) sections.
- PR template: Why / What changed / Scope / Tradeoffs / Blast radius /
  Verification briefing sections; implementation-plan.md points to it
  instead of keeping a stale copy.
- code-review skill: checks for comments, implementation-pinned tests and
  the new PR body sections.
@r0b1n
r0b1n requested a review from a team as a code owner November 17, 2026 13:53
@github-actions

Copy link
Copy Markdown
Contributor

AI Code Review

✅ Approved — no issues found


What was reviewed

File Change
.agents/skills/blast-radius/SKILL.md New skill for finding what a change breaks outside its diff, and proving the safety facts by running code against the change and its base
.agents/skills/code-review/SKILL.md New checks: PR body sections, code comments, tests pinned to the implementation
AGENTS.md New "Code Comments" and "Testing" sections
.github/pull_request_template.md "Description" replaced by Why / What changed / Scope / Tradeoffs / Blast radius / Verification
docs/requirements/implementation-plan.md Stale PR template copy replaced by a pointer to the real template

Skipped (out of scope): none. This PR changes docs and agent skills only, with no package code.

CI: pending: Plan E2E matrix, Read versions file, Run code quality check, sigridci · unrelated failures: security/snyk (dependency scan on a docs-only change)


Positives

  • The new rules in AGENTS.md, the code-review skill and the PR template agree with each other. The Medium escalation for suppressions of correctness rules is a sensible exception to the Low default.
  • Replacing the duplicated PR template in implementation-plan.md with a pointer removes a copy that would have drifted out of sync.
  • The blast-radius skill requires each proof to be run against both the base and the change, and tells the reader to mark facts as unproven when they can't be proven.

@r0b1n
r0b1n merged commit 1a2aa94 into main Nov 18, 2026
13 of 14 checks passed
@r0b1n
r0b1n deleted the r0b1n/pstack-explore branch November 18, 2026 08:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants