brainstorm-prompt-optimizer

ブレインストーミング用プロンプトオプティマイザー

生のアイデアを、ブレインストーミングのワークフロー（/specs.brainstorm）にそのまま使える最適化済みプロンプトに変換します。

このスキルでは、アイデアを準備することで、/specs.brainstorm に渡したときに、EARS 構文、適切な受け入れ基準の分類、完全な「非目標」／「禁止要件」セクションに沿った、より優れた機能仕様を作成できるようにします。

使用する場合

• ユーザーが /specs.brainstorm を実行する前にアイデアを最適化したい場合
• ユーザーが「このアイデアをブレインストーミング用に準備して」「ブレインストーミング用に強化して」と言った場合
• ユーザーがシンプルなアイデアを提示し、より良いブレインストーミング結果を得るために構造化したい場合
• ユーザーが「これをブレインストーミング用に整えて」と尋ねた場合
• ユーザーが「imposta per brainstorm」「prepara idea per brainstorm」と言った場合

使用しない場合

• ユーザーがコードやパフォーマンスの最適化を求めている場合（適切なスキルを使用してください）
• ユーザーが一般的なプロンプトエンジニアリングを求めている場合（prompt-engineering スキルを使用してください）
• ユーザーが既存のプロンプトの分析を求めている場合
• ユーザーがタスクの直接実行を求めている場合
• ユーザーがバグの修正や既存の動作の変更を求めている場合 → specs.change-spec に振り分けてください

動作の仕組み

最適化済みプロンプトのみを出力してください — 分析、レポート、提案は出力しないでください。

このワークフローでは、生のアイデアを構造化されたプロンプトに変換します。これを /specs.brainstorm で使用すると、より優れた機能仕様を作成できます。

ワークフロー

フェーズ 1：プロジェクトのコンテキストを検出する

プロジェクトファイルを確認し、環境を把握します。

• CLAUDE.md → プロジェクトの規約
• docs/specs/architecture.md → 既存のアーキテクチャ上の制約
• docs/specs/ontology.md → 既存のドメイン用語

技術スタックの検出：

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

フェーズ 2：アイデアを分析する

生のアイデアを解析して、以下を特定します。

1. 中核となるアクション：何を構築／作成する必要があるか（例：「認証を追加する」「検索を作成する」）
2. 対象ドメイン：システムのどの部分が影響を受けるか
3. 暗黙のスコープ：自然に含まれるものと、除外されるもの
4. ユーザーの視点：この機能によって誰がメリットを得るか
5. ビジネス価値：この機能が重要な理由

フェーズ 3：スコープの規模を特定する

/specs.brainstorm の参考となるよう、複雑さを見積もります。

• 小規模：単一のユーザーストーリー、1～3 個のエンティティ、シンプルなフロー → 3～8 個のタスク
• 中規模：2～4 個のユーザーストーリー、4～8 個のエンティティ → 8～15 個のタスク
• 大規模：5 個以上のユーザーストーリー、9 個以上のエンティティ → 分割が必要な場合があります（ユーザーに警告します）

フェーズ 4：最適化済みプロンプトを構成する

以下の要素を使って構造化されたプロンプトを作成します（/specs.brainstorm のテンプレートに準拠）。

# [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]

フェーズ 5：最適化済みプロンプトを出力する

完全な最適化済みプロンプトを、ラベル 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]
- **Secondary**: [other affected users]

## User Flows
1. **Primary Flow**: [Step by step from user perspective]
2. **Alternative Flow**: [If applicable]

## Data Requirements
- User entity: [fields]
- [Other entities involved]

## Success Criteria
- [IMP] [Criterion 1 — testable outcome requiring code]
- [IMP] [Criterion 2]
- [SEF] [Criterion 3 — automatic consequence]
- [EXT] [Criterion 4 — verified externally]

## Non-Goals
- **Social Login**: No OAuth providers (Google, GitHub, etc.)
- **Password Reset**: Not included in this specification
- **Two-Factor Auth**: Not included in this specification

## Negative Requirements
- REQ-NR001: The system SHALL NOT store passwords in plain text; it SHALL use bcrypt with cost factor ≥12
- REQ-NR002: The system SHALL NOT expose user existence through login error messages

API とバックエンドの機能

# [Feature Name] — API Layer

## Problem Statement
[What integration need or capability gap exists]

## Core Feature
The system SHALL provide [describe the API behavior]

## Target Users
- **Primary**: [API consumers]
- **Secondary**: [administrators]

## User Flows
1. **Happy Path**: [Request → Validation → Response]
2. **Error Path**: [Invalid input → Error response]

## API Contract
- Endpoint: [path and method]
- Input: [what the API receives]
- Output: [what the API returns]
- Error cases: [failure modes with codes]

## Data Model
- [Entities involved]
- [Relationships]

## Success Criteria
- [IMP] [Criterion 1]
- [IMP] [Criterion 2]
- [SEF] [Criterion 3]

