| name | ship-verification |
| description | Post-merge verification pass for Grantex. After any PR merges to main or ships to prod, run this pass without being asked — verify README, Mintlify docs, landing page, SDK READMEs (TS, Python, Go), integration docs, and SEO surfaces are consistent with what just shipped. Use this skill whenever a PR merges, a release goes out, or a feature ships. |
Ship Verification
Behavioral guideline for keeping Grantex's public surfaces honest after every merge. The goal is to catch drift between what the code does and what the docs claim — before a user runs into it.
Trigger: run this pass automatically after any merge to main or any prod deploy. Do not wait to be reminded. If the diff is trivial (dependabot version bump, CI-only change, internal refactor with no public contract change), say so and skip.
Tradeoff: biases toward catching drift over speed. For a pure CI / dependabot / internal refactor PR, a one-sentence "no public surface touched, skipping" is the right output.
1. Scope the diff first
Before touching any doc, identify what actually shipped:
- What routes, SDK methods, response shapes, or CLI commands changed?
- Did any behavior change silently — e.g. a request that used to succeed now 400s, or a value now appears in a different place?
- If the answer to both is "no" (CI, deps, tests, security-internal hardening with no contract change), skip the rest and report that.
Do not fabricate updates. A security fix that tightens verification without changing the API contract usually needs no doc change.
2. Surfaces to check
Walk these in order. Stop when the diff doesn't touch a surface.
README.md (repo root) — quickstart code, feature matrix, example table, package versions.- Mintlify docs (
docs/) — concept pages, SDK reference pages (TS + Python), guides, integration pages. Check docs/sdks/typescript/ and docs/sdks/python/ mirror each other when a feature exists in both.
- SDK READMEs —
packages/sdk-ts/README.md, packages/sdk-py/README.md, packages/go-sdk/README.md. Each has its own quickstart that can drift from the root.
- Landing page —
web/index.html. Only update for new capabilities that change the value proposition. Security-internal changes do not belong here.
- Integrations index —
docs/integrations/overview.mdx if a new integration shipped.
- SDK test fixtures — mocked response shapes in
packages/sdk-*/tests/* that encode server behavior. These are technically tests, but they document the shape; keep them honest.
- SEO — only when keywords or messaging change. Never touch for internal fixes. Use the keywords from
seo-system memory, not generic SEO audit advice.
3. What counts as a real gap
A finding is real when:
- A code example would fail if copy-pasted.
- A response field or URL format in docs no longer matches what the server returns.
- A parameter's documented behavior (defaults, validation, errors) diverges from the implementation.
- A feature shipped but is not mentioned anywhere a user would discover it.
A finding is not real when:
- Docs use a synonym or different phrasing for the same thing.
- A test mock uses a stale value that is not user-visible and does not affect production (flag it, but it's not a release blocker).
- A page could be restructured for clarity but is not wrong.
4. Output shape
Keep reports tight. For each surface:
README.md — OK / needs Xdocs/ — OK / list files needing updates with one-line reason each- SDK READMEs — OK / which package and why
- Landing page — OK / out of scope for this change
- SEO — OK / out of scope
If changes are needed, batch them in a single PR named docs/<topic>-followup unless the diff naturally splits. Do not open a PR per file.
5. When to skip
Skip the pass entirely when:
- PR is a dependabot bump that did not touch source.
- PR only touches
.github/workflows/, skills/, or scripts/.
- PR is an internal refactor with no change to exported symbols, route shapes, or response bodies.
- PR is a test-only change.
Always report what you skipped and why, in one line. Silence is not the right signal.
6. Order of operations in a session
When multiple PRs merge in a session:
- Batch the doc audit at the end of the session, not after each merge.
- Group updates from related PRs into one follow-up PR.
- If a single PR is large enough that its doc impact is nontrivial (e.g. a new SDK method), audit and fix as part of the same PR if still open; otherwise follow-up immediately.
Checklist
Use this before declaring done:
- Did I scope the diff to what actually shipped, not speculate?
- For each affected surface, did I read the current doc and compare it to the code?
- Did I avoid editing surfaces the change did not touch?
- Is there a single clean PR for the follow-up, or a clear statement that none was needed?
