Consolidate and improve evolved specs - identifies inconsistencies, removes redundancy, improves structure while maintaining feature coverage
Consolidates and reorganizes evolved specifications to improve clarity and maintainability. Triggers when specs have grown through multiple updates, contain redundancies, or need periodic maintenance before major work.
/plugin marketplace add rhuss/cc-superpowers-sdd/plugin install sdd@sdd-plugin-developmentThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Refactor specifications that have grown organically to improve clarity, consistency, and maintainability.
As specs evolve through sdd:evolve, they can accumulate:
This skill consolidates and improves specs while ensuring all implemented features remain covered.
Warning: Never refactor specs during active implementation. Wait until stable.
Read all related specs:
# Single spec
cat specs/features/[feature].md
# Multiple related specs
cat specs/features/user-*.md
Document current issues:
Check what's actually implemented:
# Find implementation
rg "[feature-related-terms]" src/
# Check tests
rg "[feature-related-terms]" tests/
Critical: Refactored spec MUST cover all implemented features.
Create coverage map:
Implemented Feature 1 → Spec Requirement X
Implemented Feature 2 → Spec Requirement Y
...
If implementation exists without spec coverage, ADD it during refactor.
Look for:
Redundant requirements:
Inconsistent terminology:
Scattered related requirements:
Better organization:
Example improvement:
Before:
## Requirements
- User login
- Password validation
- Email validation
- Session management
- Logout
- Password reset
- Email verification
After:
## Authentication Requirements
### User Registration
- Email validation
- Email verification
- Password validation
### Session Management
- User login
- Session creation
- Logout
- Session expiration
### Password Management
- Password reset
- Password change
- Password strength requirements
Steps:
Throughout: Maintain traceability to old spec
Check:
Use sdd:review-spec on refactored version.
Document changes:
## Spec Refactoring Changelog
**Date:** YYYY-MM-DD
**Previous Version:** [link or commit]
### Changes Made
**Structural Changes:**
- Reorganized requirements into logical groups
- Moved error handling to dedicated section
- Created sub-sections for clarity
**Consolidated Requirements:**
- Merged requirements 3, 7, 12 (all about validation)
- Combined duplicate error cases
- Unified session management requirements
**Terminology Standardization:**
- "User" → "Authenticated User" (consistent usage)
- "Login" → "Authentication" (aligned with codebase)
**Added Coverage:**
- Requirement 15: Password strength (implemented but not in spec)
- Error case 8: Rate limiting (implemented but not in spec)
**Removed:**
- Obsolete requirement 9 (feature removed in v2.0)
### Migration Notes
[How to map old spec sections to new spec sections]
Old Section 2.1 → New Section 3.1.1
Old Section 3.4 → New Section 2.3
...
For active projects:
For solo projects:
After refactoring:
# Check spec compliance with current code
# Use sdd:review-code
Ensure:
Use TodoWrite to track:
# Feature: User System
## Requirements
1. Users can register
2. Email must be validated
3. Password must be strong
4. Users can login
5. Sessions expire after 30 minutes
6. Users can logout
7. Passwords must have 8 characters
8. Passwords must have uppercase
9. Passwords must have lowercase
10. Passwords must have number
11. Email format must be valid
12. Users can reset password
13. Reset tokens expire after 1 hour
14. Users get logged out on password change
15. Sessions use JWT
16. JWT secret must be secure
...
(Requirements scattered, no organization, redundancy)
# Feature: User Authentication System
## Purpose
Provide secure user authentication with registration, login, and password management.
## User Registration
### Functional Requirements
1. Users can register with email and password
2. Registration creates user account and initial session
### Email Validation
- Must be valid email format (RFC 5322)
- Email verification required before account activation
- Verification link expires after 24 hours
### Password Requirements
- Minimum 8 characters
- Must contain: uppercase, lowercase, number
- Common passwords rejected (check against list)
## Session Management
### Authentication Flow
1. User provides credentials (email + password)
2. System validates credentials
3. On success: JWT token generated
4. Client stores token for subsequent requests
### Session Configuration
- Token type: JWT (JSON Web Token)
- Token expiration: 30 minutes
- Secret: Stored in environment variable (not in code)
- Algorithm: HS256
### Logout
- Client discards token
- Optional: Server-side token invalidation (if implemented)
## Password Management
### Password Reset
- User requests reset via email
- Reset token generated and emailed
- Reset token expires after 1 hour
- On successful reset: all sessions invalidated
### Password Change
- Requires current password confirmation
- On success: all sessions invalidated (forces re-login)
...
(Organized, consolidated, clear)
## Spec Refactoring Changelog
**Date:** 2025-11-10
### Structural Changes
- Reorganized flat list into hierarchical sections:
- User Registration
- Session Management
- Password Management
### Consolidated Requirements
- Requirements 7-10 → Single "Password Requirements" section
- Requirements 2, 11 → "Email Validation" section
- Requirements 4, 5, 6, 15, 16 → "Session Management" section
### Terminology Standardization
- Consistently use "JWT" (not "token" and "JWT" interchangeably)
- "User" context now explicit (authenticated vs unauthenticated)
### Added Coverage
- None (all features already in original spec)
### Removed
- None (all requirements preserved, just reorganized)
Problem: Password requirements in multiple places
Solution: Consolidate into single "Password Requirements" section
Problem: Some requirements specify errors, others don't
Solution: Create dedicated "Error Handling" section, reference from requirements
Problem: High-level and low-level requirements mixed
Solution: Create hierarchy - high-level functional requirements with detailed sub-sections
Problem: "User", "Account", "Profile" used interchangeably
Solution: Standardize on one term, define others in glossary if needed
Don't:
Do:
Refactoring improves form, not function.
Refactoring is maintenance, not change.
Good specs enable good work.
Periodic refactoring prevents spec decay.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.