openspec-proposal-creation

Specification Proposal Creation

Creates comprehensive change proposals following spec-driven development methodology.

Quick Start

Creating a spec proposal involves three main outputs:

1. proposal.md - Why, what, and impact summary
2. tasks.md - Numbered implementation checklist
3. spec-delta.md - Formal requirement changes (ADDED/MODIFIED/REMOVED)

Basic workflow: Generate change ID → scaffold directories → draft proposal → create spec deltas → validate structure

Workflow

Copy this checklist and track progress:

Proposal Progress:
- [ ] Step 1: Review existing specifications
- [ ] Step 2: Generate unique change ID
- [ ] Step 3: Scaffold directory structure
- [ ] Step 4: Draft proposal.md (Why/What/Impact)
- [ ] Step 5: Create tasks.md implementation checklist
- [ ] Step 6: Write spec deltas with EARS format
- [ ] Step 7: Validate proposal structure
- [ ] Step 8: Present for user approval

Step 1: Review existing specifications

Before creating a proposal, understand the current state:

# List all existing specs

Step 2: Generate unique change ID

Choose a descriptive, URL-safe identifier:

Format: add-<feature>, fix-<issue>, update-<component>, remove-<feature>

Examples:

• add-user-authentication
• fix-payment-validation
• update-api-rate-limits
• remove-legacy-endpoints

Validation: Check for conflicts:

Step 3: Scaffold directory structure

Create the change folder with standard structure:

Example:

Step 4: Draft proposal.md

Use the template at templates/proposal.md as starting point.

Required sections:

• Why: Problem or opportunity driving this change
• What Changes: Bullet list of modifications
• Impact: Affected specs, code, APIs, users

Tone: Clear, concise, decision-focused. Avoid unnecessary background.

Step 5: Create tasks.md implementation checklist

Break implementation into concrete, testable tasks. Use the template at templates/tasks.md.

Format:

Best practices:

• Each task is independently completable
• Include testing and validation tasks
• Order by dependencies (database before API, etc.)
• 5-15 tasks is typical; split if more needed

Step 6: Write spec deltas with EARS format

This is the most critical step. Spec deltas use EARS format (Easy Approach to Requirements Syntax).

For complete EARS guidelines, see reference/EARS_FORMAT.md

Delta operations:

• ## ADDED Requirements - New capabilities
• ## MODIFIED Requirements - Changed behavior (include full updated text)
• ## REMOVED Requirements - Deprecated features

Basic requirement structure:

For validation patterns, see reference/VALIDATION_PATTERNS.md

Step 7: Validate proposal structure

Run these checks before presenting to user:

Automated checks:

Step 8: Present for user approval

Summarize the proposal clearly:

Advanced Topics

EARS format details: See reference/EARS_FORMAT.md Validation patterns: See reference/VALIDATION_PATTERNS.md Complete examples: See reference/EXAMPLES.md

Common Patterns

Pattern 1: New feature proposal

When adding net-new capability:

• Use ADDED Requirements delta
• Include positive scenarios AND error handling
• Consider edge cases in scenarios

Pattern 2: Breaking change proposal

When changing existing behavior:

• Use MODIFIED Requirements delta
• Include complete updated requirement text
• Document what changes and why in proposal.md
• Consider migration tasks in tasks.md

Pattern 3: Deprecation proposal

When removing features:

• Use REMOVED Requirements delta
• Document removal rationale in proposal.md
• Include cleanup tasks in tasks.md
• Consider user migration in impact section

Anti-Patterns to Avoid

Don't:

• Skip validation checks (always run grep patterns)
• Create proposals without reviewing existing specs first
• Use vague task descriptions ("Fix the thing")
• Write requirements without scenarios
• Forget error handling scenarios
• Mix multiple unrelated changes in one proposal

Do:

• Check for conflicts before creating change ID
• Write concrete, testable tasks
• Include positive AND negative scenarios
• Keep one concern per proposal
• Validate structure before presenting

File Templates

All templates are in the templates/ directory:

• proposal.md - Proposal structure
• tasks.md - Task checklist format
• spec-delta.md - Spec delta template

Reference Materials

• EARS_FORMAT.md - Complete EARS syntax guide
• VALIDATION_PATTERNS.md - Grep/bash validation
• EXAMPLES.md - Real-world proposal examples

Token budget: This SKILL.md is approximately 450 lines, under the 500-line recommended limit. Reference files load only when needed for progressive disclosure.