[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ask user whether to skip.

Prerequisites: MUST READ .claude/skills/shared/evidence-based-reasoning-protocol.md before executing.

Quick Summary

Goal: Update specifications to match implementation, compare branches, and ensure documentation reflects current state.

Workflow:

• Change Discovery — Git-based (diff branches, commits) or pattern-based (find specs, cross-reference with code)

• Gap Analysis — Create analysis document comparing Specified vs Implemented, identify gaps, new items, deferred items

• Specification Update — Update entities, commands, queries, events, API endpoints with new details

• Verification — Cross-reference check (all commands documented?), validation report

Key Rules:

• Pattern Updates: Entity specs (properties, computed, validation, expressions), Command specs (request/response, validation, side effects, errors), API endpoint specs

• Systematic: Use bash scripts to find undocumented commands

• Completeness: Verify all implementation changes are documented

• Version Control: Update version numbers and change logs

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof.

Specification Update Workflow

When to Use This Skill

• Syncing specs with implementation

• Branch comparison analysis

• Post-implementation documentation update

• Feature spec verification

Pre-Flight Checklist

• Identify specification files to update

• Determine implementation changes

• Compare current state vs documented state

• Plan update strategy

Phase 1: Change Discovery

Git-Based Discovery

Compare branches

git diff main..feature-branch --name-only

Get detailed diff

git diff main..feature-branch

List commits with messages

git log main..feature-branch --oneline

Find files changed since date

git log --since="2024-01-01" --name-only --oneline

Pattern-Based Discovery

Find all spec files

find . -name ".spec.md" -o -name "-specification.md"

Find implementation files

grep -r "class.Command" --include=".cs" -l

Cross-reference

grep -r "SaveEmployee" --include=".md" # In specs grep -r "SaveEmployee" --include=".cs" # In code

Phase 2: Gap Analysis

Create Analysis Document

Specification Gap Analysis

Date: [Date]

Feature: [Feature Name]

Implementation Status

New Implementations (Not in Spec)

1. BulkUpdateEmployeeCommand - Added in PR #123
2. EmployeeExportQuery - Added for reporting

Spec Items Not Implemented

1. EmployeeArchiveCommand - Deferred to Phase 2
2. EmployeeAuditTrail - Pending requirements

Documentation Updates Needed

1. Add BulkUpdateEmployeeCommand to spec
2. Document new query filters
3. Add event handler documentation

Phase 3: Specification Update

Update Checklist

Specification Updates

Entities

• Update property list
• Document new computed properties
• Add validation rules
• Update relationships

Commands

• Add new commands
• Update validation rules
• Document side effects
• Add error codes

Queries

• Document new filters
• Update response schema
• Add pagination details

Events

• Document entity events
• List event handlers
• Describe cross-service effects

API Endpoints

• Add new endpoints
• Update request/response
• Document auth requirements

Pattern 1: Entity Specification Update

Employee Entity Specification

Properties

Computed Properties

Validation Rules

1. FullName: Required, max 200 characters
2. Email: Required, valid email format, unique within company
3. PhoneNumber: Optional, valid phone format (NEW in v2.1)

Static Expressions

Pattern 2: Command Specification Update

SaveEmployeeCommand Specification

Overview

Creates or updates an employee record.

Request

{
    "id": "string | null",
    "fullName": "string",
    "email": "string",
    "status": "Active | Inactive | Terminated",
    "phoneNumber": "string | null"
}

Validation

Field Rule Error Code

fullName Required EMPLOYEE_NAME_REQUIRED

fullName Max 200 chars EMPLOYEE_NAME_TOO_LONG

email Required EMPLOYEE_EMAIL_REQUIRED

email Valid format EMPLOYEE_EMAIL_INVALID

email Unique in company EMPLOYEE_EMAIL_EXISTS

Response

{ "employee": { "id": "string", "fullName": "string", "email": "string", "status": "string" } }

Side Effects

• Entity Event: Entity event raised (search for: project entity event class)

• Cross-Service Sync: Employee synced to target service

• Notification: Welcome email sent (create only)

Error Codes

Code HTTP Description

EMPLOYEE_NOT_FOUND 404 Employee ID not found

EMPLOYEE_EMAIL_EXISTS 400 Email already in use

EMPLOYEE_VALIDATION_FAILED 400 Validation error

Pattern 3: API Endpoint Specification

# Employee API Endpoints

## Base URL
`/api/Employee`

## Endpoints

### GET /api/Employee
List employees with filtering and pagination.

**Query Parameters**
| Parameter      | Type   | Description         |
| -------------- | ------ | ------------------- |
| searchText     | string | Full-text search    |
| statuses       | array  | Filter by status    |
| skipCount      | int    | Pagination offset   |
| maxResultCount | int    | Page size (max 100) |

**Response**
```json
{
  "items": [...],
  "totalCount": 100
}

POST /api/Employee

Create or update employee.

Request Body
See SaveEmployeeCommand specification.

DELETE /api/Employee/{id}

Soft delete an employee.

Path Parameters

Parameter
Type
Description

id
string
Employee ID

Response: 204 No Content

Authentication

All endpoints require authentication.
Use Authorization: Bearer {token}
 header.

Authorization

Endpoint
Required Role

GET
Employee, Manager, Admin

POST
Manager, Admin

DELETE
Admin

## Phase 4: Verification

### Cross-Reference Check
```bash
# Verify all commands are documented
for cmd in $(grep -r "class.*Command" --include="*.cs" -l); do
  name=$(grep -o "class [A-Za-z]*Command" "$cmd" | head -1)
  if ! grep -q "$name" docs/specifications/*.md; then
    echo "Missing in spec: $name"
  fi
done

Validation Report

# Specification Verification Report

## Date: [Date]

## Verified By: AI

## Summary

- Total Specs: 15
- Up to Date: 12
- Needs Update: 3
- Missing: 0

## Issues Found

### Outdated Specifications

1. **Employee.spec.md**
    - Missing: PhoneNumber property
    - Missing: BulkUpdate command

2. **API-Reference.md**
    - Missing: /export endpoint
    - Outdated: Error codes

## Recommendations

1. Update Employee.spec.md with new properties
2. Add BulkUpdateEmployeeCommand specification
3. Regenerate API reference from OpenAPI

Verification Checklist

-  All implementation changes identified

-  Gap analysis completed

-  Specifications updated

-  Cross-references verified

-  Version numbers updated

-  Change log updated

Related

- tasks-documentation

- documentation

IMPORTANT Task Planning Notes (MUST FOLLOW)

- Always plan and break work into many small todo tasks

- Always add a final review todo task to verify work quality and identify fixes/enhancements