# Design Exploration

> Explores user intent, requirements, and trade-offs through collaborative dialogue before any code is written, producing a validated design document. Use before creating features, building components, or making significant behavior changes. Use when requirements are ambiguous, when an architectural decision is imminent, or when you are tempted to start coding without a shared understanding of what…

- **Type:** Skill
- **Install:** `agentstack add skill-jagreehal-jagreehal-claude-skills-design-exploration`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jagreehal](https://agentstack.voostack.com/s/jagreehal)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jagreehal](https://github.com/jagreehal)
- **Source:** https://github.com/jagreehal/jagreehal-claude-skills/tree/main/skills/design-exploration

## Install

```sh
agentstack add skill-jagreehal-jagreehal-claude-skills-design-exploration
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Design Exploration

## Overview

Turn an idea into a fully-formed design through collaborative dialogue, then write it down before any production code exists. The design document is the shared source of truth between you and the human: it defines what we are building, why, and how we will know it is done. Code without an agreed design is guessing, and guessing at speed is how an agent produces a confident, well-tested implementation of the wrong thing.

The core principle is an iron law:

```
NO IMPLEMENTATION WITHOUT DESIGN AGREEMENT FIRST
```

If the design has not been validated by the human, you cannot write production code. The entire value of this skill is surfacing misunderstandings *before* they get encoded.

## When to Use

- Before creating a new feature
- Before building a new component
- Before a significant behavior change
- Before making an architectural decision
- When requirements are ambiguous or only exist as a vague idea
- Before complex refactoring

**When NOT to use:** Single-file, single-function changes with unambiguous, self-contained requirements; typo fixes; or work where the design is already documented and approved.

**Related:** Feed the output into [implementation-planning](../implementation-planning/SKILL.md) to turn the validated design into tasks. Isolate the work in a [git-worktrees](../git-worktrees/SKILL.md) workspace if it needs to run in parallel. Implementation follows [tdd-workflow](../tdd-workflow/SKILL.md).

## The Process

### Phase 1: Understand Context

- Check current project state: files, docs, recent commits
- Understand what exists before proposing changes
- Review related code to learn existing patterns and conventions

### Phase 2: Clarify Intent

- Ask questions one at a time; never bundle multiple questions into one message
- Prefer multiple choice when the option space is known
- Focus on purpose, constraints, and success criteria
- Never assume requirements without asking
- Never skip clarification because "it seems obvious"

### Phase 3: Explore Approaches

- Propose 2-3 different approaches with explicit trade-offs (complexity, performance, maintainability)
- Lead with your recommendation and explain why
- Never present only one option

### Phase 4: Present Design

- Break the design into sections of 200-300 words each
- Ask after each section whether it looks right before continuing
- Cover architecture, components, data flow, error handling, and testing
- Be ready to backtrack and re-clarify
- Never dump the entire design in one massive message

### Phase 5: Document and Proceed

- Write the validated design to `docs/plans/YYYY-MM-DD--design.md`
- Commit the design document; it belongs in version control alongside the code
- Ask "Ready to set up for implementation?"

## Question Patterns

**Good: multiple choice**
```
How should we handle authentication?

1. JWT tokens (stateless, scalable)
2. Session cookies (simpler, server-managed)
3. OAuth delegation (external provider)

Which fits your needs?
```

**Good: focused open-ended**
```
What should happen when a user's session expires mid-operation?
```

**Bad: multiple questions at once**
```
What auth method? How should errors be handled? What about rate limiting?
```

**Bad: leading question**
```
You want JWT tokens, right?
```

## YAGNI Ruthlessly

- Remove unnecessary features from every design
- Challenge every "nice to have"
- Ask "Do we need this for v1?"
- Never add features "while we're at it"
- Never design for hypothetical future requirements

## Design Document Template

```markdown
# [Feature Name] Design

**Goal:** [One sentence]

**Constraints:**
- [List constraints]

## Architecture

[2-3 sentences + diagram if helpful]

## Components

### [Component 1]
- Purpose:
- Inputs:
- Outputs:
- Error cases:

## Data Flow

[Sequence or flow description]

## Error Handling

| Error | Response |
|-------|----------|
| ... | ... |

## Testing Strategy

- Unit: [what]
- Integration: [what]
- Edge cases: [list]

## Open Questions

- [ ] [Any unresolved decisions]
```

## Red Flags

If you catch yourself doing any of these, STOP and return to the appropriate phase:

- Starting to write code before the design is validated
- Presenting the entire design at once
- Asking multiple questions in one message
- Offering only one approach
- Adding features "just in case"
- Silently filling in ambiguous requirements instead of asking

## Verification

Before proceeding to planning, confirm:

- [ ] You understand the existing project state and patterns
- [ ] All ambiguous requirements were clarified one question at a time
- [ ] 2-3 approaches were presented with trade-offs and a recommendation
- [ ] The design covers architecture, components, data flow, error handling, and testing
- [ ] The human has reviewed and approved each section
- [ ] The design document is saved to `docs/plans/` and committed

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jagreehal](https://github.com/jagreehal)
- **Source:** [jagreehal/jagreehal-claude-skills](https://github.com/jagreehal/jagreehal-claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jagreehal-jagreehal-claude-skills-design-exploration
- Seller: https://agentstack.voostack.com/s/jagreehal
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.