Initial commit

skills/managing-specifications/LIFECYCLE.md

@@ -0,0 +1,602 @@
+# Specification Lifecycle Management
+
+This file provides complete details for managing specifications through their lifecycle. Only load when user needs management operations beyond basic "show status" or "activate spec".
+
+## When to Load This File
+
+- User asks about lifecycle details: "How do I move specs?", "What are the rules?"
+- User wants batch operations: "Show all high priority specs"
+- User needs validation info: "Why can't I activate this spec?"
+- User wants progress tracking details: "How is progress calculated?"
+
+## The Folder-Based Lifecycle
+
+Specifications move through three folders representing their state:
+
+```
+.quaestor/specs/
+├── draft/              # New specs, not started (unlimited)
+│   └── spec-*.md
+├── active/             # Work in progress (MAX 3 enforced)
+│   └── spec-*.md
+└── completed/          # Finished work (archived, unlimited)
+    └── spec-*.md
+```
+
+**Core principle**: The folder IS the state. No separate tracking database needed.
+
+## State Transitions
+
+```
+draft/ → active/ → completed/
+  ↑         ↓
+  └─────────┘
+  (can move back to draft if needed)
+```
+
+### Draft → Active (Activation)
+
+**When**: User starts working on a specification
+
+**Command**: "activate spec-feature-001" or "start working on spec-feature-001"
+
+**Process**:
+1. Check: Is spec in draft/ folder?
+2. Check: Are there < 3 specs in active/?
+3. Move file: `draft/spec-*.md` → `active/`
+4. Update frontmatter: `status: draft` → `status: active`
+5. Add timestamp: `updated_at: [current time]`
+6. Report success
+
+**Active Limit Enforcement**:
+```yaml
+limit: 3 active specifications maximum
+
+if_limit_reached:
+  action: Block activation
+  message: |
+    ❌ Cannot activate - 3 specifications already active:
+      - spec-feature-001 (80% complete)
+      - spec-feature-002 (40% complete)
+      - spec-bugfix-001 (95% complete)
+
+    💡 Suggestion: Complete spec-bugfix-001 first (almost done!)
+
+user_options:
+  - Complete an active spec
+  - Move an active spec back to draft
+  - Choose which active spec to pause
+```
+
+### Active → Completed (Completion)
+
+**When**: All acceptance criteria are checked off
+
+**Command**: "complete spec-feature-001" or "mark spec-feature-001 as done"
+
+**Validation Before Completion**:
+```yaml
+required_checks:
+  - spec_in_active_folder: true
+  - all_criteria_checked: true  # All [ ] became [x]
+  - status_field: "active"
+
+optional_warnings:
+  - no_test_scenarios: "⚠️ No test scenarios documented"
+  - no_branch_linked: "⚠️ No branch linked to spec"
+  - estimated_hours_missing: "⚠️ No time estimate"
+```
+
+**Process**:
+1. Verify: All checkboxes marked `[x]`
+2. Verify: Spec is in active/ folder
+3. Move file: `active/spec-*.md` → `completed/`
+4. Update frontmatter: `status: active` → `status: completed`
+5. Add completion timestamp: `updated_at: [current time]`
+6. Report success + suggest PR creation
+
+**If Incomplete**:
+```
+❌ Cannot complete spec-feature-001
+
+Progress: 3/5 criteria complete (60%)
+
+⏳ Remaining:
+- [ ] User can reset password via email
+- [ ] Session timeout after 24 hours
+
+Mark these complete or continue implementation with /impl spec-feature-001
+```
+
+### Completed → Draft (Reopening)
+
+**When**: Need to reopen completed work (rare)
+
+**Command**: "reopen spec-feature-001" or "move spec-feature-001 back to draft"
+
+**Process**:
+1. Move file: `completed/spec-*.md` → `draft/`
+2. Update frontmatter: `status: completed` → `status: draft`
+3. Uncheck acceptance criteria (reset to `[ ]`)
+4. Add note about why reopened
+
+### Active → Draft (Pausing)
+
+**When**: Need to pause work temporarily
+
+**Command**: "pause spec-feature-001" or "move spec-feature-001 to draft"
+
+**Process**:
+1. Move file: `active/spec-*.md` → `draft/`
+2. Update frontmatter: `status: active` → `status: draft`
+3. Preserve progress (don't uncheck criteria)
+4. Add note about why paused
+
+## Progress Tracking
+
+### Calculation Method
+
+Progress is calculated by parsing checkbox completion:
+
+```markdown
+## Acceptance Criteria
+- [x] User can login with email and password  ✓ Complete
+- [x] Invalid credentials show error message   ✓ Complete
+- [x] Sessions persist across browser restarts ✓ Complete
+- [ ] User can logout and clear session        ✗ Incomplete
+- [ ] Password reset via email                 ✗ Incomplete
+
+Progress: 3/5 = 60%
+```
+
+**Algorithm**:
+```python
+def calculate_progress(spec_content):
+    total = count_all_checkboxes(spec_content)
+    completed = count_checked_boxes(spec_content)  # [x]
+    percentage = (completed / total) * 100
+    return {
+        'total': total,
+        'completed': completed,
+        'percentage': percentage
+    }
+```
+
+**What counts as a checkbox**:
+- `- [ ]` or `- [x]` in acceptance criteria section
+- `- [ ]` or `- [x]` in test scenarios (optional)
+- Checkboxes in other sections (optional)
+
+### Progress Visualization
+
+```
+📊 spec-feature-001: User Authentication
+Progress: [████████░░] 80%
+
+✅ Completed (4):
+- User can login with email and password
+- Invalid credentials show error message
+- Sessions persist across browser restarts
+- User can logout and clear session
+
+⏳ Remaining (1):
+- Password reset via email
+
+Last updated: 2 hours ago
+Branch: feat/user-authentication
+```
+
+## Status Dashboard
+
+### Basic Status Check
+
+**Command**: "show spec status" or "what's my spec status?"
+
+**Output**:
+```
+📊 Specification Status
+
+📁 Draft: 5 specifications
+  - spec-feature-003: User Profile Management [high]
+  - spec-feature-004: API Rate Limiting [medium]
+  - spec-bugfix-002: Fix memory leak [critical]
+  - spec-refactor-001: Simplify auth logic [medium]
+  - spec-docs-001: API documentation [low]
+
+📋 Active: 2/3 slots used
+  - spec-feature-001: User Authentication [████████░░] 80%
+    Branch: feat/user-authentication
+
+  - spec-feature-002: Email Notifications [████░░░░░░] 40%
+    Branch: feat/email-notifications
+
+✅ Completed: 12 specifications
+  - Last completed: spec-bugfix-001 (2 days ago)
+
+💡 You can activate 1 more specification
+```
+
+### Detailed Status for Single Spec
+
+**Command**: "status of spec-feature-001" or "show me spec-feature-001 progress"
+
+**Output**:
+```
+📊 spec-feature-001: User Authentication
+
+Status: Active
+Progress: [████████░░] 80% (4/5 criteria)
+Priority: High
+Branch: feat/user-authentication
+Created: 3 days ago
+Updated: 2 hours ago
+
+✅ Completed:
+- User can login with email and password
+- Invalid credentials show error message
+- Sessions persist across browser restarts
+- User can logout and clear session
+
+⏳ Remaining:
+- Password reset via email
+
+Next steps:
+- Continue implementation: /impl spec-feature-001
+- Mark complete when done: "complete spec-feature-001"
+```
+
+## Batch Operations
+
+### Filter by Type
+
+**Command**: "show all feature specs" or "list bugfix specs"
+
+```bash
+# Search across all folders
+grep -l "type: feature" .quaestor/specs/**/*.md
+```
+
+**Output**:
+```
+📂 Feature Specifications (8 total)
+
+Draft (4):
+- spec-feature-003: User Profile Management
+- spec-feature-004: API Rate Limiting
+- spec-feature-005: Search functionality
+- spec-feature-006: Export to CSV
+
+Active (2):
+- spec-feature-001: User Authentication [80%]
+- spec-feature-002: Email Notifications [40%]
+
+Completed (2):
+- spec-feature-000: Initial setup
+- spec-feature-007: Login page
+```
+
+### Filter by Priority
+
+**Command**: "show high priority specs" or "what critical specs do we have?"
+
+```bash
+grep -l "priority: critical" .quaestor/specs/**/*.md
+```
+
+**Output**:
+```
+🚨 Critical Priority Specifications
+
+Draft:
+- spec-bugfix-002: Fix memory leak [Not started]
+
+Active:
+- None
+
+💡 Consider activating spec-bugfix-002 (critical priority)
+```
+
+### Check Dependencies
+
+**Command**: "what specs are blocked?" or "show spec dependencies"
+
+**Output**:
+```
+📊 Specification Dependencies
+
+Blocked (waiting on other specs):
+- spec-feature-003 (Requires: spec-feature-001)
+- spec-feature-005 (Requires: spec-feature-002, spec-feature-003)
+
+Blocking others:
+- spec-feature-001 (Blocks: spec-feature-003, spec-refactor-001)
+
+Ready to start (no dependencies):
+- spec-feature-004
+- spec-bugfix-002
+- spec-docs-001
+```
+
+## Metadata Management
+
+### Update Priority
+
+**Command**: "set spec-feature-001 priority to critical"
+
+**Process**:
+1. Read spec file
+2. Update frontmatter: `priority: medium` → `priority: critical`
+3. Update timestamp
+4. Save file
+
+### Link to Branch
+
+**Command**: "link spec-feature-001 to feat/user-auth"
+
+**Process**:
+1. Read spec file
+2. Add/update metadata: `branch: feat/user-auth`
+3. Update timestamp
+4. Save file
+
+### Add Technical Notes
+
+**Command**: "add note to spec-feature-001: using JWT for tokens"
+
+**Process**:
+1. Read spec file
+2. Append to metadata section or create notes field
+3. Update timestamp
+4. Save file
+
+## Validation Rules
+
+### Before Activation
+
+```yaml
+checks:
+  valid_frontmatter:
+    - id field exists and is unique
+    - type is valid (feature|bugfix|refactor|etc)
+    - priority is set
+    - timestamps present
+
+  content_quality:
+    - title is not empty
+    - description has content
+    - rationale provided
+    - at least 1 acceptance criterion
+
+  warnings:
+    - no test scenarios (⚠️ warn but allow)
+    - estimated_hours missing (⚠️ warn but allow)
+```
+
+### Before Completion
+
+```yaml
+checks:
+  required:
+    - all checkboxes marked [x]
+    - spec is in active/ folder
+    - status field is "active"
+
+  warnings:
+    - no branch linked (⚠️ warn but allow)
+    - no test scenarios (⚠️ warn but allow)
+    - estimated_hours vs actual time
+```
+
+## Error Handling
+
+### Spec Not Found
+
+```
+❌ Specification 'spec-feature-999' not found
+
+Searched in:
+  - .quaestor/specs/draft/
+  - .quaestor/specs/active/
+  - .quaestor/specs/completed/
+
+💡 Run "show draft specs" to see available specifications
+```
+
+### Active Limit Reached
+
+```
+❌ Cannot activate - already at maximum (3 active specs)
+
+Active specs:
+  1. spec-feature-001 (80% complete - almost done!)
+  2. spec-feature-002 (40% complete)
+  3. spec-refactor-001 (10% complete - just started)
+
+Options:
+  - Complete spec-feature-001 (almost finished)
+  - Pause spec-refactor-001 (just started)
+  - Continue with one of the active specs
+
+💡 The 3-spec limit encourages finishing work before starting new features
+```
+
+### Incomplete Spec
+
+```
+❌ Cannot complete spec-feature-001
+
+Progress: 3/5 criteria (60%)
+
+Missing:
+  - [ ] User can reset password via email
+  - [ ] Session timeout after 24 hours
+
+Options:
+  - Continue implementation: /impl spec-feature-001
+  - Mark these criteria complete manually
+  - Split into new spec: "create spec for password reset"
+
+💡 All acceptance criteria must be checked before completion
+```
+
+## Git Integration
+
+### Stage Spec Changes
+
+When moving specs, stage the changes for commit:
+
+```bash
+# Stage all spec folder changes
+git add .quaestor/specs/draft/
+git add .quaestor/specs/active/
+git add .quaestor/specs/completed/
+
+# Commit with descriptive message
+git commit -m "chore: activate spec-feature-001"
+git commit -m "chore: complete spec-feature-001 - user authentication"
+```
+
+### Commit Message Patterns
+
+```yaml
+activation:
+  format: "chore: activate [spec-id]"
+  example: "chore: activate spec-feature-003"
+
+completion:
+  format: "chore: complete [spec-id] - [brief title]"
+  example: "chore: complete spec-feature-001 - user authentication"
+
+batch_update:
+  format: "chore: update spec statuses"
+  example: "chore: update spec statuses (2 completed, 1 activated)"
+```
+
+## Progress History
+
+### Track Updates
+
+**Command**: "when was spec-feature-001 last updated?"
+
+```bash
+# Read frontmatter
+grep "updated_at:" .quaestor/specs/active/spec-feature-001.md
+```
+
+**Output**:
+```
+spec-feature-001 last updated: 2025-01-19T14:30:00 (2 hours ago)
+```
+
+### Show Velocity
+
+**Command**: "how many specs completed this week?"
+
+```bash
+# Check completed folder, filter by completion timestamp
+find .quaestor/specs/completed/ -name "*.md" -mtime -7
+```
+
+**Output**:
+```
+📊 Velocity Report (Last 7 Days)
+
+Completed: 3 specifications
+  - spec-feature-007: Login page (2 days ago)
+  - spec-bugfix-001: Memory leak fix (4 days ago)
+  - spec-docs-002: API docs update (6 days ago)
+
+Average: 0.43 specs/day
+Weekly rate: 3 specs/week
+```
+
+## Advanced Operations
+
+### Bulk Priority Update
+
+**Command**: "set all draft bugfix specs to high priority"
+
+**Process**:
+1. Find all draft specs with `type: bugfix`
+2. Update each: `priority: medium` → `priority: high`
+3. Report changes
+
+### Archive Old Completed Specs
+
+**Command**: "archive specs completed > 90 days ago"
+
+```bash
+# Create archive folder
+mkdir -p .quaestor/specs/archived/
+
+# Move old completed specs
+find .quaestor/specs/completed/ -name "*.md" -mtime +90 \
+  -exec mv {} .quaestor/specs/archived/ \;
+```
+
+### Generate Status Report
+
+**Command**: "generate spec status report"
+
+**Output**: Markdown file with:
+- Current active specs and progress
+- Draft specs by priority
+- Recently completed specs
+- Velocity metrics
+- Blocked specs
+
+## Best Practices
+
+### Keep Active Limit Low
+
+The 3-spec limit is intentional:
+- ✅ Forces focus on completion
+- ✅ Reduces context switching
+- ✅ Makes priorities clear
+- ✅ Encourages finishing work
+
+### Link Specs to Branches
+
+When starting work:
+```yaml
+# In spec frontmatter
+branch: feat/user-authentication
+```
+
+Benefits:
+- Easy to find related code
+- Track implementation progress
+- Connect commits to specs
+
+### Update Progress Regularly
+
+Check off criteria as you complete them:
+```markdown
+- [x] User can login  ← Mark done immediately
+- [ ] User can logout ← Next to work on
+```
+
+Benefits:
+- Accurate progress tracking
+- Visibility into what's left
+- Motivation from seeing progress
+
+### Use Priority Ruthlessly
+
+```yaml
+priority: critical  # Drop everything, do now
+priority: high      # Schedule this week
+priority: medium    # Normal priority
+priority: low       # Nice to have, do when time allows
+```
+
+### Review Draft Specs Weekly
+
+Prune specs that are no longer needed:
+- Requirements changed
+- Feature no longer wanted
+- Superseded by other work
+
+---
+
+*This guide provides complete lifecycle management details. Return to SKILL.md for overview or WRITING.md for spec creation guidance.*

skills/managing-specifications/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: Managing Specifications
+description: Create, manage, and track specifications through their full lifecycle from draft to completion. Use when user wants to plan features, create specs, check progress, activate work, or complete specifications.
+allowed-tools: [Write, Read, Edit, Bash, Glob, Grep]
+---
+
+# Managing Specifications
+
+I help you work with specifications: creating new specs from requirements, managing their lifecycle (draft → active → completed), and tracking progress automatically.
+
+## When to Use Me
+
+**Auto-activate when:**
+- Invoked via `/quaestor:plan` slash command
+- User describes a feature with details: "I want to add user authentication with JWT tokens"
+- User explicitly requests spec creation: "Create a spec for X", "Write a specification for Y"
+- User asks about spec status: "What specs are active?", "Show spec progress"
+- User wants to activate work: "Start working on spec-feature-001"
+- User wants to complete: "Mark spec-feature-001 as done"
+- User checks progress: "How's the authentication feature going?"
+
+**Do NOT auto-activate when:**
+- User says only "plan" or "plan it" (slash command handles this)
+- User is making general requests without specification context
+- Request needs more clarification before creating a spec
+
+## Quick Start
+
+**New to specs?** Just describe what you want to build:
+```
+"I want to add email notifications when orders are placed"
+```
+
+I'll ask a few questions, then create a complete specification for you.
+
+**Have specs already?** Tell me what you need:
+```
+"Show me my active specs"
+"Activate spec-feature-003"
+"What's the progress on spec-auth-001?"
+```
+
+## How I Work
+
+I detect what you need and adapt automatically:
+
+### Mode 1: Creating Specifications
+
+When you describe a feature or ask me to create a spec, I:
+1. Ask clarifying questions (if needed)
+2. Generate a unique spec ID (e.g., `spec-feature-001`)
+3. Create `.quaestor/specs/draft/[spec-id].md`
+4. Report next steps
+
+**See @WRITING.md for the complete specification template and writing process**
+
+### Mode 2: Managing Lifecycle
+
+When you ask about spec status or want to move specs, I:
+1. Check current state (scan all folders)
+2. Perform the requested action (activate, complete, show status)
+3. Update spec metadata automatically
+4. Report changes
+
+**See @LIFECYCLE.md for folder-based lifecycle management and progress tracking**
+
+## The 3-Folder System
+
+Specifications live in folders that represent their state:
+
+```
+.quaestor/specs/
+├── draft/              # New specs (unlimited)
+├── active/             # Work in progress (MAX 3)
+└── completed/          # Finished work (archived)
+```
+
+**The folder IS the state** - no complex tracking needed!
+
+**Why max 3 active?** Forces focus on finishing work before starting new features.
+
+## Progressive Workflows
+
+I provide just enough information for your current task, with details available when needed:
+
+### Creating Your First Spec
+
+**Minimal workflow** (I guide you):
+```
+You: "Add user authentication"
+Me: I'll ask 3-5 questions
+Me: Create spec-feature-001.md in draft/
+```
+
+### Managing Existing Specs
+
+**Common operations**:
+- `"Show active specs"` → List with progress bars
+- `"Activate spec-feature-003"` → Move draft/ → active/
+- `"Complete spec-auth-001"` → Move active/ → completed/
+
+### Deep Dive Available
+
+When you need more details:
+- **@WRITING.md** - Complete template, field descriptions, examples
+- **@LIFECYCLE.md** - All lifecycle operations, validation rules, batch operations
+- **@TEMPLATE.md** - Field-by-field guide to spec structure
+
+## Key Features
+
+### Smart Spec Creation
+✅ Auto-generate unique IDs
+✅ Forgiving template (auto-corrects common mistakes)
+✅ No placeholders - only real values
+✅ Rich metadata (priority, type, timestamps)
+
+### Automatic Lifecycle Management
+✅ Folder-based states (simple and visual)
+✅ 3-active-spec limit (enforced automatically)
+✅ Progress calculation from checkboxes
+✅ Metadata updates on state changes
+
+### Progress Tracking
+✅ Parse checkbox completion: `- [x]` vs `- [ ]`
+✅ Calculate percentage: 4/5 complete = 80%
+✅ Visual progress bars
+✅ Branch linking support
+
+## Success Criteria
+
+**Creating specs:**
+- ✅ Spec has unique ID and proper frontmatter
+- ✅ All fields have actual values (no placeholders)
+- ✅ Acceptance criteria defined with checkboxes
+- ✅ Saved to `.quaestor/specs/draft/[spec-id].md`
+
+**Managing specs:**
+- ✅ State transitions work correctly (draft → active → completed)
+- ✅ 3-active limit enforced
+- ✅ Progress calculated accurately from checkboxes
+- ✅ Metadata updates automatically
+
+## Next Steps After Using This Skill
+
+Once you have specifications:
+1. **Activate a spec**: "Activate spec-feature-001"
+2. **Implement it**: Use `/impl spec-feature-001` or implementing-features skill
+3. **Track progress**: "What's the status?" or "Show active specs"
+4. **Complete it**: "Complete spec-feature-001" when all criteria checked
+5. **Ship it**: Use reviewing-and-shipping skill to create PR
+
+---
+
+*I handle both creation and management of specifications. Just tell me what you need - I'll detect the mode and guide you through it with minimal upfront context.*

skills/managing-specifications/TEMPLATE.md

@@ -0,0 +1,697 @@
+# Specification Template Reference
+
+This file provides a field-by-field reference for the specification template. Only load when user asks specific questions about template structure or field meanings.
+
+## When to Load This File
+
+- User asks: "What does the rationale field mean?"
+- User wants field examples: "Show me examples of good acceptance criteria"
+- User is confused about a specific section
+- User wants to understand optional vs required fields
+
+## Complete Template Structure
+
+```markdown
+---
+# FRONTMATTER (YAML metadata)
+id: spec-TYPE-NNN                    # Required: Unique identifier
+type: feature                        # Required: Category of work
+status: draft                        # Required: Current state
+priority: medium                     # Required: Urgency level
+created_at: 2025-01-19T10:00:00     # Required: Creation timestamp
+updated_at: 2025-01-19T10:00:00     # Required: Last modified timestamp
+---
+
+# Title                              # Required: Clear, descriptive name
+
+## Description                       # Required: What needs to be done
+What exactly needs to be implemented, fixed, or changed.
+Be specific about functionality, scope, and affected components.
+
+## Rationale                         # Required: Why this matters
+Business value, technical benefit, or problem being solved.
+Explain the impact if this is not done.
+
+## Dependencies                      # Optional: Related specifications
+- **Requires**: spec-001            # Must be done before this
+- **Blocks**: spec-003              # This blocks other work
+- **Related**: spec-004             # Context, not blocking
+
+## Risks                             # Optional: Potential issues
+- Technical risks
+- Schedule risks
+- Dependency risks
+
+## Success Metrics                   # Optional: Measurable outcomes
+- Performance targets
+- Usage metrics
+- Quality metrics
+
+## Acceptance Criteria               # Required: How to know it's done
+- [ ] Specific, testable criterion
+- [ ] Another specific criterion
+- [ ] Include error cases
+- [ ] Minimum 3 criteria recommended
+
+## Test Scenarios                    # Required: How to verify
+
+### Happy path test                  # At least one success case
+**Given**: Initial state
+**When**: Action taken
+**Then**: Expected result
+
+### Error case test                  # At least one failure case
+**Given**: Invalid input
+**When**: Action attempted
+**Then**: Appropriate error shown
+
+## Metadata                          # Optional: Additional info
+estimated_hours: 8
+technical_notes: Implementation notes
+branch: feat/feature-name           # Added when work starts
+```
+
+## Field Reference
+
+### Frontmatter Fields
+
+#### id (Required)
+**Format**: `spec-TYPE-NNN`
+
+**Purpose**: Unique identifier that never changes
+
+**Type Prefixes**:
+- `spec-feature-NNN` - New functionality
+- `spec-bugfix-NNN` - Fix broken behavior
+- `spec-refactor-NNN` - Improve code structure
+- `spec-perf-NNN` - Performance improvements
+- `spec-sec-NNN` - Security enhancements
+- `spec-test-NNN` - Test coverage
+- `spec-docs-NNN` - Documentation
+
+**Numbering**: Zero-padded 3 digits (001, 002, ..., 999)
+
+**Examples**:
+```yaml
+id: spec-feature-001
+id: spec-bugfix-023
+id: spec-refactor-005
+```
+
+**Rules**:
+- Generated automatically from type + next available number
+- Never changes once created
+- Must be unique across all specs
+
+---
+
+#### type (Required)
+**Values**: `feature | bugfix | refactor | documentation | performance | security | testing`
+
+**Purpose**: Categorize the work type
+
+**Descriptions**:
+```yaml
+feature:
+  description: "New functionality or capability"
+  examples:
+    - "User authentication system"
+    - "Export to PDF feature"
+    - "Real-time notifications"
+
+bugfix:
+  description: "Fix broken or incorrect behavior"
+  examples:
+    - "Fix memory leak in processor"
+    - "Correct calculation error"
+    - "Resolve null pointer exception"
+
+refactor:
+  description: "Improve code structure without changing behavior"
+  examples:
+    - "Consolidate authentication logic"
+    - "Simplify database queries"
+    - "Extract reusable components"
+
+documentation:
+  description: "Add or improve documentation"
+  examples:
+    - "API documentation"
+    - "Add code comments"
+    - "Update README"
+
+performance:
+  description: "Improve speed, efficiency, or resource usage"
+  examples:
+    - "Optimize database queries"
+    - "Implement caching"
+    - "Reduce memory usage"
+
+security:
+  description: "Security improvements or vulnerability fixes"
+  examples:
+    - "Add input validation"
+    - "Implement rate limiting"
+    - "Fix SQL injection vulnerability"
+
+testing:
+  description: "Add or improve test coverage"
+  examples:
+    - "Add unit tests for auth module"
+    - "Implement E2E tests"
+    - "Improve test coverage to 80%"
+```
+
+**Auto-Correction**: Parser auto-corrects common mistakes
+- "removal" → "refactor"
+- "fix" → "bugfix"
+- "test" → "testing"
+
+---
+
+#### status (Required, Auto-Managed)
+**Values**: `draft | active | completed`
+
+**Purpose**: Track current state (managed by folder location)
+
+**Note**: Folder location is source of truth, this field is kept in sync
+
+```yaml
+status: draft      # In .quaestor/specs/draft/
+status: active     # In .quaestor/specs/active/
+status: completed  # In .quaestor/specs/completed/
+```
+
+---
+
+#### priority (Required)
+**Values**: `critical | high | medium | low`
+
+**Purpose**: Indicate urgency and importance
+
+**Guidelines**:
+```yaml
+critical:
+  when: "Production down, security vulnerability, data loss risk"
+  sla: "Drop everything, fix immediately"
+  examples:
+    - "Production outage"
+    - "Security breach"
+    - "Data corruption"
+
+high:
+  when: "Important feature, significant bug, blocking other work"
+  sla: "Schedule this week"
+  examples:
+    - "Key customer feature"
+    - "Major bug affecting users"
+    - "Blocking other development"
+
+medium:
+  when: "Normal priority work, planned features, minor bugs"
+  sla: "Schedule in sprint"
+  examples:
+    - "Planned feature work"
+    - "Minor bug fixes"
+    - "Technical debt"
+
+low:
+  when: "Nice to have, minor improvements, future work"
+  sla: "Do when time allows"
+  examples:
+    - "Nice to have features"
+    - "Minor improvements"
+    - "Future enhancements"
+```
+
+---
+
+#### created_at / updated_at (Required, Auto)
+**Format**: ISO 8601 timestamp `YYYY-MM-DDTHH:MM:SS`
+
+**Purpose**: Track when spec was created and last modified
+
+**Examples**:
+```yaml
+created_at: 2025-01-19T10:30:00
+updated_at: 2025-01-19T14:45:00
+```
+
+**Auto-Management**:
+- `created_at`: Set once when spec is created
+- `updated_at`: Updated whenever spec content changes
+
+---
+
+### Content Sections
+
+#### Title (Required)
+**Location**: First H1 heading after frontmatter
+
+**Purpose**: Clear, descriptive name of the work
+
+**Guidelines**:
+```yaml
+do:
+  - Use clear, descriptive names
+  - Be specific about what's being done
+  - Include key context
+
+dont:
+  - Use vague terms: "Fix bug", "Update code"
+  - Use technical jargon without context
+  - Make it too long (> 80 chars)
+```
+
+**Examples**:
+```markdown
+# Good
+- User Authentication System with JWT Tokens
+- Fix Memory Leak in Background Job Processor
+- Refactor Payment Validation Logic
+- Optimize Database Query Performance
+
+# Bad
+- Auth
+- Fix Bug
+- Update Code
+- Make It Faster
+```
+
+---
+
+#### Description (Required)
+**Location**: `## Description` section
+
+**Purpose**: Detailed explanation of what needs to be done
+
+**What to Include**:
+- Specific functionality or changes
+- Scope and boundaries
+- Key components affected
+- Current state vs desired state
+
+**Example Structure**:
+```markdown
+## Description
+[Opening paragraph: What needs to be done]
+
+[Current state: How things work now]
+
+[Desired state: How things should work]
+
+[Scope: What's included and excluded]
+
+[Key components: What parts of system affected]
+```
+
+**Good Example**:
+```markdown
+## Description
+Implement a user authentication system with email/password login,
+JWT-based session management, and secure password storage using bcrypt.
+
+Current state: No authentication system exists. All endpoints are public.
+
+Desired state: Users must authenticate to access protected endpoints.
+Sessions persist for 24 hours with automatic renewal. Passwords are
+securely hashed and never stored in plain text.
+
+Scope includes:
+- Login/logout endpoints
+- JWT token generation and validation
+- Password hashing with bcrypt
+- Session management middleware
+
+Scope excludes:
+- OAuth/social login (future enhancement)
+- Password reset (separate spec: spec-auth-002)
+- Multi-factor authentication (future enhancement)
+```
+
+---
+
+#### Rationale (Required)
+**Location**: `## Rationale` section
+
+**Purpose**: Explain WHY this work matters
+
+**What to Include**:
+- Business value or technical benefit
+- Problem being solved
+- Impact if not done
+- Alignment with goals
+
+**Example Structure**:
+```markdown
+## Rationale
+[Why this is needed]
+
+[Problem being solved]
+
+[Business/technical impact]
+
+[What happens if not done]
+```
+
+**Good Example**:
+```markdown
+## Rationale
+User authentication is essential for protecting user data and enabling
+personalized features. Currently, all endpoints are public, exposing
+sensitive user information and preventing per-user customization.
+
+Problem solved: Unauthorized access to user data and inability to track
+user-specific actions.
+
+Business impact: Enables premium features, protects user privacy, meets
+security compliance requirements.
+
+If not done: Cannot launch paid features, risk data breaches, fail
+security audits, lose customer trust.
+```
+
+---
+
+#### Dependencies (Optional)
+**Location**: `## Dependencies` section
+
+**Purpose**: Link to related specifications
+
+**Format**:
+```markdown
+## Dependencies
+- **Requires**: spec-001, spec-002
+- **Blocks**: spec-003, spec-004
+- **Related**: spec-005
+```
+
+**Relationship Types**:
+```yaml
+Requires:
+  meaning: "These must be completed before this spec can start"
+  use_when: "Hard dependency on other work"
+  example: "Requires: spec-email-001 (email service must exist)"
+
+Blocks:
+  meaning: "This spec prevents other specs from starting"
+  use_when: "Other work depends on this being done"
+  example: "Blocks: spec-auth-002 (password reset needs auth)"
+
+Related:
+  meaning: "Related for context, not blocking"
+  use_when: "Useful context, not a hard dependency"
+  example: "Related: spec-user-001 (user profile system)"
+```
+
+---
+
+#### Risks (Optional)
+**Location**: `## Risks` section
+
+**Purpose**: Identify potential issues or challenges
+
+**Categories**:
+```yaml
+technical_risks:
+  - "Complex integration with third-party service"
+  - "Database migration required"
+  - "Performance impact on existing features"
+
+schedule_risks:
+  - "Depends on external team's timeline"
+  - "Blocked by infrastructure work"
+  - "May require more time than estimated"
+
+dependency_risks:
+  - "Third-party API may change"
+  - "Requires approval from security team"
+  - "Depends on unstable library"
+
+mitigation:
+  - "Include how to reduce or handle each risk"
+```
+
+**Good Example**:
+```markdown
+## Risks
+- **Performance risk**: Auth middleware adds latency to every request.
+  Mitigation: Cache token validation, use fast JWT library.
+
+- **Security risk**: Password storage vulnerability if implemented wrong.
+  Mitigation: Use battle-tested bcrypt library, security review required.
+
+- **Schedule risk**: Depends on database migration (spec-db-001).
+  Mitigation: Can implement with mock data, migrate later.
+```
+
+---
+
+#### Success Metrics (Optional)
+**Location**: `## Success Metrics` section
+
+**Purpose**: Define measurable outcomes
+
+**What to Include**:
+- Performance targets
+- Usage metrics
+- Quality metrics
+- Business metrics
+
+**Good Example**:
+```markdown
+## Success Metrics
+- Authentication latency < 200ms (p95)
+- Session validation < 50ms (p95)
+- Zero security vulnerabilities in audit
+- 99.9% uptime for auth service
+- 100% of protected endpoints require auth
+- Password hashing takes 200-300ms (bcrypt security)
+```
+
+---
+
+#### Acceptance Criteria (Required)
+**Location**: `## Acceptance Criteria` section
+
+**Purpose**: Define what "done" means with testable criteria
+
+**Format**: Checklist with `- [ ]` or `- [x]`
+
+**Guidelines**:
+```yaml
+do:
+  - Make each criterion specific and testable
+  - Include happy path and error cases
+  - Minimum 3 criteria (typically 5-8)
+  - Use action verbs: "User can...", "System will..."
+  - Be precise with numbers and timeframes
+
+dont:
+  - Use vague criteria: "System works well"
+  - Forget error cases
+  - Make criteria too large (break down if > 10)
+  - Forget non-functional requirements
+```
+
+**Good Example**:
+```markdown
+## Acceptance Criteria
+- [ ] User can login with valid email and password
+- [ ] Invalid credentials return 401 with error message
+- [ ] Successful login returns JWT token valid for 24 hours
+- [ ] Token automatically refreshes 1 hour before expiration
+- [ ] User can logout and invalidate their token
+- [ ] Logout clears session and prevents token reuse
+- [ ] Protected endpoints return 401 without valid token
+- [ ] Passwords are hashed with bcrypt (cost factor 12)
+- [ ] Login attempts are rate-limited (5 per minute)
+```
+
+**Bad Example**:
+```markdown
+## Acceptance Criteria
+- [ ] Login works
+- [ ] Errors handled
+- [ ] Security is good
+```
+
+---
+
+#### Test Scenarios (Required)
+**Location**: `## Test Scenarios` section
+
+**Purpose**: Describe how to verify acceptance criteria
+
+**Format**: Given/When/Then (BDD style)
+
+**Minimum**: 2 scenarios (happy path + error case)
+
+**Structure**:
+```markdown
+### [Scenario Name]
+**Given**: [Initial state / preconditions]
+**When**: [Action taken]
+**Then**: [Expected result]
+```
+
+**Good Example**:
+```markdown
+## Test Scenarios
+
+### Successful login
+**Given**: User has account with email "user@example.com" and password "SecurePass123"
+**When**: User submits correct credentials to /login endpoint
+**Then**: System returns 200 status with JWT token valid for 24 hours
+
+### Invalid password
+**Given**: User exists with email "user@example.com"
+**When**: User submits incorrect password
+**Then**: System returns 401 status with error "Invalid credentials"
+
+### Token expiration
+**Given**: User has JWT token that expired 1 minute ago
+**When**: User attempts to access protected endpoint
+**Then**: System returns 401 status with error "Token expired"
+
+### Rate limiting
+**Given**: User has attempted login 5 times in last minute
+**When**: User attempts 6th login
+**Then**: System returns 429 status with error "Too many attempts"
+```
+
+---
+
+#### Metadata (Optional)
+**Location**: `## Metadata` section
+
+**Purpose**: Additional information for tracking
+
+**Common Fields**:
+```markdown
+## Metadata
+estimated_hours: 8
+actual_hours: 10
+technical_notes: Using JWT library "jsonwebtoken", bcrypt cost factor 12
+branch: feat/user-authentication
+assignee: @developer-name
+labels: security, backend, high-priority
+```
+
+**Field Meanings**:
+```yaml
+estimated_hours:
+  description: "Time estimate before starting"
+  use: "Planning and capacity"
+
+actual_hours:
+  description: "Actual time spent (filled after completion)"
+  use: "Improve future estimates"
+
+technical_notes:
+  description: "Implementation details, library choices, etc"
+  use: "Context for implementers"
+
+branch:
+  description: "Git branch name for this work"
+  use: "Link spec to code changes"
+  added_when: "Work starts (activation)"
+
+assignee:
+  description: "Who's working on this"
+  use: "Track ownership"
+
+labels:
+  description: "Tags for categorization"
+  use: "Filtering and reporting"
+```
+
+---
+
+## Template Validation
+
+### Required Fields Check
+```yaml
+must_have:
+  - id
+  - type
+  - status
+  - priority
+  - created_at
+  - updated_at
+  - title
+  - description
+  - rationale
+  - acceptance_criteria (at least 1)
+  - test_scenarios (at least 1)
+
+can_warn_if_missing:
+  - dependencies
+  - risks
+  - success_metrics
+  - metadata
+```
+
+### Quality Checks
+```yaml
+description:
+  min_length: 50 characters
+  recommendation: "2-4 paragraphs"
+
+rationale:
+  min_length: 30 characters
+  recommendation: "Explain business/technical value"
+
+acceptance_criteria:
+  min_count: 3
+  recommendation: "5-8 criteria typical"
+  format: "Use checkboxes [ ] or [x]"
+
+test_scenarios:
+  min_count: 2
+  recommendation: "At least happy path + error case"
+  format: "Use Given/When/Then"
+```
+
+---
+
+## Quick Reference
+
+### Minimal Valid Spec
+```markdown
+---
+id: spec-feature-001
+type: feature
+status: draft
+priority: medium
+created_at: 2025-01-19T10:00:00
+updated_at: 2025-01-19T10:00:00
+---
+
+# Feature Title
+
+## Description
+What needs to be done.
+
+## Rationale
+Why this matters.
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Test Scenarios
+
+### Happy path
+**Given**: Initial state
+**When**: Action
+**Then**: Result
+```
+
+### Complete Spec
+See WRITING.md for complete examples with all optional sections filled.
+
+---
+
+*This template reference provides field-by-field details. Return to SKILL.md for overview, WRITING.md for creation process, or LIFECYCLE.md for management operations.*

skills/managing-specifications/WRITING.md

@@ -0,0 +1,515 @@
+# Specification Writing Guide
+
+This file provides complete details for creating specifications. Only load when user needs template details or writing guidance.
+
+## When to Load This File
+
+- User asks: "What fields does a spec have?", "Show me the template"
+- User wants examples of well-written specs
+- User is confused about spec format
+- Creating first spec and needs structure guidance
+
+## The Markdown Specification Template
+
+```markdown
+---
+id: spec-TYPE-NNN
+type: feature  # feature, bugfix, refactor, documentation, performance, security, testing
+status: draft
+priority: medium  # critical, high, medium, or low
+created_at: 2025-01-10T10:00:00
+updated_at: 2025-01-10T10:00:00
+---
+
+# Descriptive Title
+
+## Description
+What needs to be done. Be specific and detailed.
+Multiple paragraphs are fine.
+
+## Rationale
+Why this is needed.
+What problem it solves.
+Business or technical justification.
+
+## Dependencies
+- **Requires**: spec-001, spec-002 (specs that must be completed first)
+- **Blocks**: spec-003 (specs that can't start until this is done)
+- **Related**: spec-004 (related specs for context)
+
+## Risks
+- Risk description if any
+- Another risk if applicable
+
+## Success Metrics
+- Measurable success metric
+- Another measurable metric
+
+## Acceptance Criteria
+- [ ] User can do X
+- [ ] System performs Y
+- [ ] Feature handles Z
+- [ ] Error cases handled gracefully
+- [ ] Performance meets requirements
+
+## Test Scenarios
+
+### Happy path test
+**Given**: Initial state
+**When**: Action taken
+**Then**: Expected result
+
+### Error case test
+**Given**: Invalid input
+**When**: Action attempted
+**Then**: Appropriate error message shown
+
+## Metadata
+estimated_hours: 8
+technical_notes: Any technical considerations
+branch: feat/feature-name (added when work starts)
+```
+
+## Spec ID Generation
+
+I generate unique IDs based on type and existing specs:
+
+```yaml
+id_patterns:
+  feature: "spec-feature-NNN"
+  bugfix: "spec-bugfix-NNN"
+  refactor: "spec-refactor-NNN"
+  performance: "spec-perf-NNN"
+  security: "spec-sec-NNN"
+  testing: "spec-test-NNN"
+  documentation: "spec-docs-NNN"
+
+generation_process:
+  1. Check existing specs in draft/ folder
+  2. Find highest number for that type
+  3. Increment by 1
+  4. Zero-pad to 3 digits: 001, 002, etc.
+```
+
+**Example**: If `spec-feature-001` and `spec-feature-002` exist, next is `spec-feature-003`
+
+## Field Descriptions
+
+### Frontmatter Fields
+
+**id** (required): Unique identifier
+- Format: `spec-TYPE-NNN`
+- Auto-generated from type and sequence
+- Never changes once created
+
+**type** (required): Category of work
+- `feature` - New functionality
+- `bugfix` - Fix broken behavior
+- `refactor` - Improve code structure
+- `documentation` - Docs/comments
+- `performance` - Speed/efficiency
+- `security` - Security improvements
+- `testing` - Test coverage
+
+**status** (auto-managed): Current state
+- `draft` - Not started
+- `active` - Work in progress
+- `completed` - Finished
+- **Folder determines status**, not this field
+
+**priority** (required): Urgency level
+- `critical` - Drop everything, do this now
+- `high` - Important, schedule soon
+- `medium` - Normal priority
+- `low` - Nice to have, do when time allows
+
+**created_at** / **updated_at** (auto): ISO timestamps
+- Format: `2025-01-10T14:30:00`
+- Created when spec is written
+- Updated when spec is modified
+
+### Content Sections
+
+**Title** (required): Clear, descriptive name
+- Bad: "Auth", "Fix bug", "Update code"
+- Good: "User Authentication System", "Fix memory leak in processor", "Refactor payment validation logic"
+
+**Description** (required): What needs to be done
+- Be specific about functionality
+- Include scope and boundaries
+- Mention key components affected
+- Multiple paragraphs encouraged
+
+**Rationale** (required): Why this matters
+- Business value or technical benefit
+- Problem being solved
+- Impact if not done
+
+**Dependencies** (optional): Related specs
+- **Requires**: Must be completed first
+- **Blocks**: Prevents other specs from starting
+- **Related**: Provides context
+
+**Risks** (optional): Potential issues
+- Technical risks
+- Schedule risks
+- Dependency risks
+
+**Success Metrics** (optional): Measurable outcomes
+- Performance targets
+- Usage metrics
+- Quality metrics
+
+**Acceptance Criteria** (required): How to know it's done
+- Use checkboxes: `- [ ]` and `- [x]`
+- Be specific and testable
+- Include error cases
+- Minimum 3 criteria recommended
+
+**Test Scenarios** (required): How to verify
+- Happy path (success case)
+- Error cases (failure handling)
+- Edge cases (boundary conditions)
+- Use Given/When/Then format
+
+**Metadata** (optional): Additional info
+- `estimated_hours`: Time estimate
+- `technical_notes`: Implementation notes
+- `branch`: Git branch name
+
+## Writing Process
+
+### Step 1: Interactive Requirements Gathering
+
+**ALWAYS ask clarifying questions using AskUserQuestion tool:**
+
+#### Required Information
+If any of these are missing, ask:
+- **Title**: "What are we building/fixing?" (if not provided)
+- **Type**: Present options using AskUserQuestion - Feature, Bugfix, Refactor, Performance, Security, Testing, Documentation
+- **Description**: "What exactly needs to be done?"
+- **Scope**: "Should this include [related functionality]?"
+- **Priority**: Ask to choose - Critical, High, Medium, or Low?
+
+#### Decision Points
+When multiple approaches exist, use AskUserQuestion:
+
+**Example Question Pattern:**
+```yaml
+question: "I see multiple approaches for implementing [feature]. Which direction should we take?"
+options:
+  - label: "Approach A: [name]"
+    description: "[description with trade-offs like: Simple but limited, Fast but complex, etc.]"
+  - label: "Approach B: [name]"
+    description: "[description with trade-offs]"
+  - label: "Approach C: [name]"
+    description: "[description with trade-offs]"
+```
+
+#### Trade-off Clarifications
+When design choices exist, ask user to decide:
+- "Optimize for speed or simplicity?"
+- "Comprehensive feature OR minimal initial version?"
+- "Integrate with [existing system] OR standalone?"
+- "High performance OR easier maintenance?"
+
+**Always use structured questions (AskUserQuestion tool) rather than open-ended prompts.**
+
+### Step 2: Generate Unique ID
+
+Check existing specs and create next available ID:
+```bash
+# Check what exists
+ls .quaestor/specs/draft/spec-feature-*.md
+
+# If spec-feature-001 and spec-feature-002 exist
+# Create spec-feature-003
+```
+
+### Step 3: Fill Template with Actual Values
+
+**Always use real values, never placeholders:**
+
+✅ Good:
+```yaml
+id: spec-feature-001
+title: User Authentication System
+description: Implement secure login with JWT tokens and password hashing
+```
+
+❌ Bad:
+```yaml
+id: [SPEC_ID]
+title: [Feature Title]
+description: TODO: Add description
+```
+
+### Step 4: Create Checkboxes for Criteria
+
+Make criteria specific and testable:
+
+✅ Good:
+```markdown
+- [ ] User can login with email and password
+- [ ] Invalid credentials show error within 500ms
+- [ ] Session expires after 24 hours
+- [ ] Logout clears session completely
+```
+
+❌ Bad:
+```markdown
+- [ ] Login works
+- [ ] Errors handled
+- [ ] Security is good
+```
+
+### Step 5: Save to Draft Folder
+
+Write to `.quaestor/specs/draft/[spec-id].md`
+
+All specs start in draft/ regardless of when they'll be worked on.
+
+### Step 6: Report Success
+
+Tell user:
+- Spec ID created
+- File location
+- Next steps: "Run `/impl spec-feature-001` to start implementation"
+
+## Important Rules
+
+### ✅ Always Use Actual Values
+
+Never use placeholders like `[TODO]`, `[REPLACE THIS]`, `[SPEC_ID]`
+
+### ✅ Generate Sequential IDs
+
+Check existing files to find next number for each type
+
+### ✅ Include Test Scenarios
+
+Every spec needs at least:
+1. Happy path test
+2. Error case test
+
+### ✅ Make Criteria Testable
+
+Each acceptance criterion should be verifiable:
+- Can you write a test for it?
+- Is success/failure clear?
+- Is it specific enough?
+
+## Examples
+
+### Example 1: Feature Spec
+
+**User request**: "I want to add email notifications when orders are placed"
+
+**Created spec**: `spec-feature-001.md`
+```markdown
+---
+id: spec-feature-001
+type: feature
+status: draft
+priority: high
+created_at: 2025-01-19T10:30:00
+updated_at: 2025-01-19T10:30:00
+---
+
+# Order Confirmation Email Notifications
+
+## Description
+Send automated email notifications to customers when they successfully place an order. The email should include order details (items, quantities, total price), estimated delivery date, and a link to track the order.
+
+## Rationale
+Customers need immediate confirmation that their order was received. This reduces support inquiries about order status and provides professional customer experience. Industry standard for e-commerce platforms.
+
+## Dependencies
+- **Requires**: spec-email-001 (Email service integration)
+- **Related**: spec-order-003 (Order processing system)
+
+## Risks
+- Email delivery failures (use queuing system)
+- High volume during peak times (rate limiting needed)
+
+## Success Metrics
+- 95% email delivery rate within 30 seconds
+- Less than 1% bounce rate
+- Customer satisfaction score improvement
+
+## Acceptance Criteria
+- [ ] Email sent within 30 seconds of order placement
+- [ ] Email contains all order items with prices
+- [ ] Email includes estimated delivery date
+- [ ] Tracking link works and shows order status
+- [ ] Failed emails retry 3 times with exponential backoff
+- [ ] Admin dashboard shows email delivery status
+
+## Test Scenarios
+
+### Successful order email
+**Given**: User places order successfully
+**When**: Order is confirmed in database
+**Then**: Email is queued and sent within 30 seconds
+
+### Email delivery failure
+**Given**: Email service is temporarily down
+**When**: System attempts to send email
+**Then**: Email is queued for retry with exponential backoff
+
+### High volume scenario
+**Given**: 1000 orders placed simultaneously
+**When**: System processes order confirmations
+**Then**: All emails delivered within 5 minutes, no failures
+
+## Metadata
+estimated_hours: 12
+technical_notes: Use SendGrid API, implement queue with Redis
+```
+
+### Example 2: Bugfix Spec
+
+**User request**: "Memory leak in background processor needs fixing"
+
+**Created spec**: `spec-bugfix-001.md`
+```markdown
+---
+id: spec-bugfix-001
+type: bugfix
+status: draft
+priority: critical
+created_at: 2025-01-19T11:00:00
+updated_at: 2025-01-19T11:00:00
+---
+
+# Fix Memory Leak in Background Job Processor
+
+## Description
+The background job processor accumulates memory over time and doesn't release it after job completion. Memory usage grows from 200MB to 2GB+ over 24 hours, eventually causing OOM crashes. Affects job processing for order fulfillment and email sending.
+
+## Rationale
+Critical production issue causing service restarts every 12 hours. Impacts order processing reliability and customer experience. Root cause is database connections not being properly closed after job completion.
+
+## Dependencies
+None
+
+## Risks
+- Fix might affect job processing throughput
+- Need careful testing to avoid breaking existing jobs
+
+## Success Metrics
+- Memory usage stable at < 300MB over 72 hours
+- No OOM crashes
+- Job processing throughput unchanged
+
+## Acceptance Criteria
+- [ ] Memory usage remains stable over 72-hour test period
+- [ ] Database connections properly closed after each job
+- [ ] No memory leaks detected by profiler
+- [ ] All existing job types still process correctly
+- [ ] Performance benchmarks show no regression
+
+## Test Scenarios
+
+### Memory stability test
+**Given**: Background processor running for 72 hours
+**When**: 10,000 jobs processed during test period
+**Then**: Memory usage remains under 300MB
+
+### Connection cleanup verification
+**Given**: Single job completes
+**When**: Check database connection pool
+**Then**: Connection is returned to pool and not held
+
+## Metadata
+estimated_hours: 6
+technical_notes: Use context managers for DB connections, add memory profiling
+```
+
+### Example 3: Refactor Spec
+
+**User request**: "Authentication logic is spread across 5 files, needs consolidation"
+
+**Created spec**: `spec-refactor-001.md`
+```markdown
+---
+id: spec-refactor-001
+type: refactor
+status: draft
+priority: medium
+created_at: 2025-01-19T11:30:00
+updated_at: 2025-01-19T11:30:00
+---
+
+# Consolidate Authentication Logic
+
+## Description
+Authentication logic is currently scattered across 5 different files (api.py, middleware.py, services.py, utils.py, validators.py). This makes it hard to maintain, test, and understand the auth flow. Consolidate into a single AuthService class with clear responsibilities.
+
+## Rationale
+Technical debt causing maintenance issues. Recent security update required changes in 5 places. New developer onboarding takes longer due to scattered logic. Consolidation will improve testability and make security audits easier.
+
+## Dependencies
+None (existing functionality must continue working)
+
+## Risks
+- Regression in auth functionality
+- Need comprehensive test coverage before refactoring
+
+## Success Metrics
+- Auth logic in single module with < 300 lines
+- Test coverage > 90%
+- No behavior changes (all existing tests pass)
+- Reduced complexity score
+
+## Acceptance Criteria
+- [ ] All auth logic moved to single AuthService class
+- [ ] Existing functionality unchanged (all tests pass)
+- [ ] Test coverage increased to > 90%
+- [ ] Documentation updated with new structure
+- [ ] Code review approved by security team
+
+## Test Scenarios
+
+### Existing functionality preserved
+**Given**: Complete existing test suite
+**When**: Refactored code deployed
+**Then**: All 127 existing tests pass without modification
+
+### Improved testability
+**Given**: New AuthService class
+**When**: Write tests for edge cases
+**Then**: Can test authentication logic in isolation
+
+## Metadata
+estimated_hours: 16
+technical_notes: Start with comprehensive test coverage, refactor incrementally
+```
+
+## Tips for Best Specs
+
+### Be Specific
+- Instead of: "Add authentication"
+- Better: "Add email/password authentication with JWT tokens, 24-hour session expiry, and password reset via email"
+
+### Define Success Clearly
+- Bad: "System works"
+- Good: "User can login in < 2 seconds, sessions persist across browser restarts, invalid credentials show within 500ms"
+
+### Break Down Large Features
+If > 5 acceptance criteria, consider splitting:
+- `spec-auth-001`: Basic login/logout
+- `spec-auth-002`: Password reset
+- `spec-auth-003`: OAuth integration
+
+### Use Given/When/Then for Tests
+Follows BDD format that's clear and testable:
+```
+Given: Initial state
+When: Action taken
+Then: Expected result
+```
+
+---
+
+*This guide provides complete specification writing details. Return to SKILL.md for overview or LIFECYCLE.md for management operations.*