Accessor Specification Writer Skill

This skill enables creating, modifying, and analyzing accessor service specification documents for the Lista Payroll System.

When to Use This Skill

Use this skill when:

• Creating new .spec.md files in docs/services/accessor/*/ directories
• Modifying existing accessor specifications
• Analyzing or reviewing service specifications
• Defining new operations (Store, Fetch, Update, Delete)
• Adding new facets or profile types
• Working with data schema models

Scope

This skill applies ONLY to .spec.md files in the docs/services/accessor/*/ directories. These specification documents define:

• Service operation contracts (Request/Response)
• Data schema models for Marten/PostgreSQL
• Validation rules and constraints
• Type definitions that feed into code generation

Core Concepts

Facets

A facet represents a domain concept boundary within an accessor service:

• Company Facet - All company-related profiles (accounting, payroll)
• Employee Facet - All employee-related profiles (personal, employment, payroll, address)

Each facet may contain multiple profile types or aspects.

Operations

Standard operation patterns:

• Store - Create or update a resource
• Fetch - Retrieve a resource by ID
• Update - Modify an existing resource
• Delete - Remove a resource

Document Structure

Required Format

# [Service Name] [Facet Name] Facet Specification

## Overview

[Brief description of what this facet provides]

---

# [Operation Name]

[Brief description of the operation]

- Accessor: [Accessor Name]
- Operation: [Operation Name]

## Request

### Body

#### [RequestTypeName]

| Property | Type | Constraints | Validation |
| -------- | ---- | ----------- | ---------- |
| [name]   | [type] | [constraints] | [validation rules] |

## Response

### Body

#### [ResponseTypeName]

| Property | Type | Constraints | Validation |
| -------- | ---- | ----------- | ---------- |
| [name]   | [type] | [constraints] | [validation rules] |

---

## Data Schema Models

### [ModelName]

[Description of the model]

| Property | Type | Constraints |
| -------- | ---- | ----------- |
| [name]   | [type] | [constraints] |

Section Separators

• Separate operations with ---
• Data Schema Models section goes at the end

Naming Conventions

Request/Response Types

CRITICAL: Follow these exact patterns:

Operation	Request Pattern	Response Pattern
Store	[EntityType]StoreRequest	[EntityType]StoreResponse
Fetch	[EntityType]FetchRequest	[EntityType]FetchResponse
Update	[EntityType]UpdateRequest	[EntityType]UpdateResponse
Delete	[EntityType]DeleteRequest	[EntityType]DeleteResponse

Examples:

• PersonalProfileStoreRequest / PersonalProfileStoreResponse
• AccountingProfileFetchRequest / AccountingProfileFetchResponse
• WorkOrderUpdateRequest / WorkOrderUpdateResponse

Data Model Names

• Use PascalCase
• Prefix with facet context: Company[Type], Employee[Type]
• Be descriptive: CompanyAccountingProfile, EmployeePersonalProfile

Type System

Supported C# Types

Type	Usage
string	Text fields (names, identifiers)
string?	Optional text fields
int	Integer numbers
int?	Optional integers
decimal	Monetary values, rates, quantities
decimal?	Optional decimal values
bool	Boolean flags
DateOnly	Date without time (birth dates, hire dates)
DateOnly?	Optional date
DateTime	Date with time (timestamps)
Guid	Unique identifiers
List<T>	Collections

Type Selection Guidelines

• Use DateOnly for business dates (NOT DateTime)
• Use decimal for all monetary values (NOT float or double)
• Use Guid for generated IDs, string for user-facing IDs
• Always consider nullability - use ? for optional fields

Constraints and Validation

Table Columns

CRITICAL RULE: Request/Response tables have 4 columns, Data Schema Models have 3 columns.

Request/Response Tables (4 columns)

| Property | Type | Constraints | Validation |

Data Schema Models (3 columns - NO Validation column)

| Property | Type | Constraints |

Common Constraints

• Required - Field cannot be null/empty
• MaxLength(n) - Maximum string length
• MinLength(n) - Minimum string length
• Range(min, max) - Numeric range
• Validate to (12,2) - Decimal precision/scale

Validation Column Usage

The Validation column is ONLY used in Request/Response tables:

