playbooks

home / skills / duc01226 / easyplatform / tasks-spec-update

tasks-spec-update skill

/.claude/skills/tasks-spec-update

This skill synchronizes specifications with current implementation by discovering changes, analyzing gaps, and updating docs across code and specs.

npx playbooks add skill duc01226/easyplatform --skill tasks-spec-update

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.6 KB
---
name: tasks-spec-update
version: 1.0.0
description: "[Testing] Use when updating specifications, comparing branches, or ensuring documentation reflects current implementation."
infer: false
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Task
---

# Specification Update Workflow

## Summary

**Goal:** Sync specification documents with current implementation by discovering changes, analyzing gaps, and updating specs.

| Step | Action | Key Notes |
|------|--------|-----------|
| 1 | Change discovery | Git diff between branches or pattern-based file search |
| 2 | Gap analysis | Create comparison table: Specified vs Implemented vs Gap |
| 3 | Specification update | Update entity props, commands, validation, side effects, API endpoints |
| 4 | Verification | Cross-reference all commands/queries in code vs specs |

**Key Principles:**
- Always cross-reference specs with actual code (grep both `.md` and `.cs` files)
- Document both new implementations missing from specs and spec items not yet implemented
- Update version numbers and change logs after spec updates

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

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

### Pattern-Based Discovery

```bash
# Find all spec files
find . -name "*.spec.md" -o -name "*-specification.md"

# Cross-reference specs with code
grep -r "SaveEmployee" --include="*.md"  # In specs
grep -r "SaveEmployee" --include="*.cs"  # In code
```

## Phase 2: Gap Analysis

### Create Analysis Document

```markdown
# Specification Gap Analysis

## Implementation Status

| Component                | Specified | Implemented | Gap                    |
| ------------------------ | --------- | ----------- | ---------------------- |
| Entity: Employee         | Yes       | Yes         | None                   |
| Command: SaveEmployee    | Yes       | Yes         | Missing validation doc |
| Event: OnEmployeeCreated | No        | Yes         | Not in spec            |

## New Implementations (Not in Spec)
1. `BulkUpdateEmployeeCommand` - Added in PR #123

## Spec Items Not Implemented
1. `EmployeeArchiveCommand` - Deferred to Phase 2
```

## Phase 3: Specification Update

### Update Checklist

- [ ] Update entity property list
- [ ] Add new commands/queries
- [ ] Update validation rules
- [ ] Document side effects
- [ ] Add error codes
- [ ] Document new filters
- [ ] Update response schema
- [ ] List event handlers
- [ ] Describe cross-service effects
- [ ] Add new API endpoints
- [ ] Document auth requirements

## Phase 4: Verification

### Cross-Reference Check

```bash
# Verify all commands are documented
grep -r "class.*Command" --include="*.cs" -l
# Cross-check against specs
grep -r "Command" docs/specifications/*.md
```

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

Overview

This skill helps keep specification documents synchronized with the current implementation by discovering code changes, analyzing gaps, and updating specs. It guides a repeatable workflow from change discovery through verification, ensuring documentation accurately reflects the codebase. Use it to reduce drift between code and written requirements and to produce clear change logs and version updates.

How this skill works

The skill scans branches and files to discover changes using git diffs and pattern-based searches. It then produces a gap analysis comparing Specified vs Implemented vs Gap, and provides a checklist-driven process to update entities, commands, validation rules, API endpoints, and side effects in specs. Finally, it verifies updates by cross-referencing commands/queries and class names between .cs files and specification documents and ensures versioning and change logs are updated.

When to use it

  • After merging or preparing a feature branch to sync docs with implementation
  • When comparing two branches to identify specification gaps
  • Before release to confirm specs, version numbers, and change logs are accurate
  • When new commands, events, or endpoints appear in code but are not in docs
  • During documentation sprints to plan small, verifiable update tasks

Best practices

  • Always grep both .md and .cs files to cross-reference names and signatures
  • Produce a simple gap-analysis table listing Specified, Implemented, and Gap
  • Break work into small todo tasks and include a final review task
  • Update version numbers and change logs as part of the spec change
  • Document both new implementations missing from specs and spec items not implemented

Example use cases

  • Find all spec files affected by a feature-branch using git diff and update those docs
  • Create a table that lists each command and whether it is documented, implemented, or missing validation notes
  • Add newly introduced API endpoints and auth requirements to the specification before release
  • Verify that every class.*Command implementation in C# is referenced in the specification files
  • Run a final cross-reference check to ensure change log and version number are updated

FAQ

How do I discover which spec files to update?

Use git diff between branches for file lists and pattern-based finds (e.g., *.spec.md) to locate candidate documents.

What should a minimal gap analysis include?

List component name, whether it is specified, whether it is implemented, and a concise gap summary; include examples for new implementations and deferred spec items.