mvp-creator git:20260714.7bc748dA

Immutable. This exact content is served forever at /api/v1/blob/a1dba6bf97fe116a.

---
name: mvp-creator
description: Create comprehensive MVP documentation for Rails applications. Use this skill whenever a user describes a new app idea, wants to explore a SaaS concept, needs competitor research, or is starting a new project from scratch — even if they don't explicitly say "MVP". Triggers on "I have an idea for...", "I want to build...", "help me plan...", "research competitors for...", "create a business plan for...", "design a brand for my app", "set up Claude for my Rails project", "bootstrap an app", or any request to plan, research, or document a new application concept.
---

# MVP Creator

Create comprehensive MVP documentation for Rails applications through guided research and discovery.

## Overview

This skill produces 5 deliverables for a new Rails application:

1. **Research Report** — Competitor analysis, market overview, feature comparison
2. **MVP Business Plan** — Vision, features, user flows, success metrics
3. **Brand Guide** — Logo, colors, typography, components, voice
4. **Technical Guide** — Architecture, patterns, data models, code style
5. **Claude Setup** — CLAUDE.md, .mcp.json, commands for Claude Desktop/Code

## Workflow

```
Topic/Idea → Research → Discovery Questions → Generate Deliverables → Handoff to SDD
```

### Phase 1: Research

When user provides a topic or app idea:

1. Conduct web search for 2-5 similar apps/competitors
2. Research business models, features, pricing
3. Identify market gaps and opportunities
4. Present findings and ask for feedback before proceeding

**Output:** Research Report (saved to `docs/RESEARCH_REPORT.md`)

### Phase 2: Discovery Questions

After research is approved, gather project-specific information using the templates in the **Discovery Question Templates** section below. Do not re-list the questions here — go directly to the templates.

Ask the Core Questions first. Ask Feature Questions after research review. Ask Brand Questions just before generating the Brand Guide.

### Phase 3: Generate Deliverables

Generate each deliverable sequentially. **Before presenting any deliverable, run its checklist from the Quality Checklist section below.** Get approval before moving to the next.

1. **MVP Business Plan** → `docs/MVP_BUSINESS_PLAN.md`
   - Template: [mvp-business-plan.md](references/deliverable-templates/mvp-business-plan.md)
2. **Brand Guide** → `docs/BRAND_GUIDE.md` (with logo SVGs generated inline — see Logo Generation below)
   - Template: [brand-guide.md](references/deliverable-templates/brand-guide.md)
   - Reference: [rails-ui-patterns.md](references/rails-ui-patterns.md)
   - Use **`frontend-design` skill** only for UI screen mockups, not for the brand guide itself
3. **Technical Guide** → `docs/TECHNICAL_GUIDE.md`
   - Template: [technical-guide.md](references/deliverable-templates/technical-guide.md)
   - References: [rails-philosophy.md](references/rails-philosophy.md), [rails-implementation-patterns.md](references/rails-implementation-patterns.md)
   - If the app requires a JSON API (mobile app, external integrations): also load [rails-api-patterns.md](references/rails-api-patterns.md)
4. **Claude Setup** → `CLAUDE.md`, `.mcp.json`, `.claudeignore`, `.claude/commands/`
   - Template: [claude-setup.md](references/deliverable-templates/claude-setup.md)

### Phase 4: Handoff to SDD

After all deliverables are approved, always suggest:

> "Your MVP foundation is ready. The natural next step is to initialize Spec-Driven Development and convert these documents into feature specs, task breakdowns, and implementation prompts for Claude Code. Start with:
>
> *'Initialize SDD using the MVP documents we created.'*"

---

## Technical Stack (Non-Negotiable)

All projects use this Rails stack. See [rails-philosophy.md](references/rails-philosophy.md) for the "why".

