---
name: velcrafting/endpoint-scaffold
source: https://app.decimal.ai/s/velcrafting-endpoint-scaffold@1/SKILL.md
source_sha256: 1c542535fd7d
---

# Skill: backend/endpoint-scaffold

## Purpose
Add or extend an API endpoint in a way that is:
- validated (request + response shape)
- authorized (authn/authz hooks enforced)
- mapped to a stable error taxonomy
- covered by tests

This skill is the default entry point for backend feature exposure.

---

## Inputs
- Endpoint intent (what it does, who calls it)
- Contract surface (preferred):
  - method + path
  - request fields + types
  - response shape + types
- Authorization expectation:
  - public / authenticated / role-based / resource-based
- Error expectations:
  - list of expected failure cases
- Repo profile (preferred): `<repo>/REPO_PROFILE.json`

---

## Outputs
- New or updated endpoint handler/controller/router entry
- Input validation (schema/types) consistent with repo patterns
- Authorization enforcement consistent with repo patterns
- Error mapping consistent with shared error taxonomy
- Tests:
  - unit tests for handler logic and validation OR
  - integration tests at route boundary (preferred when available)

---

## Non-goals
- Implementing complex domain rules inside the handler (use `backend/domain-logic-module`)
- Changing persistence schema (use `backend/persistence-layer-change`)
- Changing API contracts across consumers (use `api/contract-update` if needed)
- Cross-cutting architecture rewrites

---

## Workflow
1) Discover repo endpoint conventions:
   - routing system, validation library, error shape, auth middleware
   - prefer `REPO_PROFILE.json` if present
2) Define contract explicitly:
   - request parsing + validation
   - response shape
3) Enforce authorization:
   - fail closed by default
   - ensure resource checks exist if needed
4) Call domain logic via a module boundary:
   - handler orchestrates, domain module decides
5) Map errors to a stable taxonomy:
   - user errors vs system errors vs auth errors
6) Add tests at the highest stable layer available:
   - route integration tests if infra exists
   - otherwise unit tests of handler + domain module
7) If this endpoint introduces branching, retries, async coordination, or multi-step behavior,
   recommend `system/state-machine-mapper` and pause until the behavior is modeled or explicitly waived.

---

## Checks
- Endpoint returns correct status/shape for success
- Validation rejects malformed inputs deterministically
- Authorization cannot be bypassed (fail closed)
- Error responses conform to shared error taxonomy
- Tests cover:
  - happy path
  - at least 2 failure cases (validation + auth or domain)
- Typecheck/lint pass if configured

---

## Failure modes
- No error taxonomy exists → recommend `shared/error-taxonomy` before shipping.
- Authz rules unclear → recommend `backend/authz-policy` or `$decision-capture`.
- Contract unclear → recommend `meta/ask-questions-if-underspecified` or `api/contract-update`.
- Handler becomes “god function” → extract domain logic into `backend/domain-logic-module`.
- Non-trivial branching or async flow added without a state model →
  block completion and recommend `system/state-machine-mapper`.

---

## Telemetry
Log:
- skill: `backend/endpoint-scaffold`
- endpoint: `<method> <path>` (if known)
- authz: `public | authenticated | role | resource`
- tests_added: `unit | integration | none`
- files_touched
- outcome: `success | partial | blocked`