# Design

> Create PRDs through structured decision-tree interviews — designing, speccing, scoping. Walks every branch of the design tree, sweeps for gray areas, writes a PRD.

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

## Install

```sh
agentstack add skill-bugroger-beastmode-design
```

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

## About

# /design

Create PRDs through structured decision-tree interviews and collaborative dialogue.

## Guiding Principles
- No implementation until PRD is approved. No Plan Mode — this skill operates in normal mode. EnterPlanMode/ExitPlanMode restrict Write/Edit tools and break the workflow.
- The session-start hook injects a metadata block into the session context with `epic-id`, `epic-slug`, and `output-target`. Use these values verbatim — do NOT re-derive, re-extract, or generate alternatives.
- Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a PRD and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
- **Every feature gets a PRD.** A config change, a single-function utility, a rename — all of them. Short is fine; skipping is not.
- **The user frames the problem.** Their words drive the design. Ask before exploring; listen before loading context.
- **Decision tree before document.** Walk every branch, sweep for gray areas, then write. The PRD is the output, not the process.
- **Scope is protected by default.** New capabilities get deferred unless the user explicitly pulls them in.

## Phase 0: Pre-Execute

### 1. Problem-First Question

Before exploring the codebase, ask the user what they are trying to solve.

**Do NOT:**
- Explore the codebase yet
- Load project context yet

Wait for the user's response. Their framing drives the entire design — do not proceed until they answer.

### 2. Express Path Check

If the user's response points to an existing PRD, spec, or requirements document (not a `.beastmode/artifacts/design/` file):
1. Read the document
2. Skip decision tree walk in execute
3. Jump directly to "Gray Areas" (Execute step 2) with the doc as input

### 3. Existing Design Check

If a prior PRD exists for the same topic (matching feature name):
- Ask: "Found existing PRD for this topic. What do you want to do?"
- Options: Update existing / View first / Start fresh

## Phase 1: Execute

### 1. Walk the Decision Tree

Interview the user about every aspect of this feature. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.

Rules:
1. Ask questions one at a time
2. For each question, provide your recommended answer
3. If a question can be answered by exploring the codebase, explore the codebase instead of asking
4. If a question requires research (unfamiliar technology, external APIs, best practices), spawn an Explore agent as the researcher. It receives the research topic and returns findings with sources. Save findings to `.beastmode/artifacts/research/YYYY-MM-DD-.md`
5. Honor prior decisions from pre-execute checks — don't re-ask settled questions
6. Scope guardrail: new capabilities get deferred
   "That sounds like its own feature — I'll note it as a deferred idea. Back to the current branch."
7. Track deferred ideas internally
8. Continue until all branches of the decision tree are resolved

### 2. Gray Area Sweep

Second pass to catch big-picture blind spots the decision tree may have missed.

Maintain a session-scoped list of resolved gray areas. Never re-present a resolved area.

**Loop:**

1. Analyze remaining ambiguity (excluding resolved areas), rank by ambiguity level
2. If 0 gray areas remain → sweep complete, proceed to step 3
3. Present the single most ambiguous gray area via `AskUserQuestion` with `multiSelect: false`
   - Options: relevant resolution choices for that gray area (recommendation first)
   - Annotate with codebase context when relevant
4. If the user responds via Other with a bail-out intent (skip, done, move on, etc.) → exit loop immediately
5. Resolve the gray area based on the selected option or freeform input
   - Scope guardrail: defer new capabilities
6. Add to session-scoped resolved list
7. Loop back to step 1

### 3. Iterate Until Ready for Validation

- Go back and clarify as needed
- Keep YAGNI in mind — remove unnecessary features
- PRD is ready when decision tree + gray areas are all resolved

## Phase 2: Validate

### 1. Completeness Check

Verify PRD covers all required sections:
- [ ] Problem Statement
- [ ] Solution
- [ ] User Stories (3+ items)
- [ ] Implementation Decisions
- [ ] Testing Decisions
- [ ] Out of Scope
- [ ] Further Notes (or "none")
- [ ] Deferred ideas captured (or "none")

If missing sections, go back to Execute phase.

### 2. Anti-Pattern Check

If the PRD produced fewer than 3 user stories, print:

"This is a lightweight PRD — that's fine. Even simple features benefit from explicit approval to prevent wasted implementation."

Do NOT skip approval. Short PRDs still need approval.

### 3. Executive Summary

Before asking for approval, present a consolidated executive summary so the user can review the full picture in one place.

Print:

```
### Executive Summary

**Problem**: [one-sentence problem statement]

**Solution**: [one-sentence solution summary]

**Key Decisions:**

| Decision | Choice |
|----------|--------|
| [decision 1] | [choice] |
| [decision 2] | [choice] |
| ... | ... |

**User Stories:** [count] stories covering [summary of scope]
```

Render this from the decisions and stories gathered during the execute phase. Do NOT ask new questions — this is a read-only summary of what was already discussed.

### 4. PRD Approval

Ask: "Does this PRD look complete? Ready to document?"

Options:
- Yes, document it
- No, let's revise [specify what]

Wait for user response before continuing.

## Phase 3: Checkpoint

### 0. Derive Epic Name

Derive a NEW human-readable **name** from the problem statement and solution discussed during the interview:
- **epic-name**: A short, human-readable title (e.g. "Dashboard Redesign for Log Events"). Not slugified — natural language, title case. The CLI slugifies this automatically for the epic slug.

- Log: "Derived name: ``"

### 1. Write PRD

Save to the path specified by `output-target` in the session metadata block.

In the PRD frontmatter:
- `epic-id`: from session metadata (verbatim)
- `epic-slug`: from session metadata (verbatim)
- `epic-name`: the human-readable name from step 0

Use the PRD template from the Reference section below.

### 2. Commit and Handoff

Commit all work to the feature branch:

```bash
git add -A
git commit -m "design(): checkpoint"
```

Print:

```
Next: beastmode plan 
```

STOP. No additional output.

## Reference

### PRD Template

```
---
phase: design
epic-id: 
epic-slug: 
epic-name: 
---

## Problem Statement

[The problem from the user's perspective]

## Solution

[The solution from the user's perspective]

## User Stories

[Numbered list of user stories in format: As an , I want a , so that ]

## Implementation Decisions

[Flat list of implementation decisions made during the interview. Include:
- Interfaces that will be modified
- Technical clarifications
- Architectural decisions
- Schema changes, API contracts, specific interactions

Do NOT include specific file paths or code snippets — they may become outdated.]

## Testing Decisions

[Include:
- What makes a good test for this feature
- Prior art for tests (similar test patterns in the codebase)]

## Out of Scope

[Things explicitly excluded from this PRD]

## Further Notes

[Additional context, or "None"]

## Deferred Ideas

[Ideas that came up during the interview but were deferred as separate features, or "None"]
```

## Source & license

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

- **Author:** [BugRoger](https://github.com/BugRoger)
- **Source:** [BugRoger/beastmode](https://github.com/BugRoger/beastmode)
- **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-bugroger-beastmode-design
- Seller: https://agentstack.voostack.com/s/bugroger
- 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%.