Skip to content

docs: add API contract verification to extension model skill#861

Merged
stack72 merged 1 commit intomainfrom
docs/api-contract-verification-855
Mar 25, 2026
Merged

docs: add API contract verification to extension model skill#861
stack72 merged 1 commit intomainfrom
docs/api-contract-verification-855

Conversation

@stack72
Copy link
Contributor

@stack72 stack72 commented Mar 25, 2026

Summary

Closes #855

Adds API contract verification guidance to the swamp-extension-model skill's smoke testing protocol. This addresses a real bug where a GCP IAM extension model shipped with JSON.stringify({}) as the POST body to serviceAccounts.getIamPolicy — an endpoint that requires an empty body per GCP docs. Mocked unit tests passed because they validated internal logic, not the actual API contract.

Changes

  • Phase 0.5: API Contract Verification (smoke_testing.md) — New phase between Pre-flight and Phase 1 with a 5-item checklist: endpoint URL patterns, HTTP methods, request body schemas, response schemas, and field naming conventions
  • API contract mismatches failure pattern (smoke_testing.md) — New entry in Common Failure Patterns covering wrong HTTP methods, incorrect request bodies, and field naming mismatches, with symptoms/causes/fix guidance
  • Contextual reminder (SKILL.md) — Prompt in the Smoke Testing section reminding model authors to verify against provider REST API docs before pushing

Why this is correct

The swamp-extension-model skill is what Claude follows when building extension models. By adding an API contract verification step to the skill, Claude will execute that step during model development — cross-referencing each endpoint URL, HTTP method, and request/response body against the provider's official docs. This catches the exact class of bug described in the issue (contract mismatches that mocked tests cannot detect) at the right point in the workflow (before push, after implementation).

Impact

  • Documentation-only change — no code, no runtime behavior changes
  • Applies to all future extension model development that wraps REST APIs
  • Zero risk of regression

Test plan

  • Verify markdown renders correctly in both files
  • Verify the new Phase 0.5 flows logically between Pre-flight and Phase 1
  • Verify the failure pattern follows the existing format (Symptom/Cause/Fix)

🤖 Generated with Claude Code

Add an API contract verification phase and failure pattern to the
swamp-extension-model skill's smoke testing protocol. This addresses a
real bug where a GCP IAM extension model shipped with an incorrect POST
body that mocked unit tests couldn't catch — the endpoint required an
empty body but the model sent JSON.stringify({}).

Changes:
- Add Phase 0.5 (API Contract Verification) to smoke_testing.md with a
  5-item checklist: endpoint URLs, HTTP methods, request bodies, response
  schemas, and field naming conventions
- Add "API contract mismatches" to Common Failure Patterns in
  smoke_testing.md with symptoms, causes, and fix guidance
- Add contextual reminder in SKILL.md's Smoke Testing section prompting
  model authors to verify against provider REST API docs before pushing

Co-authored-by: Blake Irvin <bixu@users.noreply.github.com>
Copy link

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

No blocking issues. Documentation-only change — no code, no runtime behavior, no domain model impact.

Suggestions

  1. Phase 0.5 naming: The "0.5" numbering works but could become awkward if another phase needs to be inserted later. Consider renaming phases to use whole numbers (0 → Pre-flight, 1 → API Contract Verification, 2 → List methods, etc.) in a future pass. Not worth doing in this PR since it would be a larger diff for no functional gain.

Otherwise the changes are well-placed and follow the existing Symptom/Cause/Fix format for failure patterns. The new phase sits logically between pre-flight setup and live API calls, and the SKILL.md reminder is a clean contextual nudge without being redundant with the reference doc.

@stack72 stack72 merged commit a0f1611 into main Mar 25, 2026
10 checks passed
@stack72 stack72 deleted the docs/api-contract-verification-855 branch March 25, 2026 14:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Extension model skill should prompt API doc verification before push

1 participant