sisodiabhumca When to invoke
- You have an API change (OpenAPI fragments, endpoint lists, or schema diffs) and need a human-readable changelog.
- You want release notes with clear breaking vs non-breaking classification.
Inputs needed
- A JSON diff describing changes (added/removed/modified endpoints and fields).
- Optional release metadata: version, date, owner.
Workflow
- Validate diff structure and normalize identifiers.
- Classify each change as breaking / behavioral / non-breaking.
- Group by endpoint or component.
- Generate migration notes (what to update in clients).
- Output a Markdown changelog with concise bullets.
Output format
Markdown with:
- Release header
- Breaking changes
- Behavioral changes
- Non-breaking changes
- Deprecations
- Migration notes
Guardrails
- If the diff does not include enough information to classify a change, mark it as "needs review".
- Do not invent endpoints or fields.
Reference code
summarize_api_diff.pyreads a JSON diff and writes Markdown changelog.