| Component | Choice | Reference |
|-----------|--------|-----------|
| Framework | Rails 8.x | Vanilla Rails |
| Frontend | Hotwire (Turbo + Stimulus) | No JS frameworks |
| CSS | Tailwind CSS 4 | CSS-first config |
| Components | maquina_components | [maquina.app](https://maquina.app/documentation/components/) |
| Database | SQLite (dev) / PostgreSQL (prod) | Solid Queue/Cache/Cable |
| Auth | Rails 8 built-in | Not Devise |
| Testing | Minitest + Fixtures | Not RSpec |
| Deployment | Kamal 2 | Docker-based |

### Architecture Patterns

- Rich domain models with concerns (no service objects)
- CRUD resources for everything (no custom actions)
- State as records, not booleans
- Money as integer cents
- Turbo Morph by default, Frames sparingly

See [rails-implementation-patterns.md](references/rails-implementation-patterns.md) for the "how".

---

## Discovery Question Templates

### Core Questions (Always Ask First)

```
I'd like to learn more about your app idea to create comprehensive documentation.

1. **App Name:** Do you have a name in mind? If it has meaning in another language, what does it mean?

2. **Core Problem:** In one sentence, what problem does this app solve?

3. **Target Users:** Who is the primary user? (demographics, behaviors, pain points)

4. **Region:** Any geographic focus? (affects language, payment methods, API availability)

5. **Differentiator:** What makes this different from existing solutions?
```

### Feature Questions (After Research Review)

```
Based on my research, I have some feature questions:

1. **Main Sections:** What are the primary app sections/tabs?
   (e.g., Today, Transactions, Settings)

2. **Critical Flow:** What's the ONE action that must be fast and frictionless?
   (This becomes the UX we obsess over)

3. **Data Model:** What are the main things users create/track?
   (e.g., transactions, projects, bookings)
```

### Brand Questions (Before Brand Guide)

```
Before I create the brand guide:

1. **Personality:** How should the app feel?
   - Professional / Playful
   - Minimal / Bold
   - Serious / Friendly

2. **Colors:** Any preferences or brand colors to incorporate?
   Or should I propose a palette based on the app's personality?

3. **Logo:** Want me to create SVG logo proposals?
   I can generate 2-3 concepts representing the app's core idea.
```

---

## Logo Generation

Always generate logos yourself, as SVG code written inline in the Brand Guide (rather than delegating to another skill).

1. **Concept first:** Describe the visual metaphor before generating SVG
2. **Simple shapes:** Use basic geometric forms only
3. **Two versions:** Full logo (wordmark + icon) + standalone icon/mark
4. **Monochrome requirement:** Must be legible in a single color

Example approach:
```
The logo represents [concept]. Using [shape] to symbolize [meaning].
Primary version: [description]
Icon version: [description]
```

Then generate actual SVG code inline in the brand guide.

---

## Interaction Patterns

### Starting a New Project

User: "Help me create an MVP for a personal finance app"

Response:
1. Acknowledge the idea
2. Conduct web research (2-5 competitors)
3. Present research findings
4. Ask Core discovery questions
5. Generate deliverables sequentially with approval gates

### Continuing Previous Work

User: "Let's continue with the brand guide"

Response:
1. Summarize what is known so far
2. Ask Brand Questions if not yet answered
3. Generate the brand guide
4. Ask for feedback before moving on

### Specific Deliverable Request

User: "Just create a technical guide for my app called Resto"

Response:
1. Ask minimum required questions (stack preferences, locale, key features)
2. Load technical guide template and Rails references
3. Generate the technical guide
4. Save to `docs/TECHNICAL_GUIDE.md`

### Revising a Deliverable

User: "The brand guide doesn't feel right — too corporate"

Response:
1. Acknowledge specifically what missed the mark
2. Ask 1–2 targeted questions to redirect (e.g., "What aesthetic would feel more right — can you point to an app or brand as reference?")
3. Re-generate the deliverable from scratch rather than patching it
4. Note explicitly what changed in the new version

---

## Quality Checklist

Run the relevant checklist before presenting each deliverable.

### Research Report
- [ ] 2-5 competitors analyzed
- [ ] Feature comparison matrix included
- [ ] Differentiation opportunities identified
- [ ] Sources cited

### MVP Business Plan
- [ ] Clear problem statement
- [ ] User personas defined
- [ ] Feature set organized by section
- [ ] User flows documented
- [ ] Success metrics defined

### Brand Guide
- [ ] Logo SVG code included (primary + icon), generated inline
- [ ] Full color palette with hex values
- [ ] Typography scale defined
- [ ] Component patterns documented
- [ ] Tailwind CSS @theme configuration included
- [ ] Bilingual voice examples (if applicable)

### Technical Guide
- [ ] Tech stack decisions documented
- [ ] File organization defined
- [ ] Data models with relationships
- [ ] Turbo patterns specified
- [ ] I18n strategy with file structure
- [ ] Anti-patterns listed

### Claude Setup
- [ ] CLAUDE.md with project context
- [ ] .mcp.json configured
- [ ] .claudeignore comprehensive
- [ ] Custom commands created
- [ ] Setup instructions included

---

## Output File Structure

```
[project_name]/
├── docs/
│   ├── RESEARCH_REPORT.md
│   ├── MVP_BUSINESS_PLAN.md
│   ├── BRAND_GUIDE.md
│   ├── TECHNICAL_GUIDE.md
│   └── assets/
│       ├── logo.svg
│       └── logo-icon.svg
├── CLAUDE.md
├── .mcp.json
├── .claudeignore
└── .claude/
    └── commands/
        ├── test.md
        ├── db.md
        ├── analyze.md
        ├── generate.md
        └── guide.md
```

---

## Tips

1. **Show, don't tell** — ground every deliverable in concrete examples from the user's own domain.
2. **Bilingual by default** — for a LATAM or multilingual audience, show Spanish/English examples throughout.

(The core discipline — research first, ask before assuming, one deliverable at a time with approval — is the Workflow above.)

---

## Related Skills

| Skill | When to Use |
|-------|-------------|
| `frontend-design` | UI screen mockups and design rationale — after brand guide is approved |
| `spec-driven-development` | Implementation planning — convert MVP docs into specs and tasks |
| `maquina-ui-standards` | When building UI for Rails apps with maquina_components |