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

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

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

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:

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

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:

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:

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:

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:

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

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

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

## Rationale
[Why this is needed]

[Problem being solved]

[Business/technical impact]

[What happens if not done]

Good Example:

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

## Dependencies
- **Requires**: spec-001, spec-002
- **Blocks**: spec-003, spec-004
- **Related**: spec-005

Relationship Types:

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:

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:

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

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

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:

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

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

### [Scenario Name]
**Given**: [Initial state / preconditions]
**When**: [Action taken]
**Then**: [Expected result]

Good Example:

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

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

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

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

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

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