contract-sync-audit

Files (1)

• SKILL.md

SKILL.md (first lines)

# Contract Sync Audit — Reconcile Backend & Frontend

You are an **integration auditor**. The project already has both a backend and a frontend, and they disagree about the API. Your job is to find every disagreement deterministically, decide a canonical source of truth, and produce a reconciliation report. You do **not** apply fixes — you make the gap visible and propose how to close it.

## When this applies

- The user reports "the frontend expects things the backend doesn't return", wrong URLs, 404s on calls that "should work", or shape mismatches.
- An existing project is adopting Specture (`setup` Adopt) and needs its back/front interface reconciled before building further.
- Before bringing external design material into a codebase whose API is already drifting — audit first so the new UI is wired to a coherent contract.

> **Antigravity:** if the session exposes `define_subagent`, register the agents this skill dispatches from `agents/<name>/AGENT.md` before the first dispatch — `architecture-validator` read-only (all flags `false`), any agent that writes with `enable_write_tools: true` (the flag defaults to `false`). In Claude Code they are registered by the plugin. The table of flags is in `build/SKILL.md` § "Cross-Platform Subagent Initialization".

## Required Inputs

- `.specture/stack.yml` — `backend.framework`, `frontend.framework`, languages. Drives how routes/calls are extracted.
- `.specture/conventions.md`.
- The contract file declared in `stack.yml.api.contract_file` (default `docs/02-architecture/api-contract.openapi.yaml`; `.json`, SDL or `.proto` per `api.style`) + its companion `docs/02-architecture/api-contract.md`, **if they exist** — the natural canonical source.
- Read access to the backend route definitions and the frontend API-calling code.

## Step 0 — Choose the canonical source

Before diffing, decide what "correct" means:

1. **An existing contract file (`stack.yml.api.contract_file`)** → it is canonical. Both sides are audited against it.
2. **No contract, backend is authoritative** (common when the backend is stable and the frontend drifted) → extract a contract from the backend; the frontend is audited against it.
3. **No contract, frontend is authoritative** (the UI defines the desired interface) → the backend is audited against the frontend's expectations.
4. **No contract, neither is fully right** → produce a *proposed reconciled* contract and audit both sides against it.

Ask the user which case applies if it isn't obvious. The canonical choice determines the direction of every proposed fix.

## Step 1 — Extract backend routes (deterministic where possible)

Prefer the most authoritative source available, in this order:

1. **A live/served OpenAPI/Swagger** the backend already exposes (FastAPI `/openapi.json`, NestJS Swagger, Spring springdoc, ASP.NET Swashbuckle) → parse it directly. Most reliable.
2. **Static route extraction** per `backend.framework`:
   - Express/Fastify: `app.get/post/...` and `router.*` calls.
   - NestJS / Spring: controller decorators (`@Get`, `@Post`, `@RequestMapping`, `@GetMapping`).
   - FastAPI/Flask: `@app.get`/`@router.post`/`@app.route` decorators.
   - ASP.NET: `[HttpGet]`/`[Route]` attributes + controller route prefixes.
   - Go (gin/echo/chi), Rails routes, Laravel routes — analogous.

For each endpoint capture: **method, full path (with prefix), and the response type/shape** if the language is typed (DTO/return type) or serializer is declared.

## Step 2 — Extract frontend API calls

Find every backend call in the frontend per `frontend.framework`:

- `fetch(...)`, `axios.*`, Angular `HttpClient.*`, generated SDK calls, React Query / SWR hooks.
- Capture: **method, URL/path** (resolve base-URL constants and template literals as far as statically possible), and the **expected response shape** — from the TypeScript type the call is annotated/destructured with, or the way the result is consumed.

Note where a path is fully dynamic (built at runtime) — flag it as "not statically resolvable" rather than guessing.

## Step 3 — Diff and classify

Produce findings in these categories:

| Category | Meaning |
|---|---|
| **Missing endpoint** | Frontend calls an operation the backend does not expose (404 in production). |
| **URL/path mismatch** | Same intent, different path (e.g. `/psicologos/{slug}/disponibilidad` vs `/api/v1/availability`). |
| **Method mismatch** | Same path, different HTTP method. |
| **Shape mismatch** | Frontend expects fields/types the backend response doesn't provide (or vice versa). Only assertable where both sides are typed. |
| **Orphan endpoint** | Backend exposes an operation no frontend call uses (dead or undocumented). |
| **Auth mismatch** | Frontend sends/omits auth differently than the endpoint requires. |
| **Unresolved** | Path or shape couldn't be statically determined — needs manual confirmation. |

Each finding cites `file:line` on **both** sides where possible, pinned to the audited commit (`file:line @<sha>`) so the citation stays valid after the code moves. Record the audited SHA (`git rev-parse HEAD`) in the report header.

## Step 4 — Emit the reconciliation report

Write `docs/02-architecture/contract-sync-report.md`:

- **Canonical source** chosen (Step 0) and why.
- **Audited commit** (`git rev-parse HEAD`) — every `file:line` below is read at that SHA.
- A table of findings: category, frontend evidence (`file:line @<sha>`), backend evidence (`file:line @<sha>`), and the **proposed change** stated against the canonical source ("change the frontend call to `GET /api/v1/...`" or "add backend endpoint `...` returning `...`").
- A **coverage summary**: N endpoints, N matched, N mismatched, N orphan, N unresolved.
- If no contract existed, attach a **proposed contract file** at the path `stack.yml.api.contract_file` declares (default `api-contract.openapi.yaml`, from `$SPECTURE_ROOT/templates/api-contract.openapi.template.yaml`) reflecting the canonical interface, so the project gains the source of truth it was missing.

## Step 5 — Route the fixes (do NOT auto-apply)

This skill reports; it does not edit application code. Based on the findings:

- Each proposed change becomes work for the build pipeline: route to `skills/new-feature/SKILL.md` (missing endpoints / new operations) or `skills/build/SKILL.md` (align an existing epic), each backed by a spec referencing the now-canonical contract.
- If a mismatch is a genuine bug with unclear cause, route to `skills/debug/SKILL.md`.
- Once the contract exists, the frontend should regenerate its typed client from it so the class of "hand-written divergent URL" bugs cannot recur.

## Step 6 — Hand-off

Announce in Spanish:
> "Auditoría de sincronización lista en `docs/02-architecture/contract-sync-report.md`. Fuente canónica: **[contrato existente / backend / frontend / contrato reconciliado propuesto]**. Resumen: [N matched, N mismatched, N orphan, N unresolved]. [Si generé contrato: 'Dejé un contrato propuesto en la ruta de `stack.yml.api.contract_file` como nueva fuente de verdad.'] Los cambios propuestos NO se aplicaron — cada uno necesita su spec. ¿Quieres que enrute los arreglos a `build`/`new-feature`, o revisas el reporte primero?"

Wait for the user. Do not auto-apply changes.

## Honest Limits (state these)

- **Dynamically-typed backends** (plain JS, untyped Python) expose no response types to compare → shape mismatches there are heuristic at best (inferred from serialization code). URL/method diffs remain reliable; shape diffs get marked `Unresolved` when types are absent.
- **Runtime-built paths** (URLs assembled from variables) can't be fully resolved statically — they're flagged, not guessed.
- **The audit never auto-fixes.** Choosing which side bends to the other is a design decision (the canonical source); applying it goes through specs and the normal gates.
- **An exposed OpenAPI from the backend is the most reliable input** — recommend the project add one if it lacks both a contract and served schema.

From FerEscobarDev/Specture, MIT.

More from FerEscobarDev/Specture