75 added, 22 removed. Audit A to A.
---
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"
+ version: "5.1.0"
category: analysis
platforms:
- CLAUDE_CODE
---
- You are generating an engineering specification formatted as a Jira story.
+ You are an engineering specification agent. Do NOT ask the user questions.
- 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).
+ ============================================================
+ TARGET: $ARGUMENTS
+ ============================================================
- 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.
+ - If $ARGUMENTS contains a feature description, use it as the basis for the spec.
+ - If $ARGUMENTS contains an image path, read the image to extract the design or spec to implement.
+ - If $ARGUMENTS contains "BE:" or "FE:", use that as the story type prefix.
+ - If $ARGUMENTS contains output from `/mvp` analysis, use the story candidates and feature breakdown as the basis. Do not re-analyze the application — trust the MVP output.
+ - If $ARGUMENTS is empty, check for recent `/mvp` output in the conversation context. If none, report that a feature description or story input is required.
- DETERMINE STORY TYPE:
+ ============================================================
+ PHASE 1: 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.
+ - If both are needed, generate two separate stories (one BE, one FE).
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:
+ ============================================================
+ PHASE 2: GENERATE SPEC
+ ============================================================
- ## Description
+ ### 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
+ ### 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
+ ============================================================
+ PHASE 3: GENERATE DEV NOTES
+ ============================================================
- Technical implementation guidance for the developer. Include:
+ ### Dev Notes
+ Technical implementation guidance for the developer.
+
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:
+ ============================================================
+ PHASE 4: VERIFY SPEC COMPLETENESS
+ ============================================================
+ Self-check the generated spec:
+ 1. Every acceptance criterion is testable (no vague language).
+ 2. Every API route includes method, full path, and behavior description.
+ 3. Every table includes column types and modifiers.
+ 4. No placeholders or "TBD" markers remain.
+ 5. The description is 2-4 sentences, no more.
+ 6. The title follows the BE:/FE: format with 8 words or fewer after the prefix.
+
+ ============================================================
+ OUTPUT
+ ============================================================
+
+ ## Spec Generated
+
+ | Field | Value |
+ |-------|-------|
+ | Title | BE:/FE: [Story Title] |
+ | Type | Backend / Frontend |
+ | Acceptance criteria groups | N |
+ | Total criteria | N |
+ | API routes defined | N |
+ | Database tables defined | N |
+ | Estimated complexity | Low / Medium / High |
+
+ [Full spec content follows in the sections above]
+
+ ============================================================
+ 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:
+ ============================================================
+ 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."
+ - Run `/arch-review` with this story to get architect-level feedback before implementation.
+ - Run `/si` to implement this story directly in the current repo.
+ - Run `/review-implement` to chain architect review into implementation (combo skill).
+ - Run `/manual-test-plan` to generate QA verification scenarios from the acceptance criteria.
+
+ ============================================================
+ DO NOT
+ ============================================================
+
+ - Do NOT use vague language like "handle properly", "etc.", or "as needed" in acceptance criteria.
+ - Do NOT combine backend and frontend work into a single story — split into separate BE:/FE: stories.
+ - Do NOT omit error behavior and edge cases from acceptance criteria.
+ - Do NOT skip the Routes category for any story involving API endpoints.
+ - Do NOT leave column types unspecified in table schemas.