## Non-Goals
- **GraphQL**: REST only
- **Async Processing**: Synchronous only
- **Caching**: Not included

## Negative Requirements
- REQ-NR001: IF user input is used in SQL query THEN the system SHALL NOT concatenate directly
- REQ-NR002: The system SHALL NOT expose internal error details to clients

UI とフロントエンドの機能

# [Feature Name] — User Interface

## Problem Statement
[What user experience gap exists]

## Core Feature
The user SHALL be able to [describe user action and system response]

## Target Users
- **Primary**: [end users]
- **Secondary**: [admin users if applicable]

## User Flows
1. **Entry**: [How user accesses this feature]
2. **Interaction**: [Primary user action]
3. **Outcome**: [Result user sees]
4. **Error**: [Error handling for invalid input]

## UI Requirements
- Layout: [description]
- Components: [key UI elements]
- Feedback: [success/error/loading states]

## Responsive Behavior
- Desktop: [behavior]
- Mobile: [behavior]

## Success Criteria
- [IMP] [Criterion 1 — visible behavior]
- [IMP] [Criterion 2]
- [IMP] [Criterion 3]
- [SEF] [Criterion 4 — automatic]

## Non-Goals
- **Real-time Updates**: No WebSocket or SSE
- **Offline Mode**: Not included
- **Accessibility Features**: [specific exclusions]

## Negative Requirements
- REQ-NR001: The system SHALL NOT display raw error messages to users
- REQ-NR002: The system SHALL NOT allow XSS through user input fields

データと処理の機能

# [Feature Name] — Data Processing

## Problem Statement
[What data challenge exists]

## Core Feature
The system SHALL [describe data transformation/processing behavior]

## Target Users
- **Primary**: [who benefits]
- **Secondary**: [who monitors]

## User Flows
1. **Data Input**: [Source and format]
2. **Processing**: [Transformation steps]
3. **Output**: [Result destination and format]

## Data Quality
- Validation: [rules]
- Error handling: [for bad data]

## Performance Constraints
- Volume: [expected data size]
- Latency: [expected processing time]

## Success Criteria
- [IMP] [Criterion 1]
- [IMP] [Criterion 2]
- [EXT] [Criterion 3 — external verification]

## Non-Goals
- **Real-time Processing**: Batch only
- **Data Export**: Not included
- **Backup/Restore**: Not included

## Negative Requirements
- REQ-NR001: The system SHALL NOT lose data on processing failure
- REQ-NR002: The system SHALL NOT process unbounded data without pagination

---

例

例 1：シンプルなアイデア → 最適化

入力：

Add user authentication

出力：

# Add User Authentication — Authentication Layer

## Problem Statement
Users cannot securely access the system. They need a way to prove their identity and access their personalized content.

## Core Feature
The system SHALL provide email/password authentication that allows users to:
- Register with a valid email address and secure password
- Log in with registered credentials
- Maintain an authenticated session across requests
- Log out to terminate their session

## Target Users
- **Primary**: End users who need to access personalized features
- **Secondary**: Administrators who manage user accounts

## User Flows
1. **Registration**: User enters email → receives confirmation → sets password → account created
2. **Login**: User enters credentials → validated → session established → redirected to dashboard
3. **Logout**: User clicks logout → session terminated → redirected to login page

## Data Requirements
- User entity: email, hashed_password, created_at, updated_at
- Session entity: user_id, token, expiration

## Success Criteria
- [IMP] Users can register with email/password
- [IMP] Users can log in with valid credentials
- [IMP] Invalid credentials show generic error message
- [IMP] Users can log out
- [IMP] Session persists across page navigation
- [IMP] Expired sessions require re-login

## Non-Goals
- **Social Login**: No OAuth providers (Google, GitHub, etc.)
- **Password Reset**: Not included in this specification
- **Two-Factor Authentication**: Not included in this specification

## Negative Requirements
- REQ-NR001: The system SHALL NOT store passwords in plain text; it SHALL use bcrypt with cost factor ≥12
- REQ-NR002: The system SHALL NOT expose user existence through login error messages; it SHALL use generic "invalid credentials" for both cases
- REQ-NR003: The system SHALL NOT allow weak passwords (minimum 8 characters, mixed case, number)

例 2：曖昧なアイデア → 構造化

入力：

Better search for products

出力：

# Improve Product Search — Product Discovery

## Problem Statement
Users cannot find products they are looking for using the current search. Results are not relevant, don't match user intent, and sorting is not useful.

## Core Feature
The system SHALL provide enhanced product search that allows users to:
- Search products by name, description, and category
- Receive results ranked by relevance to search terms
- Filter results by category, price range, and availability
- Sort results by relevance, price, or newest

## Target Users
- **Primary**: Shoppers looking for specific products
- **Secondary**: Browsers exploring product catalog

## User Flows
1. **Direct Search**: User enters search terms → results displayed → user selects product
2. **Filtered Search**: User enters terms → applies filters → refined results → user selects product
3. **Empty Results**: User enters terms → no results → suggestion displayed

