changeset-resolve

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:

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:

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:

bun lint:fix