mvp-design

name	mvp-design
description	Use when designing new modules from scratch, creating minimal viable prototypes, or establishing architectural decisions before implementation
version	1

MVP Design Skill

Overview

This skill guides the design of minimal, production-ready code prototypes with clear architecture and self-documenting code, emphasizing design decisions over implementation details.

Design minimal, production-ready code prototypes with clear architecture and self-documenting code.

When to Use

Use this skill when you need to:

• Design a new module or subsystem from scratch
• Create a minimal viable prototype (MVP) for rapid iteration
• Establish coding patterns and architectural decisions
• Plan implementation before writing actual code
• Design replacement systems alongside existing ones

Core Principles

1. Code as Documentation

• Code itself is readable - clear naming, simple structure
• Minimal comments - code explains itself
• Self-documenting functions - verb-based naming, obvious parameters

2. Documentation as Design

• No code in documentation - code lives in the project
• Document "why", not "how" - architectural decisions and rationale
• Focus on design patterns - data flow, component interaction
• Interface contracts - what goes in, what comes out

3. Minimal Viable Scope

• 5-6 files maximum - forces focus on essentials
• 500 lines of code - small enough to complete quickly
• Core functionality only - defer edge cases to later phases

4. Architectural Alignment

• Use existing infrastructure - leverage project's patterns
• Follow established conventions - naming, structure, serialization
• Zero-intrusive design - parallel development, not replacement

Workflow

Phase 1: Architecture Definition

1. Identify Core Data Structure

   • What is the fundamental entity?
   • Example: MissionInstance (id, kind, status, progress, target)

2. Define Primary Operations

   • What actions can be performed?
   • Example: Participate, AddProgress, AcceptReward

3. Map Infrastructure Dependencies

   • What existing systems to leverage?
   • Example: Tinker serialization, SharedTable config, NetMessage

4. Establish Design Decisions

   • Document "why" for each major choice
   • Example: "Use Save/Load methods for Tinker compatibility"

Phase 2: Component Design

1. List Required Files

   • Header + Implementation pairs
   • Configuration files
   • Maximum 6 files

2. Define Component Responsibilities

   • What each file does
   • How components interact

3. Design Data Flow

   • Input → Processing → Output
   • Serialization path
   • Database interaction

4. Specify Interface Contracts

   • Function signatures
   • Input/output types
   • Error handling approach

Phase 3: Documentation Production

Structure:

# [ModuleName] MVP Design

## 1. Core Architecture
[Architecture diagram showing components and relationships]

## 2. File Inventory
| File | Path | Responsibility |

## 3. Key Design Decisions
[Document "why" for each major decision]

## 4. Implementation Checklist
[Phase-by-phase checklist]

## 5. Integration Points
[How it connects to existing systems]

## 6. Testing Strategy
[How to verify it works]

Design Decisions Template

For each major decision, document:

### Decision: [Name]

**Choice**: [What was decided]

**Alternatives Considered**:
- Option A: [Description] → Rejected because [reason]
- Option B: [Description] → Rejected because [reason]

**Rationale**:
- [Why this choice]
- [Benefits]
- [Trade-offs]

**Impact**:
- [How it affects other components]
- [Future considerations]

Best Practices

✅ Do

• Focus on architecture and design
• Document "why" not "how"
• Keep scope minimal (5-6 files)
• Align with existing patterns
• Use clear, consistent naming

❌ Don't

• Include actual code in documentation
• Over-engineer for edge cases
• Ignore existing conventions
• Skip design rationale
• Expand scope mid-design

Example Output Structure

# PlayerMissionSystem MVP Design

## 1. Core Architecture

[MissionInstance] → [PlayerMissionSystem] → [DatabaseMethod] ↓ [MissionConfigData]

## 2. File Inventory

| File | Path | Responsibility |
|------|------|----------------|
| MissionDefines.h | WorldServer/ | Enums and utilities |
| MissionInstance.h | WorldServer/ | Data structure with Save/Load |
| PlayerMissionSystem.h/cpp | WorldServer/ | Core system implementation |

## 3. Key Design Decisions

### Decision: Use Tinker Save/Load

**Choice**: MissionInstance uses Tinker Save/Load methods

**Alternatives**:
- RTS_PACK → Rejected: bitwise copy too restrictive
- Manual serialization → Rejected: error-prone

**Rationale**:
- Type-safe, extensible
- Consistent with project direction
- Easy to add fields later

## 4. Implementation Checklist

### Phase 1: Data Structures
- [ ] MissionInstance with Save/Load
- [ ] MissionConfigData table structure

### Phase 2: Core System
- [ ] PlayerMissionSystem class
- [ ] Participate, AddProgress, AcceptReward methods

### Phase 3: Integration
- [ ] DatabaseMethod additions
- [ ] Player.h integration

## 5. Integration Points

- Uses: Tinker serialization, SharedTable, NetMessage
- Extends: PlayerSubsystem pattern
- Database: player_mission table

## 6. Testing Strategy

- Unit: MissionInstance Save/Load roundtrip
- Integration: Login → Load → Update → Verify

Integration with Other Skills

• code-analysis: Understand existing patterns before designing
• code-generator: Generate implementation from design docs
• knowledge-base-cache: Store design patterns for reuse

Version History

• v1.0 (2026-02-10) - Initial release
  • Code-as-documentation principles
  • 3-phase workflow
  • Design decision template