Commits and Slices

A commit is more useful than a timestamped bundle of files. In ODD it is a
work unit: a deliverable behavior, fix, migration, or documentation unit
that a reviewer can understand, verify, and roll back without disentangling
unrelated changes. Work-unit commits provide the foundation for reviewable PR
slices when a feature grows.

This lesson is about structure, not automatic delivery. A commit or a chosen PR
shape does not authorize pushing, opening a pull request, merging, or changing
review mode. Those remain separate human and repository-policy decisions.

Commit by outcome, not file type

A weak split mirrors the directory tree: “add models,” then “add services,” then
“add tests.” None of those commits necessarily works on its own, so a reviewer
must reconstruct the feature across several changes.

A work-unit split tells a story instead. For example:

feat(auth): add token validation domain model and tests
feat(auth): wire token validation into login flow

Each commit has one clear purpose and leaves the repository in a sensible state
when applied alone. Tests stay with the behavior they verify. Documentation
stays with the user-visible feature or workflow it explains. A good message
explains the outcome, not merely the file list, and rollback removes one coherent
unit rather than collateral work.

Before committing, ask:

• Does this commit have one clear purpose?
• Does the repository make sense after this commit alone?
• Are relevant tests and docs included?
• Can it be rolled back without reverting unrelated work?
• Does the message say what changed for the project or user?

ODD asks for Conventional Commit messages for its work units. This gives a
consistent, outcome-oriented history while keeping the actual acceptance proof
in the feature document.

Tasks, commits, and candidates are different

A feature-document task is a unit of tracked progress. A commit may hold one or
more whole tasks with their tests and docs. A PR slice is the reviewable group of
commits that delivery exposes. These are related but not interchangeable.

The feature document records the commit holding each task as evidence. A
high-risk unit gets its own commit so it can be reviewed alone. The native review
candidate is that work-unit commit, or the PR slice when review is deferred; it
is never a TODO checkbox or the whole accumulated feature branch. Keeping these
boundaries clear lets verification and rollback target the actual change.

The review budget is advisory

ODD uses about 400 authored changed lines—additions plus deletions—as an
advisory review budget. It helps forecast reviewer workload and decide whether
to slice delivery. It is not a cap, a task classifier, a forced split, or a
reason to omit quality work. The same number may be configured differently for
a session.

Never fit the budget by deleting comments, blank lines, documentation, or tests,
or by compressing code. First make one honest slicing pass by coherent work unit.
If no cohesive split puts every slice under budget, report the smallest honest
count and why it cannot shrink further; do not iterate endlessly toward a
cosmetic number.

A focused PR of 400 lines or fewer is reasonable. An oversized PR increases
reviewer cognitive load, slows feedback, and couples rollback of otherwise
separable work. The chained-PR guidance aims to keep each PR reviewable in about
60 minutes.

Delivery strategies

At feature-document creation, forecast authored changed lines from the tasks and
choose a delivery strategy. Keep a running count from work-unit commits. If the
forecast or running count exceeds the advisory budget, apply the selected
strategy before the next commit.

The default is ask-on-risk: ask once using the oversized-delivery menu. With
auto-chain, ask only if the chain choice is not already cached, then slice
automatically. single-pr keeps one PR subject to the destination repository’s
policy. exception-ok records an explicitly accepted policy exception where the
destination has such a route. A single-PR selection is not, by itself, an
accepted exception.

When a chain choice is needed, the choices appear in this order:

1. Feature/tracker branch chain (feature-branch-chain): child slices are
   reviewed before final feature integration.
2. Verified default/main branch chain (stacked-to-main): independently
   reviewable slices land in order on the repository’s verified default branch,
   whatever that branch is named.
3. One single PR — least recommended (single-pr): keep the oversized
   change together.

“Least recommended” applies only to an oversized single-PR menu. It does not
mean all single PRs are bad. The third choice clears any pending chain choice;
it is not itself a chain strategy. In noninteractive contexts where no question
can be answered, the ODD guidance uses the feature/tracker branch chain and
records that choice in the Log.

What a chain requires

Before creating branches or PRs, verify the destination repository’s default
branch rather than assuming it is named main. Do not mix strategies once one
is chosen. In a chain, each child PR holds one deliverable work unit with its
tests and docs, describes its start and end state, dependencies, follow-up work,
and out-of-scope items, and includes a dependency diagram marking the current
PR.

A feature-branch chain uses a draft, no-merge tracker PR. The first child targets
the tracker branch; each later child targets the immediate parent branch.
A stacked-to-main chain instead uses the verified default branch as the
integration destination. If a child’s diff includes work from the wrong base,
treat that as a polluted-diff problem and correct the base so the reviewer sees
only the current unit.

For one single PR, do not create chain-only artifacts such as a tracker or child
dependency diagram. Follow the destination’s normal PR template and contribution
policy. size:exception is not a universal label: use it only if the destination
policy defines it and its authorization conditions are met.

Useful local inspection

Before a commit, inspect both the story and size:

git diff --stat
git diff --cached --stat
git log --oneline -5

The diff statistics reveal the work under review; recent log messages show the
repository’s commit style. They do not decide task size or replace reading the
actual diff.

Common mistakes

• Separating tests into a later commit. It makes the behavior temporarily
  unverified.
• Splitting by folders. Split by independently understandable outcomes.
• Treating 400 lines as a hard limit. Preserve coherent code and evidence.
• Assuming main. Verify the default branch.
• Treating a chosen strategy as delivery permission. Push, PR creation, and
  merge remain separate authorizations.

Try it

Run git diff --stat and look at the current change. Describe its smallest
coherent outcome in one sentence, then list the tests and documentation that
belong with it. If the work would exceed the review budget, decide whether its
units can land independently or need feature-level integration. That tells you
which chain option you would present—without creating a PR or assuming that
approval to choose a shape is approval to deliver it.