Our Requirements Were 'Finished' — But 60% of Stories Were Wrong at Sprint End

Ambiguous requirements are the #1 cause of sprint failure. FlowSquad's requirement refinement asks clarifying questions and cross-references your codebase before locking in a spec.

How Does Ambiguity Create Rework?

Ambiguity in requirements doesn't announce itself. A story that says "Allow users to reset their password" looks complete. It has a verb, a subject, and an object. It'll pass a three-amigo review without objection. Then the developer starts building and asks:

• Does "reset" mean change a known password, or recover a forgotten one?
• Via email link? SMS OTP? Security questions?
• What's the link expiry time?
• Does the reset invalidate all active sessions?
• What's the rate limiting on reset requests?
• Is there a self-service flow or does it go through support?

Each of these questions is a decision point. In the absence of a documented decision, the developer makes a judgment call. Some calls are correct. Some aren't. The ones that aren't — discovered at sprint review — generate rework. The rework estimate for a story that needs to be partially rebuilt after development is typically 40–80% of the original story's estimate, paid twice.

The compounding problem is that the same ambiguities recur. Without a systematic refinement process, teams relitigate the same question categories sprint after sprint. A structured refinement process that asks the right questions consistently would eliminate this, but writing those questions manually requires expertise and time that most teams don't have at planning speed.

How Does FlowSquad's 2-Step Refinement Work?

FlowSquad's requirement refinement engine operates in two sequential phases, transforming a raw requirement into a production-ready story spec:

Step 1 — Clarifying Question Generation

When you input a raw requirement into FlowSquad, the platform generates a structured set of clarifying questions before any spec is written. These questions are categorised:

• Scope questions: "Does this apply to all user types, or only premium subscribers?"
• Edge case questions: "What happens if the user attempts this action while their account is suspended?"
• Integration questions: "Should this trigger an event in the notification service?"
• Constraint questions: "Are there regulatory requirements that affect how this data is stored?"
• Codebase-informed questions: "The existing AuthService has a rate limiter on reset requests — should this feature use it, or does it need a different limit?"

The last category — codebase-informed questions — is unique to FlowSquad. Because the platform has indexed your codebase via the VectorDB layer, it can cross-reference new requirements against existing implementations and ask questions that no generic LLM could generate, because they require knowledge of your specific system.

Step 2 — Spec Generation

After you answer the clarifying questions (typically 5–12 questions per requirement, taking 8–15 minutes), FlowSquad generates a complete requirement specification:

• Full user story in your preferred format
• Acceptance criteria in Given/When/Then or checklist format
• Edge cases and out-of-scope statements
• Technical notes (affected modules, APIs to create/modify)
• Suggested story point estimate range based on scope and codebase complexity

How Does Codebase Context Catch Impossible Requirements Early?

One of FlowSquad's most practically valuable refinement capabilities is identifying requirements that are technically impossible given the current codebase — surfacing them during refinement, before a developer discovers them mid-sprint.

Common examples:

• A requirement to "add real-time push notifications" when the backend is a stateless REST API with no WebSocket infrastructure
• A requirement to "store user preferences per device" when the data model has no concept of device identity
• A requirement to "support payment in 50 currencies" when the payment gateway integration only supports 12

FlowSquad's VectorDB-grounded refinement detects these mismatches by comparing the requirement semantics against the indexed codebase. When it finds a conflict, it surfaces it as a clarifying question: "The current payment gateway integration (payments/gateway/stripe.py) only supports USD, EUR, and GBP. Is expanding currency support a dependency of this requirement, or should it be scoped to supported currencies only?"

This kind of question, answered in a 15-minute refinement session, prevents a 3-day mid-sprint crisis where a developer discovers an architectural blocker and has to escalate to the tech lead.

From Refined Requirement to Signed-Off Story in One Session

The end-to-end refinement workflow in FlowSquad takes approximately 20–35 minutes per requirement — including the Q&A session and spec review — and produces a story that is ready for sprint planning without further discussion:

1. Paste or type raw requirement into FlowSquad
2. Answer FlowSquad's clarifying questions (8–15 minutes)
3. Review the generated spec (2–5 minutes) — edit inline if needed
4. One-click push to Jira as a fully-formed story with acceptance criteria
5. Optional: push the requirement document to Confluence for stakeholder sign-off

What Acceptance Criteria Does FlowSquad Generate?

FlowSquad generates acceptance criteria in three formats, configurable per project:

# FlowSquad acceptance criteria output example (YAML)
story:
  title: "As a user, I can reset my forgotten password via email"
  acceptance_criteria:
    given_when_then:
      - given: "I am on the login page and do not know my password"
        when: "I click 'Forgot password?' and enter my registered email"
        then: "I receive a reset email within 60 seconds containing a link valid for 1 hour"
      - given: "I click the reset link within 1 hour"
        when: "I enter a new password meeting complexity requirements (8+ chars, 1 special)"
        then: "My password is updated and all active sessions except the current one are invalidated"
      - given: "The reset link has expired (>1 hour)"
        when: "I click the link"
        then: "I see an error 'This reset link has expired. Please request a new one.' No password change occurs."
      - given: "I attempt to request a reset more than 5 times in 10 minutes"
        when: "I submit the form"
        then: "Requests are rate-limited; I see 'Too many requests. Please try again later.'"
    out_of_scope:
      - "Admin-initiated password resets (separate story)"
      - "SMS-based reset (future enhancement)"
    technical_notes:
      - "Use existing EmailService (notifications/services/email_service.py)"
      - "Reduce PasswordReset token expiry from 24h to 1h in auth/models/password_reset.py"
      - "Invalidate sessions via SessionManager.invalidate_all_except(user_id, current_session_id)"