This skill helps you reverse-engineer comprehensive specification documents from existing code snippets, following the OpenSpec philosophy and structure.
When working with existing codebases, documentation often lags behind implementation. This skill enables you to analyze code and generate structured documentation that captures:
Following OpenSpec principles:
→ behavior-first not implementation-first
→ progressive rigor not heavy upfront process
→ testable scenarios not vague descriptions
→ brownfield-friendly not greenfield-only
When provided with code snippets, analyze:
The proposal captures intent, scope, and approach at a high level.
# Proposal: [Feature/Module Name]
## Intent
[Why does this code exist? What problem does it solve? What business need does it address?]
## Scope
In scope:
- [What functionality is covered]
- [What use cases are supported]
Out of scope:
- [What is explicitly not handled]
- [Future considerations]
## Approach
[High-level technical approach taken]
## Success Criteria
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
## Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk description] | Low/Medium/High | Low/Medium/High | [How to mitigate] |
## Dependencies
- [External dependency 1]
- [Internal dependency 2]
## Timeline Estimate
- [Estimated effort or complexity]
The spec captures requirements and scenarios using Given/When/Then format.
# [Domain] Specification
## Purpose
[High-level description of this spec's domain]
## Requirements
### Requirement: [Requirement Name]
The system SHALL/MUST/SHOULD [behavior description].
**Rationale**: [Why this requirement exists]
#### Scenario: [Happy Path Scenario]
- GIVEN [initial context/preconditions]
- WHEN [action/trigger]
- THEN [expected outcome]
- AND [additional assertions]
#### Scenario: [Edge Case Scenario]
- GIVEN [edge case context]
- WHEN [action/trigger]
- THEN [expected behavior]
#### Scenario: [Error Scenario]
- GIVEN [error-prone context]
- WHEN [invalid action]
- THEN [error handling behavior]
### Requirement: [Another Requirement]
[Continue pattern...]
## Constraints
- [Technical constraint]
- [Business constraint]
- [Security/privacy constraint]
## Assumptions
- [Assumption made]
- [Another assumption]
## Out of Scope
- [Explicitly excluded functionality]
Use these keywords to indicate requirement strength:
| Keyword | Meaning | Usage |
|---|---|---|
| MUST / SHALL | Absolute requirement | Critical functionality |
| MUST NOT | Absolute prohibition | Security/safety constraints |
| SHOULD | Recommended but exceptions exist | Best practices |
| SHOULD NOT | Not recommended | Anti-patterns to avoid |
| MAY | Optional | Nice-to-have features |
The design document captures the technical approach and implementation details.
# Design: [Feature/Module Name]
## Overview
[High-level technical summary]
## Architecture
### Component Diagram
[ASCII or description of component relationships]
### Data Flow
[ASCII or description of data movement]
## Technical Decisions
### Decision 1: [Decision Title]
**Context**: [What situation necessitated this decision]
**Options Considered**:
1. [Option A] - [Pros/Cons]
2. [Option B] - [Pros/Cons]
**Decision**: [Chosen option]
**Rationale**: [Why this option was chosen]
### Decision 2: [Another Decision]
[Continue pattern...]
## Implementation Details
### [Module/Component 1]
- **Purpose**: [What it does]
- **Key Functions**:
- `functionName()`: [Description]
- `anotherFunction()`: [Description]
- **State Management**: [How state is handled]
- **Error Handling**: [How errors are handled]
### [Module/Component 2]
[Continue pattern...]
## Data Models
### [Model Name]
[Schema or structure definition]
## API Contracts
### [Endpoint/Function Name]
- **Input**: [Parameters and types]
- **Output**: [Return type and structure]
- **Errors**: [Possible error conditions]
## Security Considerations
- [Security measure 1]
- [Security measure 2]
## Performance Considerations
- [Performance optimization 1]
- [Performance optimization 2]
## Testing Strategy
- **Unit Tests**: [What is unit tested]
- **Integration Tests**: [What is integration tested]
- **Edge Cases**: [Special scenarios to test]
## Trade-offs
| Trade-off | Chosen | Alternative | Reason |
|-----------|--------|-------------|--------|
| [Trade-off description] | [Choice] | [Alternative] | [Reasoning] |
The tasks document provides an implementation checklist broken down into manageable pieces.
Important: When reverse-engineering from existing code, you MUST check the input context to determine if each task has
already been implemented. Mark tasks as done ([x]) when the implementation satisfies the task requirements, and leave them as
incomplete ([ ]) only for missing or partial implementations.
For each identified task, verify against the input code:
[x] for fully implemented tasks[ ] for not implemented or partial implementations[~] for partially implemented (optional, with note on what's missing)# Tasks: [Feature/Module Name]
## Overview
[Summary of the work to be done]
**Implementation Status**: [Summary of what's already done vs. what remains]
## Task Breakdown
### Phase 1: [Phase Name]
**Estimated Effort**: [Time/Complexity]
- [x] **1.1** [Task description] ✅ Already implemented
- **Details**: [Additional context]
- **Acceptance**: [How to verify completion]
- **Dependencies**: [Any prerequisite tasks]
- **Implementation Note**: [Brief note on how it's implemented in the code]
- [ ] **1.2** [Task description] ❌ Not implemented
- **Details**: [Additional context]
- **Acceptance**: [How to verify completion]
- **Dependencies**: [Any prerequisite tasks]
- **Gap Analysis**: [What's missing from the implementation]
- [~] **1.3** [Task description] ⚠️ Partially implemented
- **Details**: [Additional context]
- **Acceptance**: [How to verify completion]
- **Dependencies**: [Any prerequisite tasks]
- **Missing Parts**: [What still needs to be done]
### Phase 2: [Phase Name]
**Estimated Effort**: [Time/Complexity]
- [x] **2.1** [Task description] ✅ Already implemented
- **Details**: [Additional context]
- **Acceptance**: [How to verify completion]
- **Dependencies**: [Any prerequisite tasks]
- [ ] **2.2** [Task description] ❌ Not implemented
- **Details**: [Additional context]
- **Acceptance**: [How to verify completion]
- **Dependencies**: [Any prerequisite tasks]
### Phase 3: Testing & Validation
**Estimated Effort**: [Time/Complexity]
- [x] **3.1** Write unit tests for [component] ✅ Tests exist
- **Coverage Target**: [Percentage or specific cases]
- **Dependencies**: [Prerequisite tasks]
- **Test Files**: [List existing test files if found]
- [ ] **3.2** Write integration tests for [feature] ❌ No tests found
- **Scenarios**: [Key scenarios to test]
- **Dependencies**: [Prerequisite tasks]
- [ ] **3.3** Perform edge case testing
- **Edge Cases**: [List edge cases]
- **Dependencies**: [Prerequisite tasks]
### Phase 4: Documentation & Cleanup
**Estimated Effort**: [Time/Complexity]
- [x] **4.1** Update API documentation ✅ Documented
- [ ] **4.2** Update README if needed
- [ ] **4.3** Code review and refactoring
## Task Dependencies
[ASCII diagram showing task dependencies]
## Implementation Status Summary
| Status | Count | Percentage |
|--------|-------|------------|
| ✅ Complete | [X] | [X]% |
| ⚠️ Partial | [X] | [X]% |
| ❌ Not Started | [X] | [X]% |
## Notes
- [Any additional notes or context]
- [Link to related resources]
Input Code:
function validateEmail(email) {
if (!email || typeof email !== 'string') {
return {valid : false, error : 'Email is required'};
}
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
if (!emailRegex.test(email)) {
return {valid : false, error : 'Invalid email format'};
}
if (email.length > 254) {
return {valid : false, error : 'Email exceeds maximum length'};
}
return {valid : true};
}
Expected Output: Generate all four documents capturing:
# Tasks: Email Validation
## Overview
Email validation functionality implementation.
**Implementation Status**: All core functionality implemented. No tests found.
## Task Breakdown
### Phase 1: Core Implementation
**Estimated Effort**: Low
- [x] **1.1** Implement null/undefined check ✅ Already implemented
- **Details**: Check if email is null, undefined, or not a string
- **Acceptance**: Returns error object for invalid inputs
- **Implementation Note**: `if (!email || typeof email !== 'string')` handles this
- [x] **1.2** Implement email format validation ✅ Already implemented
- **Details**: Validate email against regex pattern
- **Acceptance**: Returns error for invalid format
- **Implementation Note**: Uses regex `/^[^\s@]+@[^\s@]+\.[^\s@]+$/`
- [x] **1.3** Implement length validation ✅ Already implemented
- **Details**: Check email doesn't exceed 254 characters
- **Acceptance**: Returns error for oversized emails
- **Implementation Note**: `if (email.length > 254)` check exists
### Phase 2: Testing & Validation
**Estimated Effort**: Medium
- [ ] **2.1** Write unit tests for validateEmail ❌ No tests found
- **Coverage Target**: 100% branch coverage
- **Test Cases Needed**:
- Valid email format
- Null/undefined input
- Non-string input
- Invalid format (no @, no domain, etc.)
- Max length boundary
## Implementation Status Summary
| Status | Count | Percentage |
|--------|-------|------------|
| ✅ Complete | 3 | 75% |
| ❌ Not Started | 1 | 25% |
Input Code:
function UserProfile({userId}) {
const [user, setUser] = useState(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
useEffect(() => {
async function fetchUser() {
try {
const response = await api.getUser(userId);
setUser(response.data);
} catch (err) {
setError(err.message);
} finally {
setLoading(false);
}
}
fetchUser();
}, [userId]);
if (loading) return <Spinner />;
if (error) return <ErrorMessage error={error} />;
return <UserCard user={user} />;
}
Expected Output: Generate documents capturing:
# Tasks: UserProfile Component
## Overview
User profile display component with data fetching and state management.
**Implementation Status**: Core component implemented. Testing and accessibility incomplete.
## Task Breakdown
### Phase 1: Component Structure
**Estimated Effort**: Low
- [x] **1.1** Set up component with props interface ✅ Already implemented
- **Acceptance**: Component accepts userId prop
- **Implementation Note**: `function UserProfile({userId})`
- [x] **1.2** Implement state management ✅ Already implemented
- **Details**: user, loading, error states
- **Implementation Note**: Uses `useState` for all three states
### Phase 2: Data Fetching
**Estimated Effort**: Medium
- [x] **2.1** Implement API integration ✅ Already implemented
- **Acceptance**: Fetches user data from API
- **Implementation Note**: `api.getUser(userId)` in useEffect
- [x] **2.2** Handle loading state ✅ Already implemented
- **Implementation Note**: `if (loading) return <Spinner />`
- [x] **2.3** Handle error state ✅ Already implemented
- **Implementation Note**: `if (error) return <ErrorMessage error={error} />`
- [x] **2.4** Implement userId dependency tracking ✅ Already implemented
- **Implementation Note**: `useEffect(..., [userId])`
### Phase 3: Testing
**Estimated Effort**: Medium
- [ ] **3.1** Write unit tests ❌ No tests found
- **Test Cases Needed**:
- Renders loading state initially
- Renders user card on success
- Renders error message on failure
- Re-fetches when userId changes
- [ ] **3.2** Write integration tests ❌ No tests found
- **Scenarios**: API interaction, state transitions
### Phase 4: Accessibility & Polish
**Estimated Effort**: Low
- [~] **4.1** Add accessibility attributes ⚠️ Partially implemented
- **Missing Parts**: ARIA labels, role attributes for loading/error states
- [ ] **4.2** Add error boundary handling ❌ Not implemented
## Implementation Status Summary
| Status | Count | Percentage |
|--------|-------|------------|
| ✅ Complete | 6 | 67% |
| ⚠️ Partial | 1 | 11% |
| ❌ Not Started | 3 | 22% |
When generating tasks.md from existing code:
[x] only when the code fully satisfies the task requirements[~] for partial implementations with details on what's missingVerification Checklist:
proposal.md ──────► specs.md ──────► design.md ──────► tasks.md
│ │ │ │
intent what how steps
+ scope + scenarios + decisions + checklist
Each document builds on the previous: