Back to Details

tasks-spec-update

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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

基于Git的发现方式

bash
undefined
bash
undefined

Compare branches

Compare branches

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

Get detailed diff

Get detailed diff

git diff main..feature-branch
git diff main..feature-branch

List commits with messages

List commits with messages

git log main..feature-branch --oneline
git log main..feature-branch --oneline

Find files changed since date

Find files changed since date

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

Pattern-Based Discovery

基于模式的发现方式

bash
undefined
bash
undefined

Find all spec files

Find all spec files

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

Find implementation files

Find implementation files

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

Cross-reference

Cross-reference

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

Phase 2: Gap Analysis

第二阶段：差异分析

Create Analysis Document

创建分析文档

markdown
undefined
markdown
undefined

Specification Gap Analysis

Specification Gap Analysis

Date: [Date]

Date: [Date]

Feature: [Feature Name]

Feature: [Feature Name]

Implementation Status

Implementation Status

ComponentSpecifiedImplementedGap
Entity: Employee✅✅None
Command: SaveEmployee✅✅Missing validation doc
Query: GetEmployeeList✅✅Filters not documented
Event: OnEmployeeCreated❌✅Not in spec
ComponentSpecifiedImplementedGap
Entity: Employee✅✅None
Command: SaveEmployee✅✅Missing validation doc
Query: GetEmployeeList✅✅Filters not documented
Event: OnEmployeeCreated❌✅Not in spec

New Implementations (Not in Spec)

New Implementations (Not in Spec)

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

Spec Items Not Implemented

Spec Items Not Implemented

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

Documentation Updates Needed

Documentation Updates Needed

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

Phase 3: Specification Update

第三阶段：规格说明更新

Update Checklist

更新检查清单

markdown
undefined
markdown
undefined

Specification Updates

Specification Updates

Entities

Entities

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

Commands

Commands

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

Queries

Queries

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

Events

Events

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

API Endpoints

API Endpoints

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

Pattern 1: Entity Specification Update

模式1：实体规格说明更新

markdown
undefined
markdown
undefined

Employee Entity Specification

Employee Entity Specification

Properties

Properties

PropertyTypeRequiredDescription
IdstringYesUnique identifier (ULID)
FullNamestringYesEmployee full name (max 200)
EmailstringYesEmail address (unique per company)
StatusEmployeeStatusYesCurrent employment status
PhoneNumberstringNoContact phone (NEW in v2.1)
PropertyTypeRequiredDescription
IdstringYesUnique identifier (ULID)
FullNamestringYesEmployee full name (max 200)
EmailstringYesEmail address (unique per company)
StatusEmployeeStatusYesCurrent employment status
PhoneNumberstringNoContact phone (NEW in v2.1)

Computed Properties

Computed Properties

PropertyCalculation
IsActiveStatus == Active && !IsDeleted
DisplayName
{Code} - {FullName}
PropertyCalculation
IsActiveStatus == Active && !IsDeleted
DisplayName
{Code} - {FullName}

Validation Rules

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

Static Expressions

ExpressionPurpose
UniqueExpr(companyId, userId)Find unique employee
ActiveInCompanyExpr(companyId)Filter active employees
SearchExpr(term)Full-text search
undefined
ExpressionPurpose
UniqueExpr(companyId, userId)Find unique employee
ActiveInCompanyExpr(companyId)Filter active employees
SearchExpr(term)Full-text search
undefined

Pattern 2: Command Specification Update

模式2：命令规格说明更新

markdown
undefined
markdown
undefined

SaveEmployeeCommand Specification

SaveEmployeeCommand Specification

Overview

Overview

Creates or updates an employee record.
Creates or updates an employee record.

Request

Request

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

Validation

Validation

FieldRuleError Code
fullNameRequiredEMPLOYEE_NAME_REQUIRED
fullNameMax 200 charsEMPLOYEE_NAME_TOO_LONG
emailRequiredEMPLOYEE_EMAIL_REQUIRED
emailValid formatEMPLOYEE_EMAIL_INVALID
emailUnique in companyEMPLOYEE_EMAIL_EXISTS
FieldRuleError Code
fullNameRequiredEMPLOYEE_NAME_REQUIRED
fullNameMax 200 charsEMPLOYEE_NAME_TOO_LONG
emailRequiredEMPLOYEE_EMAIL_REQUIRED
emailValid formatEMPLOYEE_EMAIL_INVALID
emailUnique in companyEMPLOYEE_EMAIL_EXISTS

Response

Response

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

Side Effects

Side Effects

  1. Entity Event: 
    PlatformCqrsEntityEvent<Employee>
    raised
  2. Cross-Service Sync: Employee synced to other services
  3. Notification: Welcome email sent (create only)
  1. Entity Event: 
    PlatformCqrsEntityEvent<Employee>
    raised
  2. Cross-Service Sync: Employee synced to other services
  3. Notification: Welcome email sent (create only)

Error Codes

Error Codes

CodeHTTPDescription
EMPLOYEE_NOT_FOUND404Employee ID not found
EMPLOYEE_EMAIL_EXISTS400Email already in use
EMPLOYEE_VALIDATION_FAILED400Validation error
undefined
CodeHTTPDescription
EMPLOYEE_NOT_FOUND404Employee ID not found
EMPLOYEE_EMAIL_EXISTS400Email already in use
EMPLOYEE_VALIDATION_FAILED400Validation error
undefined

Pattern 3: API Endpoint Specification

模式3：API端点规格说明更新

markdown
undefined
markdown
undefined

Employee API Endpoints

Employee API Endpoints

Base URL

Base URL

/api/Employee
/api/Employee

Endpoints

Endpoints

GET /api/Employee

GET /api/Employee

List employees with filtering and pagination.
Query Parameters
ParameterTypeDescription
searchTextstringFull-text search
statusesarrayFilter by status
skipCountintPagination offset
maxResultCountintPage size (max 100)
Response
json
{
  "items": [...],
  "totalCount": 100
}
List employees with filtering and pagination.
Query Parameters
ParameterTypeDescription
searchTextstringFull-text search
statusesarrayFilter by status
skipCountintPagination offset
maxResultCountintPage size (max 100)
Response
json
{
  "items": [...],
  "totalCount": 100
}

POST /api/Employee

POST /api/Employee

Create or update employee.
Request Body See SaveEmployeeCommand specification.
Create or update employee.
Request Body See SaveEmployeeCommand specification.

DELETE /api/Employee/{id}

DELETE /api/Employee/{id}

Soft delete an employee.
Path Parameters
ParameterTypeDescription
idstringEmployee ID
Response: 204 No Content
Soft delete an employee.
Path Parameters
ParameterTypeDescription
idstringEmployee ID
Response: 204 No Content

Authentication

Authentication

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

Authorization

Authorization

EndpointRequired Role
GETEmployee, Manager, Admin
POSTManager, Admin
DELETEAdmin
undefined
EndpointRequired Role
GETEmployee, Manager, Admin
POSTManager, Admin
DELETEAdmin
undefined

Phase 4: Verification

第四阶段：验证

Cross-Reference Check

交叉引用检查

bash
undefined
bash
undefined

Verify all commands are documented

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

Validation Report

验证报告

markdown
undefined
markdown
undefined

Specification Verification Report

Specification Verification Report

Date: [Date]

Date: [Date]

Verified By: AI

Verified By: AI

Summary

Summary

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

Issues Found

Issues Found

Outdated Specifications

Outdated Specifications

  1. Employee.spec.md
    • Missing: PhoneNumber property
    • Missing: BulkUpdate command
  2. API-Reference.md
    • Missing: /export endpoint
    • Outdated: Error codes
  1. Employee.spec.md
    • Missing: PhoneNumber property
    • Missing: BulkUpdate command
  2. API-Reference.md
    • Missing: /export endpoint
    • Outdated: Error codes

Recommendations

Recommendations

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

Verification Checklist

验证检查清单

  • All implementation changes identified
  • Gap analysis completed
  • Specifications updated
  • Cross-references verified
  • Version numbers updated
  • Change log updated
  • 已识别所有实现变更
  • 已完成差异分析
  • 已更新规格说明
  • 已验证交叉引用
  • 已更新版本号
  • 已更新变更日志