---
description: Repair an unreleased `.changeset/*.md` file so it matches the real branch delta against `main`. Use when a changeset was edited iteratively during debugging, when bullets may reflect turn-by-turn history instead of `main...HEAD`, when "removed/gone/renamed" claims need proof, or when you need to audit whether a changeset is actually lossless before commit.
name: changeset-resolve
metadata:
  skiller:
    source: .agents/rules/changeset-resolve.mdc
---

# Changeset Resolve

Use the companion `changeset` skill for structure and versioning. This skill
owns the diff audit and the bullshit detector pass.

## Goal

Rewrite the active unreleased changeset so it describes the package-level,
user-facing branch delta against `main`, not the local iteration history.

## Hard Rules

- Diff against `main...HEAD`. Never diff against the current changeset draft.
- Reuse the existing unreleased changeset file. Do not create another one.
- Keep the release surface package-first:
  - `packages/kitcn`
  - `packages/resend`
  - root and `example` manifests/scripts when user-facing
  - docs only when they reveal public API shape
- Ignore repo noise unless it changes real user behavior:
  - `.claude`
  - `.agents`
  - tests
  - internal tooling churn
- If a bullet says something is gone, removed, renamed, or replaced, prove the
  old surface existed on `main` first.
- If it did not exist on `main`, it is not a breaking change. Rewrite it as a
  feature or delete it.
- Do not call a changeset lossless unless you actually audited the package
  surface. If unsure, say so.

## Mandatory Sequence

1. Resolve the active changeset:
   - list `.changeset/*.md` excluding `.changeset/README.md`
   - reuse the existing unreleased file

2. Audit the real branch delta against `main`:

```bash
git diff --stat main...HEAD -- packages/kitcn packages/resend package.json example/package.json www/content/docs
git diff --name-only main...HEAD -- packages/kitcn packages/resend package.json example/package.json www/content/docs
git diff main...HEAD -- packages/kitcn/package.json packages/resend/package.json package.json example/package.json
```

3. Audit the likely-missed public seams:
   - package `exports`
   - package `bin`
   - package `files`
   - peer dependency/support matrix
   - new packages
   - public CLI commands and flags

4. Prove every breaking bullet:

```bash
git show main:packages/kitcn/package.json
git show main:packages/kitcn/src/cli/config.ts
git grep -n "claim-you-are-making" main -- packages/kitcn packages/resend www/content/docs example
```

5. Classify honestly:
   - existed on `main` and changed incompatibly: `## Breaking changes`
   - new user-facing capability: `## Features`
   - same surface, better behavior or safer output: `## Patches`
   - test-only, docs-only, or internal churn: omit

6. Rewrite from scratch:
   - keep `## Breaking changes`, `## Features`, `## Patches`
   - user-facing only
   - no file paths
   - no implementation gossip

7. Run one final anti-lie pass:
   - re-check every breaking snippet against `main` and `HEAD`
   - scan manifests/exports one more time
   - if something still smells off, say it is not fully lossless yet

## Sanity Heuristics

- New command on this branch only: feature, not deprecation.
- New package on this branch only: feature.
- Tightened peer dependency support matrix: usually breaking.
- Moved import paths with old path removed: breaking.
- Renamed flag with old flag removed: breaking.
- Scenario/fixture proof improvements: patch only if users feel it.
- Docs sync alone: omit unless it reveals a real new surface.

## Exit Gate

Before done, run:

```bash
bun lint:fix
```