• Enumerated values: One of: 'value1', 'value2'
• Format requirements: Email format, SSN format, Phone format
• Business rules: Custom validation descriptions
• Cross-field dependencies: Must be after StartDate

Example: Request with Validation

#### PersonalProfileStoreRequest

| Property             | Type       | Constraints | Validation |
| -------------------- | ---------- | ----------- | ---------- |
| Id                   | `string`   | `Required`  |            |
| FirstName            | `string`   | `Required`  |            |
| LastName             | `string`   | `Required`  |            |
| DateOfBirth          | `DateOnly` | `Required`  |            |
| SocialSecurityNumber | `string`   | `Required`  | SSN format |
| Email                | `string?`  |             | Email format |

Example: Data Schema Model (No Validation)

### EmployeePersonalProfile

Database model for storing employee personal profile information.

| Property             | Type       | Constraints |
| -------------------- | ---------- | ----------- |
| Id                   | `string`   | `Required`  |
| FirstName            | `string`   | `Required`  |
| LastName             | `string`   | `Required`  |
| DateOfBirth          | `DateOnly` | `Required`  |
| SocialSecurityNumber | `string`   | `Required`  |

Advanced Patterns

Union Types

When a facet supports multiple profile types:

1. Note in the overview: "supports [type1] or [type2] via union"
2. Document each type as separate Request/Response pairs under the same operation
3. Each type gets its own table section

Example:

# Store Profile

This operation is used to store company profile information. The operation accepts either an accounting profile or a payroll profile request.

- Accessor: Profile
- Operation: Store

## Request

### Body

The request supports two profile types via union:

#### AccountingProfileStoreRequest

| Property    | Type     | Constraints | Validation |
| ----------- | -------- | ----------- | ---------- |
| Id          | `string` | `Required`  |            |
| CompanyName | `string` | `Required`  |            |

#### PayrollProfileStoreRequest

| Property           | Type     | Constraints | Validation |
| ------------------ | -------- | ----------- | ---------- |
| Id                 | `string` | `Required`  |            |
| FederalEmployerId  | `string` | `Required`  |            |

Multi-Value Returns

For operations returning multiple items:

#### AddressesFetchResponse

| Property | Type | Constraints | Validation |
| -------- | ---- | ----------- | ---------- |
| Items    | `List<AddressDetail>` | `Required` | |

#### AddressDetail

| Property | Type | Constraints | Validation |
| -------- | ---- | ----------- | ---------- |
| Street   | `string` | `Required` | |
| City     | `string` | `Required` | |
| State    | `string` | `Required` | One of: 'AL', 'AK', ... |
| ZipCode  | `string` | `Required` | |

Complex Nested Structures

For nested objects:

#### InvoiceStoreRequest

| Property | Type | Constraints | Validation |
| -------- | ---- | ----------- | ---------- |
| InvoiceId | `string` | `Required` | |
| LineItems | `List<InvoiceLineItem>` | `Required` | |
| Total     | `decimal` | `Required` | Validate to (12,2) |

#### InvoiceLineItem

| Property    | Type     | Constraints | Validation |
| ----------- | -------- | ----------- | ---------- |
| Description | `string` | `Required`  | |
| Amount      | `decimal` | `Required` | Validate to (12,2) |
| Quantity    | `int`    | `Required`  | |

Data Schema Models Section

REQUIRED at the end of every specification:

## Data Schema Models

### [ModelName]

