Incremental Service Requirements

Use this template when modifying an existing service in the operations repository. It provides structured sections for documenting entity modifications, method changes, persistence migrations, and API contract changes.

When to Use

• Adding new capabilities or behaviors to an existing service.
• Modifying entity properties or validation rules.
• Changing method signatures or qualifier-based behavior.
• Adding database migrations or API endpoint changes.

Document Sections

The template covers six major areas:

1. Overview — Change summary, target service, change type classification, impact assessment.
2. Current State Analysis — Existing entity properties, validation rules, and method behaviors being modified.
3. Proposed Changes — Entity modifications (EM), method modifications (MM), persistence changes (PC), API changes (AC).
4. Testing Requirements — Existing test modifications, new unit/integration/API tests.
5. Migration & Deployment — Deployment order, feature flags, rollback plan.
6. Requirements Summary — Cross-reference index of all changes.

Change Type Classification

• New Capability: Adding new methods or behaviors
• Behavior Modification: Changing existing method behavior
• Entity Extension: Adding properties to existing entities
• New Child Entity: Adding a new entity under existing parent
• Persistence Change: Schema migration or query modification
• Integration Addition: New external system interaction

Requirement ID Conventions

Prefix	Category	Example
EM	Entity Modification	EM-SUP-001
MM	Method Modification	MM-SUP-001
PC	Persistence Change	PC-SUP-001
AC	API Change	AC-SUP-001
VR	Validation Rule	VR-NEW-001

Template

The full template is extensive. Key sections are shown below; see the complete source at workspace/knowledge-base/templates/incremental-service/incremental-service-requirements.md.

Overview Block

## Overview

### Change Summary

Brief description of the capability being added or modified.

### Target Service/Module

- **Service**: `ServiceNameService`
- **Package**: `cards.arda.operations.domain.module`
- **Repository**: `operations`

### Impact Assessment

| Area | Impact Level | Description |
|---|---|---|
| API Contract | None / Additive / Breaking | How does this affect the REST API? |
| Database Schema | None / Migration Required | Schema changes needed? |
| Existing Tests | None / Updates Required | Which tests need modification? |
| Client Applications | None / Optional Update / Required Update | Frontend/integration impact? |

Entity Modification Block

#### EM-CODE-001: Modify `EntityName`

- **Change Type**: Add Property | Modify Property | Remove Property | Add Validation

##### New/Modified Properties

| Property | Type | Required | Default | Change | Description |
|---|---|---|---|---|---|
| `property` | `Type` | Yes/No | `default` | **NEW** | Description |

##### Backward Compatibility

| Concern | Mitigation |
|---|---|
| Existing records without new field | Default value applied |
| Clients not sending new field | Field is optional |

Method Modification Block

#### MM-CODE-001: Modify `methodName`

- **Current Signature**: `suspend fun methodName(params): Result<CurrentReturn>`
- **New Signature**: `suspend fun methodName(params): Result<NewReturn>`

##### Behavior Changes by Qualifier

| Qualifier | Current Behavior | New Behavior | Change Reason |
|---|---|---|---|
| **LAX** | Current | New | Why |
| **STRICT** | Current | New | Why |
| **PROPAGATE** | Current | New | Why |

Persistence Change Block

#### PC-CODE-001: Schema Migration

- **Migration File**: `V<version>__<description>.sql`

##### Column Changes

| Table | Column | Change | Type | Nullable | Default | Notes |
|---|---|---|---|---|---|---|
| `table` | `column` | **ADD** | `type` | Yes/No | `default` | Notes |

##### Data Migration

SQL migration script outline with rollback strategy.