Idea for dedicated requirements step

[pikant]

Intro

I am quite impressed with Agent OS. Regarding the shape-spec step, I noticed that it already focusses a lot on the solution. I assume this is intentional. Nevertheless, I wanted to share our approach.

Our approach

We generally always try to separate the problem side from the solution side – in other words, the requirement specification from the technical specification, if you will.

Our planninc process:

1. Fully understand the problem; Output: requirements specification
2. Plan the solution; Output: implementation specification (->claude plan)

Here is our command for step 1:

You are now starting a spec-driven workflow for a new feature.

Feature idea: $ARGUMENTS

---

## Phase 1: Interview (iterative)

Your goal is to fully understand the requirements BEFORE you write anything.
Work like an experienced business analyst.

Approach:
- Ask 2–3 targeted, numbered questions per round
- Briefly summarize your understanding after each round
- Actively identify gaps, contradictions, and implicit assumptions
- Ask about edge cases and boundaries
- When you believe you fully understand the feature:
  Provide a compact summary and explicitly ask:
  "Is the feature fully described, or is anything missing?"
- Only proceed to Phase 2 after I confirm

Do NOT stop after one round. Keep iterating until there is full clarity.

---

## Phase 2: Write the spec

Create specs/[yyyy-mm-dd-feature-name].md with the following structure:
    ```
    # Feature: [Name]

    > Brief description in 1–2 sentences

    ## Context & Problem
    Why do we need this? What is the trigger?

    ## Goals
    - Business/technical goals
    - Expected outcome

    ## Requirements

    ### Functional
    - As a [role], I want [action], so that [benefit]
    - When [condition], then [behavior]

    ### Non-functional
    - Only if relevant (performance, security, compatibility)

    ## Out of Scope
    What is explicitly NOT part of this feature?

    ## Open Questions
    - Items that need to be clarified before implementation
      (or empty if everything is resolved)
    ```

---

## Rules
- Focus on What and Why – no design, no architecture, no code
- Use kebab-case feature name for the filename
- The spec must reflect all insights from the interview
- Do not make assumptions that were not confirmed in the interview

We also have subsequent commands with which the requirements can be refined in order to then create a new plan to ultimately adjust the implementation.

Why I share this:

1. I am honestly quite impressed by Claude’s ability to understand the problem and ask very, very good substantive follow-up questions. The question rounds from our workflow have often pointed out issues that we would otherwise have forgotten.
2. I think it is quite clean to think about the problem/requirements first before you start planing the solution. Sometime, both sides interphere - but this is not a problem for this workflow.