Claude Skill

gentle-ai-work-unit-commits

Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download Gentleman-Programming-gentle-shell-skills_work-unit-commits-a5cc0e2.zip · 2 KB

Install

skills CLI npx skills add https://github.com/Gentleman-Programming/gentle-shell/tree/main/skills/work-unit-commits
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gentleman-programming-gentle-shell@llmmart
Git git clone https://github.com/Gentleman-Programming/gentle-shell.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole gentleman-programming/gentle-shell collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

When to Use

Load this skill when deciding what belongs in each commit or PR.

Use it for:

  • Splitting a feature into reviewable work.
  • Preparing commits before opening a PR.
  • Turning a large change into chained or stacked PRs.
  • Keeping reviewer cognitive load healthy.
  • Committing ODD work in reviewable slices of about 400 authored changed lines.

Critical Rules

Rule Requirement
Commit by work unit A commit represents a deliverable behavior, fix, migration, or docs unit.
Do not commit by file type Avoid models, then services, then tests if none works alone.
Keep tests with code Tests belong in the same commit as the behavior they verify.
Keep docs with the user-visible change Docs belong with the feature or workflow they explain.
Tell a story A reviewer should understand why each commit exists from its diff and message.
Future PR-ready Each commit should be a candidate chained PR when the change grows.
Delivery workload guard If the task forecast produces a >400-line change, honor the selected delivery_strategy. On chaining paths only, group commits into chained PR slices before implementation. For explicit single-pr or exception-ok, keep one PR, report the review load, and follow the destination repository's documented contribution/size policy; selection alone does not accept an exception.
Budget is not code-golf Never shrink a diff by deleting comments, blank lines, docs, or tests, or by compressing code, to fit the review budget (about 400 authored changed lines). Slice by work unit or report the overage.

Work Unit Checklist

Before committing, confirm:

  • The commit has one clear purpose.
  • The repo still makes sense after applying only this commit.
  • Tests or docs for this unit are included when relevant.
  • Rollback is reasonable without reverting unrelated work.
  • The commit message explains the outcome, not the file list.

Split Examples

Weak split Better work-unit split
add models feat(auth): add token validation domain model and tests
add services feat(auth): wire token validation into login flow
add tests Tests included with each behavior commit
update docs Docs included with the user-facing change they explain

PR Relationship

Use work-unit commits as the foundation for chained PRs:

  1. Build the smallest independent work unit.
  2. Include verification for that unit.
  3. Commit it with a Conventional Commit message.
  4. If the PR approaches 400 changed lines, promote commits or groups of commits into chained PRs.

Delivery And Budget

The chosen delivery_strategy governs how commits group into PRs, and the budget constrains how work is sliced, never the code itself.

  • Up to about 400 forecast or running authored changed lines: keep work-unit commits inside one PR.
  • Above it: follow the selected delivery_strategy — ask on ask-on-risk, auto-slice with the cached chain choice on auto-chain, follow the destination repository's documented contribution/size policy on over-budget single-pr, or record an explicitly accepted policy exception on exception-ok. A single-PR selection does not itself accept an exception.
  • Risk never picks the delivery strategy; a unit whose Risk line names a high-risk item gets its own commit.
  • size:exception is a Gentle-owned repository policy, not a universal label requirement. Never request, create, or add the label for generic users unless the destination policy uses it; preserve its maintainer acceptance and protected-label authorization gates.
  • Splitting is bounded: after one honest slicing pass, if no cohesive work-unit split fits the budget, stop and report the smallest honest count and rationale. Recommend an exception only where destination policy provides it. Do not iterate shrinking the code to reach the number.

Each work unit should map cleanly to a commit or PR with:

  • clear start state,
  • clear finished state,
  • verification in the same unit,
  • rollback that does not remove unrelated work.

ODD Relationship

ODD commits work units in reviewable slices of about 400 authored changed lines, not one commit per task:

  • A slice holds one or more whole tasks with their tests and docs; the last slice closes the feature.
  • A unit whose Risk line names a high-risk item gets its own commit, so native review takes it alone.
  • The native review candidate is that commit, or the PR slice it belongs to when review is deferred, evaluated against the previous reviewed boundary.
  • The running authored line count from work-unit commits feeds the delivery-strategy vocabulary.
  • The feature document records the commit that holds each task and, once a delivery strategy applies, the slice boundaries.

Commands

# Review the story before committing
git diff --stat
git diff --cached --stat

