api-contract-writer
Purpose
Write backend API contracts covering endpoints or operations, payloads, validation, errors, idempotency, and state transitions.
Expected inputs
- current backend or persistence context
- data model or schema details
- constraints or stack context
- known risks or unresolved decisions
Deliverables
- structured recommendation
- design notes
- risks or gaps
- recommended next artifact
Trigger this skill when
- You are designing or reviewing backend behavior, persistence, or API structure rather than only UI flow.
- Data modeling, transactions, migration, or access-layer choices materially affect correctness or maintainability.
- A team needs sharper boundaries between domain logic, persistence logic, and API contracts.
Operating procedure
- Clarify the domain, data lifecycle, and current or intended persistence approach.
- Separate facts, assumptions, constraints, and unresolved backend-specific risks.
- Prefer concrete operational behavior over abstract framework enthusiasm.
- Explicitly handle invalid, missing, conflict, and rollback cases where relevant.
- Recommend the next most useful backend, persistence, or testing skill.
Quality gates
- The recommendation respects real data lifecycle and consistency needs.
- Failure and conflict cases are not ignored.
- Assumptions and unresolved decisions are visible.
- Output is specific enough to influence implementation, schema, or testing.
Output style
- Be concrete and structured.
- Separate findings, assumptions, and recommendations.
- Prefer explicit tradeoffs over single-answer absolutism.
- Use severity or priority where useful.
Failure modes to avoid
- Do not blur domain logic, persistence logic, and transport concerns.
- Do not describe happy-path behavior only.
- Do not hide uncertainty behind ORM or framework jargon.
- Do not recommend migrations or transactions without discussing rollback and compatibility.
Minimum output skeleton
## Summary
## Findings or proposal
## Evidence vs assumptions
## Risks or tradeoffs
## Recommended next skill
Handoff targets
- api-error-model-designer
- crud-surface-reviewer
- persistence-test-planner
1---2name: api-contract-writer-23description: api-contract-writer4---5# api-contract-writer67## Purpose8Write backend API contracts covering endpoints or operations, payloads, validation, errors, idempotency, and state transitions.910## Expected inputs11- current backend or persistence context12- data model or schema details13- constraints or stack context14- known risks or unresolved decisions1516## Deliverables17- structured recommendation18- design notes19- risks or gaps20- recommended next artifact2122## Trigger this skill when23- You are designing or reviewing backend behavior, persistence, or API structure rather than only UI flow.24- Data modeling, transactions, migration, or access-layer choices materially affect correctness or maintainability.25- A team needs sharper boundaries between domain logic, persistence logic, and API contracts.2627## Operating procedure281. Clarify the domain, data lifecycle, and current or intended persistence approach.292. Separate facts, assumptions, constraints, and unresolved backend-specific risks.303. Prefer concrete operational behavior over abstract framework enthusiasm.314. Explicitly handle invalid, missing, conflict, and rollback cases where relevant.325. Recommend the next most useful backend, persistence, or testing skill.3334## Quality gates35- The recommendation respects real data lifecycle and consistency needs.36- Failure and conflict cases are not ignored.37- Assumptions and unresolved decisions are visible.38- Output is specific enough to influence implementation, schema, or testing.3940## Output style41- Be concrete and structured.42- Separate findings, assumptions, and recommendations.43- Prefer explicit tradeoffs over single-answer absolutism.44- Use severity or priority where useful.4546## Failure modes to avoid47- Do not blur domain logic, persistence logic, and transport concerns.48- Do not describe happy-path behavior only.49- Do not hide uncertainty behind ORM or framework jargon.50- Do not recommend migrations or transactions without discussing rollback and compatibility.5152## Minimum output skeleton53```md54## Summary55## Findings or proposal56## Evidence vs assumptions57## Risks or tradeoffs58## Recommended next skill59```6061## Handoff targets62- api-error-model-designer63- crud-surface-reviewer64- persistence-test-planner
45ck