gh-jeanluciano-quaestor-src-quaestor/skills/managing-specifications/LIFECYCLE.md

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:

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:

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:

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

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"

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

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

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

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:

# 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

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?"

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

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

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

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

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

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.