shape-up

Shape Up — Top-Down Design Spec

Shape a vague idea into a clear design spec by working top-down: start from the big picture, confirm alignment at each layer, then go deeper. This is NOT an interview — it's collaborative writing where the agent drafts and the user shapes.

When to Use

• User says "shape up", "design spec", "let's design", "plan a system", "I need to think through this"
• User has a large or ambiguous project and needs to see the big picture first
• Before /grill-design — when the scope isn't clear enough to grill on details yet

Core Principle

One layer at a time. Confirm before going deeper. Never jump ahead.

If the user can't answer something at the current layer, mark it [TBD] and move on. Don't drill down into unknowns — that's how people lose focus.

Workflow

Layer 1: Vision

Ask the user to describe what they're building in plain language. Then co-write a short vision block:

• What — one sentence describing the thing
• Why — what problem it solves, who it's for
• Done looks like — how you'd know it succeeded

Draft this as a short block (5-8 lines max). Show it to the user. Adjust until they say it's right.

Do NOT ask about tech stack, architecture, or implementation yet.

Layer 2: Scope

Now that the vision is clear, co-write the scope:

• In scope — what this project will do (bullet list)
• Out of scope — what it explicitly won't do (bullet list)
• Constraints — timeline, tech, team, budget, dependencies
• Users / Actors — who interacts with it

Draft and show. The user cuts, adds, moves things between in/out scope. Keep going until scope feels tight.

If scope is getting too big, say so: "This feels like it's growing — want to split it?"

Layer 3: Building Blocks

Break the in-scope work into 3-7 big blocks. Each block is a major component, feature area, or workstream. For each block:

• Name — short label
• Purpose — one line
• Depends on — which other blocks it needs