binance-api/.specify/templates/spec-template.md

Feature Specification: [FEATURE NAME]

Feature Branch: [###-feature-name]
Created: [DATE]
Status: Draft
Input: User description: "$ARGUMENTS"

Execution Flow (main)

1. Parse user description from Input
   → If empty: ERROR "No feature description provided"
2. Extract key concepts from description
   → Identify: actors, actions, data, constraints
3. For each unclear aspect:
   → Mark with [NEEDS CLARIFICATION: specific question]
4. Fill User Scenarios & Testing section
   → If no clear user flow: ERROR "Cannot determine user scenarios"
5. Generate Functional Requirements
   → Each requirement must be testable
   → Mark ambiguous requirements
6. Identify Key Entities (if data involved)
7. Run Review Checklist
   → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
   → If implementation details found: ERROR "Remove tech details"
8. Return: SUCCESS (spec ready for planning)

---

⚡ Quick Guidelines

• ✅ Focus on WHAT users need and WHY
• ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
• 👥 Written for business stakeholders, not developers

Section Requirements

• Mandatory sections: Must be completed for every feature
• Optional sections: Include only when relevant to the feature
• When a section doesn't apply, remove it entirely (don't leave as "N/A")

For AI Generation

When creating this spec from a user prompt:

1. Mark all ambiguities: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
2. Don't guess: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
3. Think like a tester: Every vague requirement should fail the "testable and unambiguous" checklist item
4. Common underspecified areas:
   • User types and permissions
   • Data retention/deletion policies
     
   • Performance targets and scale
   • Error handling behaviors
   • Integration requirements
   • Security/compliance needs

---

User Scenarios & Testing (mandatory)

Primary User Story

[Describe the main trading / hedging scenario that maintains delta neutrality]

Acceptance Scenarios

1. Given [account exposure state], When [hedge or order action], Then [delta neutrality is restored and fees covered]
2. Given [market data freshness], When [strategy executes], Then [order placements respect exposure and risk limits]

Edge Cases

• What happens when market data becomes stale or unavailable?
• How does the system handle liquidity gaps, proxy failures, or partial fills?

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST maintain aggregate delta ≈ 0 across all exchanges within mandated thresholds.
• FR-002: System MUST acquire and validate orderbook data in real-time (primary WebSocket, backup HTTP).
• FR-003: System MUST execute hedging, rebalance, and market-making flows that achieve profit-after-fee targets.
• FR-004: System MUST enforce risk limits (position, leverage, drawdown) per account and react within defined SLAs.
• FR-005: System MUST emit structured logs/metrics covering order lifecycle, exposure, and health events.
• FR-006: Requirements MUST specify automated test coverage (simulation, integration, fallback scenarios).

Example of marking unclear requirements:

• FR-006: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
• FR-007: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]

Key Entities (include if feature involves data)

• [Entity 1]: [What it represents, key attributes without implementation]
• [Entity 2]: [What it represents, relationships to other entities]

---

Review & Acceptance Checklist

GATE: Automated checks run during main() execution

Content Quality

• No implementation details (languages, frameworks, APIs)
• Focused on user value and business needs
• Written for non-technical stakeholders
• All mandatory sections completed

Requirement Completeness

• No [NEEDS CLARIFICATION] markers remain
• Requirements are testable and unambiguous
  
• Success criteria are measurable
• Scope is clearly bounded
• Dependencies and assumptions identified

---

Execution Status

Updated by main() during processing

• User description parsed
• Key concepts extracted
• Ambiguities marked
• User scenarios defined
• Requirements generated
• Entities identified
• Review checklist passed

---