# Commit

> Finish a branch cleanly. Use to verify readiness, make logical commits, push, and create or refresh a PR with evidence.

- Skill: `mopeyjellyfish/commit` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add mopeyjellyfish/commit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mopeyjellyfish/commit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mopeyjellyfish (https://skillmd.com/u/mopeyjellyfish)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mopeyjellyfish/commit

---


# Commit The Work

`$fw:commit` closes Flywheel's compact project loop between "the repo
change is ready enough to finish" and "the branch is pushed with an open or
refreshed PR."

It is the finishing workflow for:

- staged or unstaged work that needs commit planning, commit creation, push,
  and PR creation or refresh
- committed work that needs pushing and PR creation or refresh
- a feature branch that needs a PR
- an existing PR whose description should be refreshed
- a branch that surfaced durable lessons worth capturing before commit

Use it after `$fw:work` or after `$fw:review` reaches a clean
enough verdict. For runtime-risky changes, use it after `$fw:rollout`
sets the activation, validation, and rollback posture. If the user invokes
`$fw:commit` directly, treat that as permission to run the finish-stage
workflow rather than as a reason to reject the request because earlier stages
were skipped.

## Interaction Method

Follow `../references/host-interaction-contract.md`.

Call the exact host question tool named in
`../references/host-interaction-contract.md` when that tool is available. Do
not ask for raw `1/2/3` replies when the host already offers a choice surface.

When the workflow spans multiple material steps, use the host task-tracking
tool named in `../references/host-interaction-contract.md` to create and
maintain a short task list.

Ask one question at a time. When multiple finish paths are viable, present a
short predicted choice list with the recommended label first and rely on the
host's native freeform final path when it exists.

## Input

<commit_input> #$ARGUMENTS </commit_input>

Parse optional tokens before interpreting any remainder:

- `local-only` - explicitly opt out of the default publish path; create local
  commit(s) but do not push or create or refresh a PR
- `plan:<path>` - use this plan as finish-stage context and update it to
  `status: completed` when appropriate
- `pr:<url>` - target this existing PR explicitly
- `refresh-description` - update the current PR description without changing
  branch or commit state

## Reference Loading Map

Do not preload every support file. Load only what the current phase needs:

- read `references/pr-body-template.md` only when composing or refreshing the
  PR body
- read `references/evidence-bundle.md` when a shared evidence bundle exists or
  when a proof-producing stage already created reusable evidence for this
  branch
- read `../rollout/references/rollout-template.md` only when a rollout
  artifact already exists and its staged-release summary should be reflected in
  the PR story
- read `../observability/references/service-readiness-matrix.md` only when the
  change is runtime-risky and the monitoring or validation section needs a
  grounded readiness frame
- read `../references/workflow-gates.md` before final readiness checks and when
  closing the finish stage
- read `.flywheel/config.local.yaml` when present for repo-local commit gates
  such as browser proof, review-before-commit, and runtime validation

## Core Principles

1. **Finish from repo truth** - branch status, open PR state, test evidence,
   and review outcomes outrank memory or optimism.
2. **Commit honestly** - use `$fw:commit-message` for each logical unit
   being committed. If the helper is unavailable, draft the conventional header
   directly and ask before marking breaking changes.
3. **Prefer one coherent finish flow** - local commits, push, PR state, and
   operational validation belong to one remembered command.
4. **Publish by default** - unless the user passes `local-only`, continue from
   commit through push and PR creation or refresh instead of stopping at a
   clean local branch.
5. **Preview multiple commits before execution** - when the diff should split,
   show a short commit plan first so the grouping is reviewable.
6. **Operational validation is mandatory** - every PR gets a
   `Post-Deploy Monitoring & Validation` section, even if the answer is a
   no-impact rationale.
7. **Preserve branch safety** - do not commit directly to the default branch
   without explicit user approval.
8. **Carry only the material architecture and code-quality story** - PR text
   should explain the relevant boundary, pattern, simplification, or
   maintainability decisions without replaying raw specialist analysis.
9. **Capture durable lessons before commit** - when the branch surfaced durable
   project value, offer `spin` before staging and committing so the solution doc
   can land in the same logical change.
10. **Stop only for real blockers** - do not prompt or pause for preferences
    that can be inferred from repo truth. Stop for unsafe default-branch state,
    failed required checks, missing required policy gates, unavailable publish
    tooling, unresolved blocking review findings, missing required proof, or an
    explicit `local-only` request.

## Workflow

### Phase 1: Gather Finish Context

Collect the smallest useful context in one pass:

```bash
printf '=== STATUS ===\n'; git status --short --branch
printf '\n=== BRANCH ===\n'; git branch --show-current
printf '\n=== DIFF ===\n'; git diff HEAD
printf '\n=== LOG ===\n'; git log --oneline -10
printf '\n=== DEFAULT_BRANCH ===\n'; git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null || echo 'DEFAULT_BRANCH_UNRESOLVED'
printf '\n=== PR_CHECK ===\n'; gh pr view --json url,title,state,baseRefName,headRefName 2>/dev/null || echo 'NO_OPEN_PR'
```

If GitHub CLI is unavailable or unauthenticated, continue only as far as local
git truth allows and report PR creation or refresh as a publish blocker. Do not
silently downgrade the default finish path to local-only unless the user passed
`local-only`.

If `.flywheel/config.local.yaml` exists, read only the finish-stage-relevant
keys before classifying the path:

- `review.require_review_before_commit`
- `browser.require_proof_for_browser_visible_changes`
- `commit.require_browser_proof_for_browser_visible_changes`
- `runtime.require_operational_validation_for_runtime_changes`

If `.context/flywheel/evidence/` exists, inspect only the newest `summary.md`
that clearly matches the current branch, plan, or task. Treat the shared
bundle as the primary reusable proof source for finishing.

If `.context/flywheel/rollout/` exists, inspect only the newest `rollout.md`
that clearly matches the current branch, plan, or task. Treat it as the source
of truth for activation sequence, validation window, and rollback trigger.

### Phase 2: Classify The Finish Path

Choose the path from branch truth. The default non-local path is publish
complete: commit what is needed, push the branch, then create or refresh the PR.

- **Description refresh** - user asked for `refresh-description` or only wants
  to update the existing PR text
- **Full finish** - branch has uncommitted work, unpushed commits, no open PR,
  or an existing PR whose body should reflect new commits, evidence, or summary
- **Local-only finish** - user explicitly asked for `local-only`
- **Publish finish** - branch is committed but still needs push plus PR
  creation or refresh
- **PR refresh** - branch is already pushed and an open PR exists; refresh it by
  default when the current finish payload differs from the PR body

If the current branch is the default branch and finishing would create commits,
create a feature branch first unless the user explicitly approves committing on
the default branch.

If a clean isolated checkout is preferable before finishing, use
`$fw:worktree` instead of switching the shared checkout ad hoc.

### Phase 3: Run Missing Readiness Checks

Read `../references/workflow-gates.md` and apply the `Commit-Ready` gate while
running the checks below. If the gate is not satisfied, stop with the missing
items instead of committing, pushing, or creating a PR.

Before creating commits or a PR, confirm:

- tests and linting were addressed, using the repo-grounded commands already
  discovered during `$fw:work` or local setup
- browser-visible changes have fresh acceptance proof from
  `$fw:browser-test`, repo-native browser tests, or an explicit user
  decision to continue without that proof
- if the change is runtime-risky and activation sequence, validation window, or
  rollback trigger are still unresolved, stop and route through
  `$fw:rollout` before continuing
- the change's runtime impact has either:
  - concrete monitoring and validation notes, or
  - a clear no-impact rationale
- if local policy requires explicit operational validation for runtime changes,
  that validation is present before continuing

Review handling:

- if `$fw:review` already ran and the latest verdict is clean enough,
  reuse it
- if review has not run and finish-stage confidence depends on it, run
  `$fw:review` now instead of blocking only because the user skipped it
- if unresolved `P0` or `P1` gated or manual findings remain after review, stop
  instead of continuing into commit or PR creation
- if local policy requires review before commit, stop only when the review pass
  still leaves blocking findings unresolved

If the branch is not actually ready, stop and say what remains.

### Phase 4: Run The Pre-Commit Spin Checkpoint

Before building the final commit payload or staging files, infer at most **3**
candidate spin lessons from:

- execution evidence such as review findings, validation work, or non-obvious
  fixes
- repo changes that altered setup, CLI, API, config, docs, or workflow
  contracts
- answers and clarified preferences surfaced during `ideate`, `brainstorm`, or
  `plan` when they materially changed the repo workflow or project direction
- user corrections from this session that materially changed how Flywheel
  should behave for project work

Only keep candidates that look durable and project-specific. If nothing
non-trivial surfaced, continue without forcing a spin offer.

If one or more candidates are worth preserving, call the host question tool with
a small choice surface. Put the recommended option first:

1. **Quick spin** - capture the strongest lesson in a compact solution note
2. **Full spin** - run `$fw:spin` with the selected candidate summary
3. **Skip** - finish without capturing a solution entry

Recommend the strongest candidate explicitly when capture is warranted. Recommend
`Skip` only when the value is marginal.

If the user wants to continue, launch `$fw:spin` with the selected candidate
summary and the selected capture depth instead of calling it blank. For quick
capture, pass a lightweight-mode hint with the summary. When `$fw:spin` creates
or updates `docs/solutions/`, treat those files as part of the same finish
payload and include them in the commit plan.

### Phase 5: Build The Finish Payload

Assemble one finish summary from repo truth that will be reused in the PR
`Summary` section and in the final user report. Keep it concise: what changed,
why it matters, and any material architecture, code-quality, testing, decision,
or operational caveat.

Assemble the payload for commit, push, and PR steps from:

- current diff and recent commits
- any `docs/solutions/` changes created by the pre-commit spin checkpoint
- plan summary and key decisions when `plan:<path>` is available
- context or decision-record artifacts when they materially explain the branch
- the material architecture, pattern, simplification, or maintainability story
  when those decisions materially affect the branch summary
- testing notes
- review outcomes and residual caveats
- rollout artifact contents when present
- shared evidence bundle contents when present
- operational validation notes

When the change is runtime-risky, read
`../observability/references/service-readiness-matrix.md` so the PR's
monitoring section covers the real contract, state, rollout, and recovery
surface instead of generic "watch the logs" language.

If a shared evidence bundle exists, prefer it first. Include only items marked
`clean` or `redacted` with `PR Use: yes`. Turn `summary-only` items into short
prose instead of pasting raw artifacts. Keep `local-only` items out of the PR
body.

If the change affects observable behavior and the repo or host already exposes
evidence such as screenshots, CLI transcripts, request examples, generated
artifacts, or a shared evidence bundle, offer three choices:

- **Include existing evidence** (recommended when a clean or redacted bundle
  entry already exists)
- **Finish without evidence**
- Freeform path when the repo needs a different evidence posture

Do not block finishing on evidence capture when the repo has no practical
capture path.

Only include evidence in the PR description when you are above 90% confident it
contains no secrets and no meaningful PII. Do not paste raw auth headers,
cookies, tokens, passwords, or unredacted sensitive request or response bodies
into the PR body. When the raw artifact is too sensitive but the shape matters,
prefer a redacted or dummy-substituted example.

When a shared evidence bundle exists, cite the bundle-backed summary or the
sanitized artifact path rather than re-explaining the proof from scratch.

When a rollout artifact exists, reuse its activation sequence, validation
window, owner, and rollback trigger instead of rebuilding those decisions from
memory during PR preparation.

If the change is browser-visible and fresh proof is still missing, route
through `$fw:browser-test` before final PR preparation unless the user
explicitly wants to continue without it.

Read `references/pr-body-template.md` and fill it with concrete repo facts.

### Phase 6: Plan And Create Commit(s)

If the worktree is dirty:

1. identify one logical unit at a time
2. decide whether the diff should stay as one honest commit or split into
   multiple logical commits
3. if multiple commits are warranted, show a short commit plan before
   execution with:
   - the proposed header
   - the goal of the unit
   - the reason it is separate
4. if the diff is too entangled for a clean split, say so and prefer one
   honest commit
5. stage only the files for each chosen unit
6. use `$fw:commit-message` for each conventional header, plus body or
   footers when useful
7. commit the unit before moving to the next one

If the most honest message would be breaking, ask before using `!` or
`BREAKING CHANGE:`.

Default to one commit unless there are clearly separate concerns worth
splitting.

### Phase 7: Push

If the path is `local-only`, skip this phase and say so explicitly.

Otherwise publish the branch safely:

```bash
git push --set-upstream origin HEAD
```

If the branch already has an upstream, use `git push`.

If push fails, stop before PR creation or refresh and report the exact blocked
state. Do not claim the branch is published unless the push succeeded.

### Phase 8: Create Or Refresh The PR

If the path is `local-only`, skip this phase and report that no PR work was
requested.

If GitHub CLI is available:

- **No open PR** -> create one with the assembled title and body after the
  branch has been pushed
- **Existing open PR** -> refresh the title and body with the assembled finish
  summary, testing, monitoring, and evidence unless the user explicitly asked
  for local-only behavior
- **Description refresh** -> update the existing PR title and body without
  changing branch or commit state

Required PR body sections:

- Summary
- Testing
- Post-Deploy Monitoring & Validation
- Evidence, only when present

If there is truly no runtime impact, the monitoring section must still contain:

```text
No additional operational monitoring required.
Reason: <one line grounded in the actual change>
```

### Phase 9: Close The Loop

When `plan:<path>` is available and the plan frontmatter contains
`status: active`, update it to `status: completed`.

Then report:

1. finish summary
2. branch name, push result, and PR URL or explicit PR blocker
3. commits created or confirmed
4. any residual follow-up
5. whether the pre-commit spin checkpoint captured, skipped, or found no durable
   lesson
6. a final handoff card from `../references/workflow-gates.md` with readiness,
   evidence, and any open follow-up

Do not make a normal post-commit spin offer. If push, PR creation, CI, or
reviewer feedback after commit reveals a new durable lesson, treat that as a new
follow-up change and capture it in a later commit.

If the branch finished from a `.worktrees/` checkout and no longer needs that
checkout, suggest `$fw:worktree cleanup <branch>` as the cleanup path.

---

## Included References

### Evidence Bundle

@./references/evidence-bundle.md

### PR Body Template

@./references/pr-body-template.md

### Rollout Template

@../rollout/references/rollout-template.md