tasks-spec-update（任务规格更新）

[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:

1. Change Discovery — Git-based (diff branches, commits) or pattern-based (find specs, cross-reference with code)
2. Gap Analysis — Create analysis document comparing Specified vs Implemented, identify gaps, new items, deferred items
3. Specification Update — Update entities, commands, queries, events, API endpoints with new details
4. 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

| Component                | Specified | Implemented | Gap                    |
| ------------------------ | --------- | ----------- | ---------------------- |
| Entity: Employee         | ✅        | ✅          | None                   |
| Command: SaveEmployee    | ✅        | ✅          | Missing validation doc |
| Query: GetEmployeeList   | ✅        | ✅          | Filters not documented |
| Event: OnEmployeeCreated | ❌        | ✅          | Not in spec            |

## 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

| Property    | Type           | Required | Description                        |
| ----------- | -------------- | -------- | ---------------------------------- |
| Id          | string         | Yes      | Unique identifier (ULID)           |
| FullName    | string         | Yes      | Employee full name (max 200)       |
| Email       | string         | Yes      | Email address (unique per company) |
| Status      | EmployeeStatus | Yes      | Current employment status          |
| PhoneNumber | string         | No       | Contact phone (NEW in v2.1)        |

## Computed Properties

| Property    | Calculation                    |
| ----------- | ------------------------------ |
| IsActive    | Status == Active && !IsDeleted |
| DisplayName | `{Code} - {FullName}`          |

## 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

| Expression                     | Purpose                 |
| ------------------------------ | ----------------------- |
| UniqueExpr(companyId, userId)  | Find unique employee    |
| ActiveInCompanyExpr(companyId) | Filter active employees |
| SearchExpr(term)               | Full-text search        |

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

Response

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

Side Effects

1. Entity Event: Entity event raised (search for: project entity event class)
2. Cross-Service Sync: Employee synced to target service
3. Notification: Welcome email sent (create only)

Error Codes

## Pattern 3: API Endpoint Specification

Employee API Endpoints

Base URL

/api/Employee

Endpoints

GET /api/Employee

List employees with filtering and pagination.

Query Parameters

Response

{
  "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

Response: 204 No Content

Authentication

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

Authorization

## Phase 4: Verification

### Cross-Reference Check

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

1. 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