specifier

The output is not for humans to read casually — it's a machine-parseable contract that defines exactly what "done" looks like.

Key insight from SDD methodology: Specs must be structured for machine comprehension, not just human readability. Use hierarchical Markdown, explicit invariants, and testable acceptance criteria.

IF user's description is vague or high-level:
  ASK targeted questions (MAX 5 per round — don't overwhelm):
    - "Who is the primary user? What's their situation when they use this?"
    - "What's the ONE thing this must do well to be useful?"
    - "What's explicitly out of scope for v1?"
    - "Are there hard constraints? (platform, budget, compliance, timeline)"
    - "Any existing products you like or want to differentiate from?"

  AWAIT answers before proceeding

ELIF user's description is detailed:
  SUMMARIZE understanding back to user
  ASK: "Did I get that right? Anything I'm missing?"
  AWAIT confirmation

Happy Path (the standard flow):

1. User arrives at [entry point]
2. User performs [action]
3. System responds with [response]
4. User sees [outcome]
5. ...continue until journey completes

Edge Cases (boundary conditions):

• Empty states (no data yet, first-time user)
• Maximum limits (too many items, too large file, rate limits)
• Concurrent access (two users editing same thing)
• Partial completion (user abandons halfway, network drops)
• Invalid input (wrong format, out of range, special characters)

Error States (what can go wrong):

• Network failures
• Authentication expiration
• Data validation failures
• External service outages
• Permission denied scenarios

For each error state, define: what the user sees, what the system does, how recovery works.

Present user journeys to user for validation before continuing.

Categories:

• Business Logic: Rules about data and operations (e.g., "order total = sum of line items")
• Data Integrity: Rules about data state (e.g., "email must be unique per account")
• Security: Rules about access and protection (e.g., "API keys never in client code")
• UX: Rules about user experience (e.g., "every destructive action requires confirmation")
• Performance: Rules about speed (e.g., "search results return within 500ms")

Format each invariant as:

INV-{NNN}: {rule statement} — {why this matters}

These must be testable. If you can't write a test for it, it's not specific enough.

In Scope (v1): List every feature/capability that WILL be built.

• Be specific: "User authentication via email/password" not "auth"
• Include data requirements: "Store user profile with name, email, avatar"

Explicitly Out of Scope: List things that might seem related but are NOT being built.

• For each, briefly state why (deferred to v2, not needed, too complex for now)