MVP Design Skill

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