# Check recent commit style
git log --oneline -5
Files (gentle-shell)
  • SKILL.md 5.1 KB
    ---
    name: gentle-ai-work-unit-commits
    description: "Plan commits as reviewable work units. Trigger: commit splitting, chained PRs, or keeping tests and docs with code."
    license: Apache-2.0
    metadata:
      author: gentleman-programming
      version: "1.0"
    ---
    
    ## When to Use
    
    Load this skill when deciding what belongs in each commit or PR.
    
    Use it for:
    
    - Splitting a feature into reviewable work.
    - Preparing commits before opening a PR.
    - Turning a large change into chained or stacked PRs.
    - Keeping reviewer cognitive load healthy.
    - Committing ODD work in reviewable slices of about 400 authored changed lines.
    
    ## Critical Rules
    
    | Rule | Requirement |
    |------|-------------|
    | Commit by work unit | A commit represents a deliverable behavior, fix, migration, or docs unit. |
    | Do not commit by file type | Avoid `models`, then `services`, then `tests` if none works alone. |
    | Keep tests with code | Tests belong in the same commit as the behavior they verify. |
    | Keep docs with the user-visible change | Docs belong with the feature or workflow they explain. |
    | Tell a story | A reviewer should understand why each commit exists from its diff and message. |
    | Future PR-ready | Each commit should be a candidate chained PR when the change grows. |
    | Delivery workload guard | If the task forecast produces a >400-line change, honor the selected `delivery_strategy`. On chaining paths only, group commits into chained PR slices before implementation. For explicit `single-pr` or `exception-ok`, keep one PR, report the review load, and follow the destination repository's documented contribution/size policy; selection alone does not accept an exception. |
    | Budget is not code-golf | Never shrink a diff by deleting comments, blank lines, docs, or tests, or by compressing code, to fit the review budget (about 400 authored changed lines). Slice by work unit or report the overage. |
    
    ## Work Unit Checklist
    
    Before committing, confirm:
    
    - [ ] The commit has one clear purpose.
    - [ ] The repo still makes sense after applying only this commit.
    - [ ] Tests or docs for this unit are included when relevant.
    - [ ] Rollback is reasonable without reverting unrelated work.
    - [ ] The commit message explains the outcome, not the file list.
    
    ## Split Examples
    
    | Weak split | Better work-unit split |
    |------------|------------------------|
    | `add models` | `feat(auth): add token validation domain model and tests` |
    | `add services` | `feat(auth): wire token validation into login flow` |
    | `add tests` | Tests included with each behavior commit |
    | `update docs` | Docs included with the user-facing change they explain |
    
    ## PR Relationship
    
    Use work-unit commits as the foundation for chained PRs:
    
    1. Build the smallest independent work unit.
    2. Include verification for that unit.
    3. Commit it with a Conventional Commit message.
    4. If the PR approaches 400 changed lines, promote commits or groups of commits into chained PRs.
    
    ## Delivery And Budget
    
    The chosen `delivery_strategy` governs how commits group into PRs, and the budget constrains how work is sliced, never the code itself.
    
    - Up to about 400 forecast or running authored changed lines: keep work-unit commits inside one PR.
    - Above it: follow the selected `delivery_strategy` — ask on `ask-on-risk`, auto-slice with the cached chain choice on `auto-chain`, follow the destination repository's documented contribution/size policy on over-budget `single-pr`, or record an explicitly accepted policy exception on `exception-ok`. A single-PR selection does not itself accept an exception.
    - Risk never picks the delivery strategy; a unit whose Risk line names a high-risk item gets its own commit.
    - `size:exception` is a Gentle-owned repository policy, not a universal label requirement. Never request, create, or add the label for generic users unless the destination policy uses it; preserve its maintainer acceptance and protected-label authorization gates.
    - Splitting is bounded: after one honest slicing pass, if no cohesive work-unit split fits the budget, stop and report the smallest honest count and rationale. Recommend an exception only where destination policy provides it. Do not iterate shrinking the code to reach the number.
    
    Each work unit should map cleanly to a commit or PR with:
    
    - clear start state,
    - clear finished state,
    - verification in the same unit,
    - rollback that does not remove unrelated work.
    
    ## ODD Relationship
    
    ODD commits work units in reviewable slices of about 400 authored changed lines, not one commit per task:
    
    - A slice holds one or more whole tasks with their tests and docs; the last slice closes the feature.
    - A unit whose Risk line names a high-risk item gets its own commit, so native review takes it alone.
    - The native review candidate is that commit, or the PR slice it belongs to when review is deferred, evaluated against the previous reviewed boundary.
    - The running authored line count from work-unit commits feeds the delivery-strategy vocabulary.
    - The feature document records the commit that holds each task and, once a delivery strategy applies, the slice boundaries.
    
    ## Commands
    
    ```bash
    # Review the story before committing
    git diff --stat
    git diff --cached --stat
    
    # Check recent commit style
    git log --oneline -5
    ```
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.