sc30gsw/vcsdd-spec-crystallization

VCSDD Spec Crystallization

When to Activate

• Phase 1a of VCSDD pipeline (behavioral specification)
• Writing EARS-format requirements
• Identifying edge cases for a feature
• Reviewing a behavioral spec for completeness

EARS Requirement Format

Every requirement MUST use EARS (Easy Approach to Requirements Syntax):

| Pattern | Syntax | Example | |---------|--------|---------| | Ubiquitous | THE SYSTEM SHALL [action] | THE SYSTEM SHALL log all authentication attempts | | Event-driven | WHEN [trigger] THE SYSTEM SHALL [action] | WHEN user submits empty form THE SYSTEM SHALL return ErrorCode.EMPTY | | State-driven | WHILE [state] THE SYSTEM SHALL [action] | WHILE user is authenticated THE SYSTEM SHALL display dashboard | | Conditional | IF [condition] THEN THE SYSTEM SHALL [action] | IF retry count exceeds 3 THEN THE SYSTEM SHALL lock account | | Optional | WHERE [feature] THE SYSTEM SHALL [action] | WHERE audit mode enabled THE SYSTEM SHALL record all reads |

Spec Completeness Checklist

• [ ] Every requirement has a unique ID (REQ-001, REQ-002, ...)
• [ ] Every requirement uses EARS syntax
• [ ] Every requirement is testable (can be pass/fail verified)
• [ ] Edge case catalog includes: empty inputs, boundary values, concurrent access, error conditions
• [ ] Non-functional requirements specified (performance bounds, security constraints)
• [ ] Purity boundary identified: pure core vs effectful shell

Purity Boundary Analysis

Separate code into:

• Pure Core: deterministic functions, no side effects, same input → same output always
  • Example: parsing logic, business rules, validation, calculations
  • Formally verifiable with Kani/hypothesis/fast-check
• Effectful Shell: I/O, database, network, time, randomness
  • Example: file readers, HTTP clients, database queries
  • Tested with integration tests and mocks at the boundary

Edge Case Catalog Template

## Edge Cases

### Input Edge Cases
- Empty input: [expected behavior]
- Maximum length input: [expected behavior]
- Special characters / unicode: [expected behavior]
- Null / undefined: [expected behavior]

### State Edge Cases
- First-time run (no state): [expected behavior]
- Concurrent modification: [expected behavior]
- Interrupted operation: [expected behavior]

### Error Edge Cases
- External dependency unavailable: [expected behavior]
- Partial failure: [expected behavior]
- Timeout: [expected behavior]