agentleFS
Sign inStart free
AndyTechnologiesAndyTechnologies/my-own-skills/skills/work-unit-commits/SKILL.md

work-unit-commits

Skill0 starsChanged 38 days agoApache-2.0View on GitHub

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

4 other projects use a version of this, 2 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 58
  2. Distinctive:

    Commit it with a Conventional Commit message.

    line 62
  3. Distinctive:

    If the PR approaches 400 changed lines, promote commits or groups of commits into chained PRs.

    line 63
  4. Distinctive:

    Every ODD task closes with at least one work-unit commit, branch first when on the default branch, with tests and docs alongside the …

    line 69

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.
  • Closing an ODD task with a work-unit commit.

Critical Rules

RuleRequirement
Commit by work unitA commit represents a deliverable behavior, fix, migration, or docs unit.
Do not commit by file typeAvoid models, then services, then tests if none works alone.
Keep tests with codeTests belong in the same commit as the behavior they verify.
Keep docs with the user-visible changeDocs belong with the feature or workflow they explain.
Tell a storyA reviewer should understand why each commit exists from its diff and message.
Future PR-readyEach commit should be a candidate chained PR when the change grows.
Budget is not code-golfNever shrink a diff by deleting comments, blank lines, docs, or tests, or by compressing code, to fit the review budget (400 by default, or the session review_budget_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.
  • Focused test command and exact result are recorded.
  • Runtime harness command/scenario and exact result are recorded, or explicit N/A explains why no runtime boundary exists.
  • Rollback boundary names the exact files/behavior removable without unrelated work.
  • The commit message explains the outcome, not the file list.

Split Examples

Weak splitBetter work-unit split
add modelsfeat(auth): add token validation domain model and tests
add servicesfeat(auth): wire token validation into login flow
add testsTests included with each behavior commit
update docsDocs 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.

ODD Relationship

Organic Driven Development (ODD) closes every substantial task with a work-unit commit on the feature branch:

  • Every ODD task closes with at least one work-unit commit, branch first when on the default branch, with tests and docs alongside the behavior and a Conventional Commit message.
  • The native review candidate is that commit, or the PR slice it belongs to when review is deferred, against the previous reviewed boundary. It is never a TODO checkbox and never the accumulated feature branch.
  • The running authored line count from work-unit commits feeds the delivery-strategy vocabulary: ask-on-risk, auto-chain, single-pr, exception-ok.
  • The ODD feature document records the commit identity as evidence and, once a delivery strategy applies, the chosen chain strategy and slice boundaries (which commits each PR holds).

Commands

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

# Check recent commit style
git log --oneline -5

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free