## Search Behavior
- Minimum 2 characters to trigger search
- Partial word matching for product names
- Search across: product name, description, category name, tags
- Results limited to 50 per page with pagination

## Filtering Options
- Category: single or multiple selection
- Price range: min/max with validation
- Availability: in-stock only toggle

## Sorting Options
- Relevance (default): based on search term match score
- Price: low-to-high or high-to-low
- Newest: by creation date descending

## Success Criteria
- [IMP] Search returns products matching the query terms
- [IMP] Search supports partial word matching
- [IMP] Category filter limits results to selected category
- [IMP] Price range filter shows products within min/max bounds
- [IMP] Results can be sorted by relevance, price, or date
- [IMP] Pagination allows navigation through large result sets
- [IMP] Empty search shows appropriate message with suggestions

## Non-Goals
- **Autocomplete**: Not included in this specification
- **Search Analytics**: Not included in this specification
- **Personalized Results**: Results are the same for all users
- **Image Search**: Not included in this specification

## Negative Requirements
- REQ-NR001: The system SHALL NOT expose product inventory details in search results unless explicitly needed
- REQ-NR002: The system SHALL NOT allow SQL injection through search terms; it SHALL sanitize all input
- REQ-NR003: The system SHALL NOT return results beyond configured pagination limits per request

例 3：技術的なアイデア → 機能的な表現

入力：

Implement Redis caching for API responses

出力：

# Implement API Response Caching — Performance Optimization

## Problem Statement
The API is slow for frequently requested data. Repeated requests for the same resources consume unnecessary server resources and increase response times for users.

## Core Feature
The system SHALL cache frequently accessed API responses to reduce response times and server load:
- Cache GET requests for defined intervals
- Return cached responses when data hasn't changed
- Invalidate cache when underlying data changes
- Provide cache statistics for monitoring

## Target Users
- **Primary**: API consumers (frontend applications, mobile apps)
- **Secondary**: System administrators monitoring performance

## Cache Behavior
- Cache key based on request URL and parameters
- Default TTL: 5 minutes (configurable per endpoint)
- Cache stores: response body, status code, headers
- Cache miss: fetch from source, store, return

## Invalidation Rules
- Cache invalidated when source data is modified via POST/PUT/PATCH/DELETE
- Manual invalidation available via admin endpoint
- Bulk invalidation by cache key pattern

## Success Criteria
- [IMP] Cached requests return within 50ms
- [IMP] Cache hit rate visible in metrics
- [IMP] Manual cache invalidation works
- [IMP] Automatic invalidation on data changes
- [IMP] Cache can be disabled per request via header
- [SEF] Cache reduces database load for repeated requests
- [EXT] Response time improvement measurable via APM

## Non-Goals
- **Distributed Cache**: Single Redis instance only
- **Cache Warming**: Not included
- **Cache Partitioning**: Not included
- **Multi-Tenant Isolation**: Not included in this specification

## Negative Requirements
- REQ-NR001: The system SHALL NOT cache responses containing user-specific data
- REQ-NR002: The system SHALL NOT serve stale cache beyond configured TTL
- REQ-NR003: The system SHALL NOT expose cache internals in API responses
- REQ-NR004: IF cache connection fails THEN the system SHALL fall back to direct database access without error

---

ブレインストーミングとの連携

最適化済みプロンプトは、/specs.brainstorm でそのまま使用してください。

# Copy the optimized prompt and use it with brainstorm
/specs.brainstorm [paste optimized prompt here]

ワークフロー

Raw Idea → brainstorm-prompt-optimizer → Optimized Prompt → /specs.brainstorm → Functional Spec → /specs.spec-to-tasks → Tasks

制約

• 最適化済みプロンプトのみを出力してください — 分析や提案は出力しないでください
• 入力がバグ修正または変更依頼の場合は、最適化せずに specs.change-spec に振り分けてください
• 入力が曖昧すぎて意味のある最適化ができない場合は、確認の質問を 1 つだけしてください
• 実装方法（HOW）ではなく、動作（WHAT）に焦点を当ててください
• スコープの拡大を防ぐため、「非目標」セクションを明示的に含めてください（最低 3 項目）
• セキュリティ／整合性の制約を示す「禁止要件」を含めてください（最低 2 項目）
• 要件には EARS 構文（SHALL/WILL/MAY）を使用してください
• すべての受け入れ基準に [IMP]、[SEF]、または [EXT] のいずれかのタグを付けてください
• [NEEDS CLARIFICATION] マーカーは最大 3 つまでにしてください

関連するコマンドとスキル

コンポーネント	使用するタイミング
/specs.brainstorm	最適化の後、ブレインストーミングを実行して仕様を作成します
/specs.spec-to-tasks	仕様を実行可能なタスクに変換します
specs-change-spec	バグ修正や差分変更の場合（新機能ではありません）
specs-brainstorm	機能仕様テンプレートの参考資料