Skip to content

Replace Open Questions spec section with a shorter questions file #53

@tylertimms

Description

@tylertimms

Background

During review of PR #52, two patterns were observed with the Open Questions section at the end of generated specs:

  1. The section sometimes includes questions that already have a pre-filled answer — a middle ground that is neither a true open question nor a deliberate clarification round.
  2. Occasionally the answer to an open question is deferred to a later SDD phase, which is unhelpful.

Meanwhile, the questions file format — presenting multiple labeled options with a recommended answer and justification — is consistently more useful to reviewers. It surfaces options users may not have considered and makes the agent's assumptions explicit and correctable.

Proposed Change

Remove the Open Questions section from the spec template and replace its purpose with a shorter questions file using the existing questions file format.

When Phase 1 identifies remaining questions that are minor enough not to block spec generation but significant enough not to silently assume, instead of appending them to the spec body it should generate a short questions file with the familiar multiple-option + recommendation structure.

This would:

  • Consolidate two question-handling mechanisms into one consistent format
  • Give users the structured option + recommendation view they already find valuable from the clarification flow
  • Eliminate the awkward pattern of "questions with pre-filled answers" buried at the bottom of a spec
  • Keep the spec document focused on requirements and design rather than open-ended uncertainty

Context

Raised during review of PR #52 (feat: add SDD agent skill install option).

Relevant thread: #52 (comment)

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions