service-scaffold

name	service-scaffold
description	Use when creating, updating, reviewing, or debugging service layers, business logic, use cases, domain logic, controller-service separation, dependency injection, or service tests.

Service Scaffold

Use this skill for clean, testable service-layer business logic.

Rules

• Follow the project’s existing service and architecture patterns.
• Do not introduce a new architecture, dependency injection system, or service framework unless already used or explicitly requested.
• Keep HTTP concerns out of services.
• Services must not receive raw request/response objects.
• Services should receive validated data and explicit context.
• Put business rules in services or use-cases, not controllers or repositories.
• Keep database queries in repositories, models, or data-access modules.
• Throw or return domain-level errors according to project patterns.
• Return domain/application results, not HTTP responses.
• Keep services focused and testable.
• Preserve existing response, error, logging, and test patterns.
• Avoid unrelated refactors.

Inspect First

Before changing service code, check existing patterns for:

• service location
• method naming
• DTO/input types
• context shape
• dependency usage
• repository/data access pattern
• error handling
• transaction handling
• logging
• test style

Implementation Checklist

• Identify the business operation.
• Reuse existing service structure.
• Accept only needed input and context.
• Validate business rules.
• Check ownership or permissions when needed.
• Call repositories/data-access modules for persistence.
• Call other services only when orchestration is required.
• Keep side effects explicit.
• Use transactions for multi-step critical changes when available.
• Return clean results.
• Add or update relevant tests.

Layer Boundaries

Controller or handler should:

• parse request
• validate request input
• extract user/session context
• call service
• map result to response
• map errors to response

Service should:

• enforce business rules
• orchestrate workflow
• check domain constraints
• call dependencies
• throw domain errors
• return domain/application data

Repository or data-access should:

• run database queries
• persist data
• return stored data
• avoid business decisions

Method Rules

Good service methods are:

• small enough to understand
• named by business action
• explicit about input
• explicit about context
• independent from HTTP
• easy to unit test

Avoid:

• giant services with unrelated methods
• raw SQL inside services unless this is the project pattern
• hidden global dependencies
• duplicated business rules
• circular service dependencies
• formatting API responses inside services

Security Rules

• Do not trust client-provided user IDs, roles, ownership, tenant IDs, prices, permissions, or status values.
• Derive identity and scope from verified server context.
• Enforce ownership and permission checks server-side.
• Do not leak sensitive data through returned service results.
• Keep privileged actions explicit.

Error Rules

• Use existing project error classes or result patterns.
• Use domain errors for expected business failures.
• Let controllers/handlers map errors to HTTP or UI responses.
• Do not expose database/provider errors directly.
• Do not swallow errors silently.
• Keep error behavior consistent with nearby services.

Tests

Cover relevant paths:

• successful business operation
• validation or business rule failure
• not found
• permission or ownership failure
• dependency failure
• side effect behavior
• transaction or rollback behavior if relevant

Use mocked dependencies when the project tests services in isolation.