Backend contract reconciliation
Skill felipeblassioli/agent-skills/skills/backend-contract-reconciliation
Take draft endpoint artifacts produced by frontend-contract-discovery and reconcile them with backend implementation truth using strict trace sources.From its SKILL.md
npx -y skills add felipeblassioli/agent-skills --skill backend-contract-reconciliationAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
2.8 KB, as published. Nobody here has run it
Backend Contract Reconciliation
Take draft endpoint documentation (often produced by frontend inference) and upgrade it to a final, verified contract by finding the actual backend implementation.
This skill ensures that backend documentation is anchored in reality using strict code evidence (Trace Sources) rather than guesswork.
Applicability Gate
Use this skill when ANY of the following are true:
- the user wants to reconcile a draft or frontend-inferred API doc with the backend
- the user wants to map a backend router to an API doc
- the user wants to add strict Trace Sources to an existing endpoint doc
Do NOT use this skill when:
- the user wants to infer the API from a React/frontend client (use
frontend-contract-discoveryinstead) - the task is to design a completely new API from scratch
- the task is to validate live endpoints against a running service
Procedure
-
Investigate the Backend.
- If the codebase is large or the router is unknown, use the
Tasktool (subagentexploreorgeneralPurpose) to search for the path and verb without flooding your main context. - Once found, start from the matching router or controller.
- Follow the execution path through controllers, services, and repositories to understand the full contract (auth, validation, payloads, errors).
- Resolve discrepancies. If the frontend sends a field the backend ignores, or the backend requires a field the frontend missed, the backend implementation is the source of truth.
- If the codebase is large or the router is unknown, use the
-
Gather Trace Sources.
- Every non-obvious claim (validation rules, error codes, domain logic) MUST be supported by a Trace Source.
- Trace Sources must link directly to the code.
- Format:
[path/to/file.ts : L12-L26](https://<git-host>/<repo>/src/<commit>/path/to/file.ts#lines-12:26)(If git permalinks are unavailable, use local paths like- path/to/file.ts:12-26).
-
Draft the Final Document.
- Use the
Readtool to readassets/endpoint-doc-template.md. - Upgrade the draft endpoint document to use this strict backend template.
- Ensure the
Domain Logic Summaryaccurately reflects the backend execution path, side effects, and state mutations. - Fill in the
Source Tracesection with the gathered evidence.
- Use the
Output Contract
For every reconciled endpoint, output the final markdown document following the assets/endpoint-doc-template.md structure.
If you encounter unversioned breaking changes or conflicting definitions that you cannot resolve from code evidence alone, STOP and ask the user for clarification before finalizing the document.