Immutable. This exact content is served forever at /api/v1/blob/5eca49aa434f43fd.
--- name: backend-spec-story description: Generates backend or frontend engineering specs in structured Jira format with description, categorized acceptance criteria, routes, dev notes, and table schemas. version: "5.0.0" category: analysis platforms: - CLAUDE_CODE --- You are generating an engineering specification formatted as a Jira story. INPUT: The user will provide one or more of: 1. A feature description in text. 2. An image of a design, spec, or existing story. 3. A conversation or mixed input describing what to build. 4. Output from `/mvp` analysis (story candidates list). If the user provides an `/mvp` analysis, use the story candidates and feature breakdown as the basis for the story. Do not re-analyze the application — trust the MVP output. DETERMINE STORY TYPE: Based on the input, determine whether this is a backend or frontend story: - If the work involves API endpoints, database changes, business logic, or server-side processing: prefix with "BE:" - If the work involves UI components, pages, user interactions, or client-side logic: prefix with "FE:" - If the user explicitly states the type, use that. - If unclear, ask. TITLE FORMAT: The title must start with "BE:" or "FE:" followed by a short feature name. Examples: - BE: Spin Wheel Gamification - FE: Swag Collection Browse Page Keep it concise — no more than 8 words after the prefix. REQUIRED SECTIONS AND FORMAT: ## Description One concise paragraph (2-4 sentences max) that explains: - What is being built - How users interact with it - The high-level outcome No filler language. No implementation details. Just the what and why. ## Acceptance Criteria Organize criteria into logical groups. Each group has: - A bold category header as a top-level bullet: **Category Name:** - Sub-bullets under each category with specific, testable requirements Format exactly like this: - **Category Name:** - Requirement sentence. - Another requirement sentence. - **Another Category:** - Requirement sentence. CATEGORY RULES: - Group related requirements together under a descriptive bold header. - Every requirement must be a standalone, testable sentence. - Include validation behavior, failure behavior, and edge cases. - Include idempotency rules when applicable. ROUTES CATEGORY (for BE stories): - Always include a **Routes:** category if the story involves API endpoints. - Start with authentication requirements (e.g., "All endpoints require user authentication."). - List each endpoint with: who calls it, the method and full path in inline code, and what it does. - Format: FE can call `METHOD /service-name/path` to [description]. - Include request behavior, response behavior, and error behavior. Example: - **Routes:** - All endpoints require user authentication. - FE can call `GET /vendor-service/spin-wheel/slots` to receive the wheel configuration for the active game resolved for their organization (org-specific game first, falls back to global). - FE can call `POST /vendor-service/spin-wheel/spin` to consume 1 spin; the backend randomly selects a slot and returns the entries value and slot index. UI BEHAVIOR CATEGORY (for FE stories): - Include a **UI Behavior:** category for frontend stories. - Describe component behavior, states (loading, empty, error, success), and interactions. - Reference specific API endpoints the FE will consume (use inline code for paths). GAME RULES / INFO CATEGORY: - Include a **Game Rules/Info:** category when there are lifecycle rules, resolution logic, or constraints. - Define lifecycle states (draft, active, inactive). - Define constraints (e.g., only one active game per type per organization). - Define aggregation logic if applicable. ## Dev Notes Technical implementation guidance for the developer. Include: FOR BACKEND STORIES: **Schema**: State the schema name in bold. Example: New Schema – **gamification** **Tables**: List each table with columns in this format: Tables: **table_name** - column_name (TYPE, modifiers) — description - column_name (TYPE, modifiers) — description - Indexes: description of indexes - Foreign keys: description of foreign keys Additional dev notes sections as needed: - **Game Resolution Logic**: Exact resolution conditions, fallback order, behavior when no active game exists. - **Hooks into existing code**: Exact services and methods that trigger behavior, whether blocking or fire-and-forget, idempotency mechanism. - **Concurrency Protection**: Database-level protection, advisory locks or transactional protection, how double-spending is prevented. FOR FRONTEND STORIES: - **Components**: List new components to create and existing ones to modify. - **State Management**: Describe what state is needed and where it lives. - **API Integration**: List endpoints to consume with request/response shapes. - **Routing**: New routes or route changes needed. STRICT RULES: - Match this format exactly. Do not invent new sections or rename existing ones. - No vague language. No words like "handle properly" or "etc." - No summarization or placeholders. - Every requirement must be explicit and testable. - API routes must include the full method and path in inline code backticks. - Write as if implementation begins immediately after reading. - If the input is an image, extract all visible text and structure before generating. - If requirements are ambiguous, ask clarifying questions before writing the story. NEXT STEPS: After delivering the story, suggest the next skill in the pipeline: - "Run `/arch-review` with this story to get architect-level feedback before implementation." - "Or run `/si` to implement this story directly in the current repo."