The Flexso Spec Template

Every GitLab issue gets a spec once it enters stage::spec — but the template is two-tier, dialed by the issue's size:: label: spec-lite for size::xs/size::s (a lighter-weight version of the same sections) and the full template below for size::m/size::l/size::xl. Both are structured so that humans and AI can parse them. A well-written spec should enable a developer (or Claude Code) to start building without a single additional conversation.

## Summary
{One paragraph. What are we building and why? Who benefits?}

## User Stories
- As a {role}, I want {action} so that {benefit}
- As a {role}, I want {action} so that {benefit}

## Acceptance Criteria
Given {context}
When {action}
Then {expected result}

Given {context}
When {action}
Then {expected result}

## Data Model
{CDS-like pseudocode or Mermaid ER diagram of entities involved}

## API Contract
{Endpoints, methods, request/response shapes if applicable}

## Integration Points
- Connects to: {SAP system, API, event}
- Authentication: {XSUAA, API key, destination}
- Data flow: {inbound/outbound, frequency, volume}

## UI/UX Requirements
{Wireframe links, Fiori design guideline references, or text description}
{Specify: List Report, Object Page, Freestyle, Launchpad tile}

## Edge Cases & Error Handling
- What happens when {edge case}?
- What happens when {external system is down}?
- What happens when {data is missing}?

## Out of Scope
{Explicitly list what this spec does NOT cover to prevent scope creep}

## Dependencies
- Blocked by: {issue link}
- Blocks: {issue link}
- Shared lib required: {package}

## Size Estimate
{T-shirt size: XS / S / M / L / XL}
{Rationale: "M because it involves 2 new entities + 1 integration"}

---
Spec Author: {name}  |  Spec Reviewer: {name}  |  Approved: ☐

Pro tip — AI Spec Review

After writing a spec, paste it into Claude and ask: "Review this spec for completeness. What edge cases am I missing? What questions would a developer have?" This catches gaps before the design phase and prevents costly back-and-forth.