magus-commit-composition

magus agent install --tar | tar -xO -f - magus-commit-composition/SKILL.md

# Commit composition

Reviewer reads commits, not diffs.
Decide what belongs in each commit: every commit one idea, accepted or rejected alone.
Use workspace's own boundaries, not directory names.
magus does not rewrite history: shows seams, proves afterwards nothing lost; your VCS edits.

## Two constraints

Only unpushed work eligible; published commits fixed.
Establish unpushed set before planning.

Generated output belongs with source that moved it; split -> source commit fails drift gate.

```sh
magus describe file <changed-path>...
```

Every `output` path joins `source` change that invalidated it.
Commit of all regeneration missed pairing -> fold into causing change.

## Ask workspace for seams

```sh
magus ls                             # the projects: the coarsest real boundary
magus describe project <path>        # its declared sources, outputs, depends_on
magus affected --impact              # what a candidate group actually reaches
magus refs <symbol> --occurrences    # every site of a rename, uncapped
```

Three signals, strongest first:
- Project ownership: projects with no dependency edge between them -> separate commits; edges from `magus describe project`.
- Blast radius: groups reaching disjoint project sets -> separable; same set -> usually one commit.
- Symbol coupling: rename's sites together, however many directories.

## Limits

Two changes inside one file cannot be separated by path.
File with rename and behavior fix -> hunk-level work, or ship together; recognize while planning.

Prefer cheapest operation making branch reviewable. Rising risk:
1. Reword message.
2. Fold regeneration into neighbor.
3. Drop commit whose content final tree does not keep.
4. Reorder independent commits.
5. Split one commit into several.

## Before start, after finish

Record state identity before rewriting:

```sh
magus vcs checkpoint          # revision, branch, dirty flag, patch digest; writes nothing
```

Restructure with your VCS.
When it stops on conflicted generated file -> settle with magus, not by hand:

```sh
magus vcs resolve             # settles the conflicted declared outputs, regenerates once
```

Prove content survived: restructure changes history and nothing else; lost commit still leaves building tree.

```sh
magus graph diff --rev <checkpoint-revision>
```

Everything reported must be intended change.
Missing nodes you did not remove -> work dropped -> return to recorded revision, restart; never reconcile by hand.

Finish: list what the commit wants, stage it, re-run gate:

```sh
magus vcs ls-files -o name | git add --pathspec-from-file=-
magus affected ci
```

## Not commit content at all

Session notes, scratch plans: not repository content unless repository already tracks them.
Untracked session state: harness memory, not branch.

## See also

- magus-vcs-hygiene: classifying paths, staging one commit safely.

magus agent install --tar | tar -xO -f - magus-commit-composition-full/SKILL.md

# Composing unpushed commits into reviewable chunks

A reviewer reads commits, not diffs. Work committed in the order it occurred to
you arrives as a log nobody can review: a rename spread over four commits, a fix
buried in a regeneration, notes-to-self between two real changes. This skill decides
what belongs in each commit, so every commit is one idea a reviewer can accept or
reject alone. The workspace models its own boundaries: use them, not directory
names.

magus does not rewrite history for you, the same way it reports what a
change affects without editing it. It shows the seams and proves afterwards that
nothing was lost; your VCS performs the edit.

## Contents

- Two constraints that decide most groupings
- Ask the workspace where the seams are
- Where this stops
- Before you start, and after you finish
- What does not belong in a commit at all
- See also

## Two constraints that decide most groupings

**Only unpushed work is eligible.** Published commits are fixed. Establish what is
unpushed before planning; a branch with no upstream has
published nothing.

**Generated output belongs with the source that moved it.** Split them and the
source commit fails its own drift gate.

```sh
magus describe file <changed-path>...
```

Every `output` path joins the `source` change that invalidated it. A commit that is
all regeneration missed that pairing: fold it into the change that caused it.

## Ask the workspace where the seams are

```sh
magus ls                             # the projects: the coarsest real boundary
magus describe project <path>        # its declared sources, outputs, depends_on
magus affected --impact              # what a candidate group actually reaches
magus refs <symbol> --occurrences    # every site of a rename, uncapped
```

Three signals, strongest first:

- **Project ownership.** Changes in projects with no dependency edge between them
  are separate commits. Read the edges from `magus describe project`,
  which frequently disagrees with what the directory layout suggests.
- **Blast radius.** Groups that reach disjoint project sets are separable; groups
  that reach the same set usually want one commit.
- **Symbol coupling.** A rename's sites belong together, however many directories
  they span. If refs reports a project not-indexed, run
  `magus graph build` first: `unknown, not absent` is not an empty result.

## Where this stops

**Two changes inside one file cannot be separated by path.** A file carrying a
rename and a behavior fix needs hunk-level work, or they ship together. Recognize it
while planning; discovering it
mid-restructure turns a cleanup into a recovery.

Prefer the cheapest operation that makes the branch reviewable. In rising order of
risk:

1. Reword a message.
2. Fold a regeneration into its neighbor.
3. Drop a commit whose content the final tree does not keep.
4. Reorder independent commits.
5. Split one commit into several.

Most branches need only the first three.

## Before you start, and after you finish

Record the identity of the state you are about to rewrite:

```sh
magus vcs checkpoint          # revision, branch, dirty flag, patch digest; writes nothing
```

Restructure with your VCS. When it stops on a conflicted generated file, settle it
with magus, not by hand:

```sh
magus vcs resolve             # settles the conflicted declared outputs, regenerates once
```

**Prove the content survived.** A restructure changes history and nothing else, and
a lost commit still leaves a tree that builds, which is why
a green suite is not evidence here:

```sh
magus graph diff --rev <checkpoint-revision>
```

Everything it reports must be a change you intended. Missing nodes you did not
remove mean the restructure dropped work: return to the recorded revision and start
again, never reconcile by hand.

Finish by listing what the commit wants, staging that list, and re-running the gate:

```sh
magus vcs ls-files -o name | git add --pathspec-from-file=-
magus affected ci
```

## What does not belong in a commit at all

Session notes and scratch plans are not repository content unless the repository
already tracks them; check the path's history on the base branch
before assuming either way. Untracked session state belongs in your harness's
memory, not the branch, and dropping those commits is
often the single largest reduction available.

## See also

- magus-vcs-hygiene covers classifying paths and staging one commit safely.