/brainstorm-prompt-optimizer

name: brainstorm-prompt-optimizer
description: >
  Optimizes raw idea descriptions into structured prompts ready for the brainstorming workflow.
  TRIGGER when: user says "optimize for brainstorm", "prepare idea for brainstorm", "enhance this idea",
  "make this ready for brainstorming", "imposta per brainstorm", or wants to improve a feature idea 
  before using /specs.brainstorm.
  DO NOT TRIGGER for code optimization, refactoring, or general prompt engineering tasks.
allowed-tools: Read, Bash
model: inherit

Brainstorm Prompt Optimizer

Transform a raw idea into an optimized prompt ready for the brainstorming workflow (`/specs.brainstorm`).

This skill prepares ideas so that when passed to `/specs.brainstorm`, they produce better functional specifications following EARS syntax, proper acceptance criteria taxonomy, and complete Non-Goals/Negative Requirements sections.

When to Use

• User wants to optimize an idea before running `/specs.brainstorm`
• User says "prepare this idea for brainstorming", "enhance for brainstorm"
• User provides a simple idea and wants it structured for better brainstorming results
• User asks "make this ready for brainstorm"
• User says "imposta per brainstorm", "prepara idea per brainstorm"

Do Not Use When

• User wants code or performance optimization (use appropriate skills)
• User wants general prompt engineering (use prompt-engineering skill)
• User wants analysis of an existing prompt
• User is asking to execute a task directly
• User wants to fix a bug or modify existing behavior → route to `specs.change-spec`

How It Works

**Output ONLY the optimized prompt** — no analysis, no reports, no recommendations.

The workflow transforms a raw idea into a structured prompt that will produce better functional specifications when used with `/specs.brainstorm`.

Workflow

Phase 1: Detect Project Context

Check for project files to understand the environment:

• `CLAUDE.md` → project conventions
• `docs/specs/architecture.md` → existing architecture constraints
• `docs/specs/ontology.md` → existing domain terms

Tech stack detection:

• `package.json` → Node.js/TypeScript/React
• `pom.xml` / `build.gradle` → Java/Spring Boot
• `requirements.txt` / `pyproject.toml` → Python

Phase 2: Analyze the Idea

Parse the raw idea to identify: 1. **Core action**: What needs to be built/created (e.g., "add authentication", "create search") 2. **Target domain**: What part of the system is affected 3. **Implicit scope**: What's naturally included vs. excluded 4. **User perspective**: Who benefits from this feature 5. **Business value**: Why this feature matters

Phase 3: Identify Scope Size

Estimate complexity to help `/specs.brainstorm`:

• **Small**: Single user story, 1-3 entities, simple flow → 3-8 tasks
• **Medium**: 2-4 user stories, 4-8 entities → 8-15 tasks
• **Large**: 5+ user stories, 9+ entities → may need split (warn user)

Phase 4: Structure the Optimized Prompt

Build a structured prompt with these components (aligned with `/specs.brainstorm` template):

# [Core Action] — [Target Domain]

## Problem Statement
[What problem does this solve? Who has it?]

## Core Feature
[What should the system do? Focus on behavior, not implementation]

## Target Users
[Who will use this? What's their goal?]

## User Flows
1. [Primary flow from user perspective]
2. [Alternative flows if applicable]

## Data Requirements
- [What data the feature needs to work with]
- [Any data relationships]

## Success Criteria
- [IMP] [Testable criterion that requires code/implementation]
- [SEF] [Side-effect criterion - automatic consequence]
- [EXT] [External verification criterion]

## Non-Goals
- **Feature X**: [Brief explanation why excluded]
- **Feature Y**: [Brief explanation why excluded]

## Negative Requirements
- REQ-NR001: The system SHALL NOT [security/data integrity constraint]

## [NEEDS CLARIFICATION] (max 3)
- [Specific question that significantly impacts scope]

Phase 5: Output the Optimized Prompt

Present the complete optimized prompt in a fenced code block with the label `optimized-prompt`:

```optimized-prompt
[Full optimized prompt content]

---

## EARS Syntax Reference

Use EARS (Easy Approach to Requirements Syntax) for requirements:

| Form | Pattern | Example |
|------|---------|---------|
| **Event-driven** | `WHEN <event> THEN the system SHALL <action>` | `WHEN the user clicks "Submit" THEN the system SHALL validate the form data` |
| **State-driven** | `WHEN <system state> THEN the system SHALL <action>` | `WHEN the session expires THEN the system SHALL clear user data` |
| **Generic** | `The system SHALL <action>` | `The system SHALL encrypt all stored passwords with bcrypt` |
| **Feature** | `IF <feature> THEN the system SHALL <action>` | `IF multi-factor auth is enabled THEN the system SHALL require second factor` |
| **Negative** | `IF <unwanted condition> THEN the system SHALL NOT <action>` | `IF SQL input detected THEN the system SHALL reject with 400` |

Mandatory keywords: **SHALL**, **WILL**, **MAY**
Forbidden words: "robust", "intuitive", "fast", "scalable", "efficient", "user-friendly"

---

## Acceptance Criteria Taxonomy

Every success criterion MUST be tagged:

| Tag | Meaning | Generates Tasks? |
|-----|---------|------------------|
| `[IMP]` | Requires new code, configuration, or explicit behavior | **YES** |
| `[SEF]` | Natural automatic consequence of an `[IMP]` criterion | NO (verify in e2e) |
| `[EXT]` | Verified by external tools or user observation | NO (e2e checkpoint) |

**60% Rule**: At least 60% of criteria should be `[IMP]`.

---

## Prompt Templates by Category

### Authentication & User Management

```optimized-prompt
# Add [Feature] — User Management

## Problem Statement
[Describe the problem users face without this feature]

## Core Feature
The system SHALL [describe what the feature does, focus on behavior]

## Target Users
- **Primary**: [main user type]
-