[Brief description of the model's purpose]

| Property | Type | Constraints |
| -------- | ---- | ----------- |
| [name]   | [type] | [constraints] |

Requirements:

• Use 3-column format (NO Validation column)
• Include brief description above each model
• List all database models used by the facet
• Models correspond to Marten documents in PostgreSQL

Quality Checklist

Before finalizing a specification:

Completeness

• All properties for operations are documented
• Both request and response are fully specified
• Data schema models section included
• All nested types are defined

Consistency

• Naming conventions followed exactly
• Type names use PascalCase
• Request/Response suffixes match operation type
• Correct column counts (4 for contracts, 3 for models)

Type Safety

• Correct C# type names
• Nullability explicit with ?
• DateOnly for business dates
• decimal for monetary values with precision/scale
• Collection types use List<T>

Validation

• Required fields marked
• String lengths specified where applicable
• Decimal precision documented
• Validation column ONLY in Request/Response tables
• Validation rules are clear

Organization

• Operations separated by ---
• Data Schema Models at the end
• Proper headers and descriptions

Reference Examples

Example Files in Repository

• docs/services/accessor/profile/company.spec.md - Union types example
• docs/services/accessor/profile/employee.spec.md - Personal profile example

Common Mistakes to Avoid

❌ DON'T:

• Use DateTime for business dates (use DateOnly)
• Forget ? for optional fields
• Use inconsistent naming (e.g., ProfileRequest instead of ProfileStoreRequest)
• Add Validation column to Data Schema Models
• Forget Data Schema Models section
• Use float/double for money (use decimal)
• Omit decimal precision/scale for monetary fields
• Use lowercase or snake_case for type names
• Forget operation separators (---)

✅ DO:

• Use DateOnly for dates
• Use decimal with precision for money
• Follow naming patterns exactly
• Include all required sections
• Document validation rules clearly
• Keep Request/Response contracts separate from Data Schema Models
• Include descriptive overviews

Integration Notes

These specifications feed into code generation for:

• Interface definitions in *.Interfaces projects
• Request/Response DTOs
• Marten document models for PostgreSQL
• Service implementations in *.Service projects
• MassTransit message contracts

Therefore:

• Specifications must be complete (missing fields break generated code)
• Naming must match conventions (for code generators)
• Types must be correct (mismatches cause compilation errors)
• Constraints translate to code validation

Step-by-Step Workflow

When creating a new specification:

1. Understand the domain - What facet and operations are needed?
2. Choose operation types - Store? Fetch? Update? Delete?
3. Define request contracts - What data goes in? (4 columns)
4. Define response contracts - What data comes back? (4 columns)
5. Document validation - Add validation rules in Validation column
6. Define data models - What persists to database? (3 columns)
7. Review checklist - Ensure completeness and consistency
8. Cross-reference examples - Match patterns from existing specs

When modifying existing specifications:

1. Read entire spec - Understand current structure
2. Identify change scope - What needs to change?
3. Maintain consistency - Match existing patterns
4. Update related sections - If request changes, check response and models
5. Verify completeness - All fields documented?
6. Review checklist - Quality check

Summary

This skill provides comprehensive guidance for creating accessor service specifications in the Lista Payroll System. Key principles:

• Strict structure - Follow the template exactly
• Naming conventions - [Type][Operation]Request/Response
• Type system - Use correct C# types (DateOnly, decimal, etc.)
• Validation rules - 4 columns for contracts, 3 for models
• Data models - Always include at the end
• Quality - Complete, consistent, and correct

The specifications you create drive code generation, so precision and consistency are critical.

Task Playbooks

Draft a New Facet Specification

1. Confirm the facet scope, accessor name, and required operations with product or architecture documents.
2. Create the .spec.md file following the template in this skill; keep headings and separators identical.
3. Write a concise overview that mentions unions or multi-operation coverage.
4. Document each operation (Store/Fetch/Update/Delete) with properly formatted request and response tables.
5. Add validation guidance in the Validation column; leave the column blank rather than deleting it when rules are absent.
6. Author the Data Schema Models section with all persisted entities, matching property names and types.
7. Run through the Completeness, Consistency, Type Safety, Validation, and Organization checklists.
8. Share the draft with implementation owners before code generation.

Extend an Existing Specification

1. Read the entire spec to understand current structure and unions.
2. Update request/response tables to include new properties or variants, maintaining table order and formatting.
3. Modify Data Schema Models to reflect new persisted fields or entities.
4. Adjust overview text and union descriptions if the supported variants changed.
5. Update validation rules to capture new constraints or business rules.
6. Verify linked implementations (interfaces, service models) will be updated in tandem; note follow-up tasks if needed.
7. Re-run the quality checklist and ensure Markdown renders cleanly.

Acceptance Criteria

• Each specification conforms to the documented structure, headings, and table formats.
• Request/response and schema sections remain synchronized with agreed type names and constraints.
• Validation guidance appears only where appropriate and is clear enough for code generation or manual enforcement.
• Union and multi-value operations explicitly document every supported variant in both prose and table form.
• The final document equips implementers to generate interfaces, models, and tests without guessing missing details.