Skip to content
SpecFlow SpecFlow
🚧 This documentation is a draft and is currently under review. 🚧

201 High-Level Design

What this skill is for

Section titled “What this skill is for”

201-high-level-design creates a short feature overview that explains what the feature does, what is in scope, what is out of scope, how the user journey works, and when meaningful, how reviewers will know the feature is working correctly.

This is the moment where a vague feature request becomes something reviewable. If the feature definition is blurry here, everything after it gets harder.

Output path: .specflow/features/<fid>-<feature-slug>/overview.md

When to use it

Section titled “When to use it”
  • When starting design work for a specific feature
  • When the team needs a shared plain-language understanding before writing specs
  • When you want a reviewable scope boundary before implementation begins
  • When the feature is new and no design artifacts yet exist

When NOT to use it

Section titled “When NOT to use it”
  • When the feature scope is already clear, written, and agreed on
  • For tiny changes (single field, small bug fix) where a one-line description is sufficient
  • When you are using 301 directly and are comfortable with it synthesizing a working 201 in memory

What it produces

Section titled “What it produces”
  • .specflow/features/<fid>-<feature-slug>/overview.md with:
    • Feature slug in front matter and a stable F-ID
    • Concise description of what the feature does
    • In-scope boundaries
    • Explicit out-of-scope decisions
    • Primary user journey as a plain-text bullet list
    • Acceptance criteria when reviewable outcomes can be stated
    • Lifecycle front matter for status tracking

Required inputs

Section titled “Required inputs”
  • Feature name
  • One sentence of context about what the feature should do

201 requires an assigned F-ID before it creates the feature folder. If D10-feature-overview.md tracks this feature, it reuses that F-ID. Otherwise it should ask whether to add the feature to D10 first or assign an F-ID explicitly.

Common prompts

Section titled “Common prompts”
Prompt
Run 201-high-level-design for account recovery.
Prompt
Run 201-high-level-design for invoice approval.

What usually comes next

Section titled “What usually comes next”

202-spec-design — write the Gherkin scenarios that describe what the feature should do, using overview.md as the scope reference.

Practical guidance

Section titled “Practical guidance”
  • Keep the output short enough for fast human review. The goal is a reviewable scope boundary, not a complete specification.
  • The feature folder should always start with the F-ID, for example .specflow/features/F003-invoice-approval/overview.md.
  • Use the out-of-scope list to draw explicit boundaries — implicit assumptions about what is not included tend to become scope creep.
  • The user journey should stay a plain-text bullet list, not a diagram. Diagrams are harder to review in code review and harder to update.
  • Acceptance criteria are optional but valuable on features where “done” is ambiguous.

Common mistakes

Section titled “Common mistakes”
  • Treating 201 as an implementation plan
  • Writing generic scope bullets that do not actually constrain the feature
  • Skipping explicit out-of-scope decisions
  • Writing a user journey so detailed it becomes a UI specification