one-semantic-change

Enforces one semantic purpose per pull request through scope contracts and diff justification.

1|Updated Aug 11, 2026
One-click install
npx skills add https://github.com/0xMuluh/package-development-skills --skill one-semantic-change-0xmuluh
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: one-semantic-change
Source: https://github.com/0xMuluh/package-development-skills/tree/main/one-semantic-change
Command: npx skills add https://github.com/0xMuluh/package-development-skills --skill one-semantic-change-0xmuluh

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Pull requests often accumulate unrelated changes—opportunistic renames, formatting noise, dependency cleanup—that make review difficult and rollbacks risky. This Skill enforces the discipline of one semantic purpose per PR so every changed line is justified by a single stated intent. ## Core Features & Use Cases - Scope Contracts: Write a pre-implementation contract defining the problem, intended change, non-goals, behavioral boundary, and evidence before touching code. - Diff Justification & Scope Creep Detection: Classify every changed line as necessary implementation, test, documentation, or unrelated, and remove or split anything that cannot be justified. - Split Patterns & Review Checklist: Apply proven patterns for separating bug fixes from refactors, migrations from redesigns, and renames from behavior changes, then validate with a structured review checklist. - Use Case: While fixing a selection bug, you notice a helper with an ugly name and an unused dependency. Instead of bundling all three changes, this Skill guides you to ship the bug fix with a regression test and record the rename and dependency removal as separate follow-up PRs. ## Quick Start Ask the AI to apply the one-semantic-change skill to plan or review your pull request and verify that every changed line serves a single stated purpose.

Frequently Asked Questions about one-semantic-change

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I keep a pull request focused on one change?▼

Write a scope contract before coding: state one concrete problem, one intended change, explicit non-goals, behavior that must remain unchanged, and the evidence proving completion. Then review the final diff line by line and remove anything not justified by that purpose.

When should I split a pull request into multiple PRs?▼

Split when two changes can be implemented, reviewed, tested, reverted, or released independently. If one part could merge safely without the other—such as a bug fix bundled with a refactor—they are separate semantic changes.

Can a large pull request still be a single semantic change?▼

Yes. A public rename touching implementation, exports, docs, tests, and vignettes is one semantic change if every edit exists only because of the rename. The measure is the number of independent intentions, not the number of changed lines.

What should I do when I discover an unrelated bug mid-PR?▼

Determine whether the second bug blocks your current change. If not, do not fix it in the same PR—record it separately and address it in a follow-up. The criterion is necessity, not proximity.

How should I handle reviewer requests for extra cleanup?▼

Classify each request: include changes required for correctness, the stated contract, or maintainability of the introduced change. Treat independent improvements as follow-up PRs so the review does not turn the PR into a container for unrelated maintenance.