/universal

allowed-tools: Task, Bash, Read, Write, Edit, MultiEdit, Grep, Glob, LS
name: "Universal Development Principles"
description: "Comprehensive development principles and best practices for AI assistants working on any project"
author: "rishabhsonker"
tags: ["development", "best-practices", "workflow", "mcp", "git", "code-quality"]
version: "1.0.0"
created_at: "2024-01-01T00:00:00Z"
updated_at: "2024-01-01T00:00:00Z"

Universal Development Principles

This document contains universal development principles and practices for AI assistants working on any project. These principles are derived from battle-tested practices and represent a philosophy of clear, honest, and systematic development.

Features

• **Mandatory MCP Tool Usage**: Required tools and research methods before any action
• **Clear Code Principles**: Write maintainable, obvious code without clever tricks
• **Honest Technical Assessment**: Provide realistic evaluation of technical decisions
• **Conventional Commits**: Standardized commit messages for better project history
• **Systematic Workflow**: Step-by-step development process with quality gates
• **Security First**: Built-in security requirements and best practices
• **Performance Optimization**: Measure-first approach to performance improvements

Usage

Basic Usage

# Follow the mandatory workflow before any coding task
mcp__Ref__ref_search_documentation "[technology] [feature] best practices 2025"
mcp__sequential-thinking__sequentialthinking  # For complex analysis
mcp__git__git_log --oneline -20  # Check recent commits

Advanced Usage

# Complete development workflow with quality gates
/explore [feature] → Write code → /qa → /commit
# Or for debugging: /debug → /map → Fix → /qa → /commit
# For maintenance: /cleanup → /refactor → /qa → /commit

Examples

Example 1: Starting a New Feature

Before implementing any feature, follow this systematic approach:

# 1. Research current state
mcp__git__git_log --oneline -20
mcp__git__git_grep "[feature_name]"

# 2. Research best practices
mcp__Ref__ref_search_documentation "[tech] [feature] implementation 2025"

# 3. Plan with sequential thinking
mcp__sequential-thinking__sequentialthinking

Example 2: Quality Assurance Process

Ensure code quality before completion:

# Validate code
mcp__ide__getDiagnostics

# Run quality checks
/qa [area]

# Create proper commit
/commit [type]

Configuration

Required Tools and Research Methods

1. Mandatory MCP Tool Usage

BEFORE ANY ACTION, you MUST use these tools. Tool names use double underscores between segments.

Documentation Research (ALWAYS FIRST)

# BEFORE writing ANY code, search ALL relevant docs:
mcp__Ref__ref_search_documentation "[language/framework] [feature] best practices 2025"
mcp__Ref__ref_search_documentation "[API name] documentation"
mcp__Ref__ref_search_documentation "[technology] [pattern] implementation"

# Read the actual documentation URLs found:
mcp__Ref__ref_read_url "[documentation URL from search]"

Sequential Thinking (FOR COMPLEX TASKS)

Use `mcp__sequential-thinking__sequentialthinking` for:

• ANY feature implementation (even "simple" ones have edge cases)
• Debugging ANY issue (systematic analysis beats guessing)
• Architecture decisions (consider all implications)
• Performance optimizations (measure, analyze, implement)
• Security implementations (threat model first)
• Refactoring plans (understand current state fully)
• API integrations (error cases, rate limits, costs)
• State management changes (race conditions, cleanup)

Git History Analysis

# BEFORE modifying ANY file:
mcp__git__git_log --oneline -20  # Recent commits
mcp__git__git_log [filename] -10  # File history
mcp__git__git_diff HEAD~1  # What changed recently

# When tests fail or CI issues:
mcp__git__git_log .github/workflows/ -10  # Workflow changes
mcp__git__git_show [commit_hash]  # Understand specific changes

# Before implementing features:
mcp__git__git_grep "[feature_name]"  # Find related code

Code Validation Requirements

# ALWAYS run before saying "done":
mcp__ide__getDiagnostics  # TypeScript/ESLint errors

2. Required Questions Before Implementation

ASK QUESTIONS. LOTS OF THEM.

**Before implementing features**:

• "What exact user experience are you envisioning?"
• "Should this be configurable? What are the defaults?"
• "How should this integrate with existing features?"

**For error handling**:

• "What should happen when this fails?"
• "Should errors be retried? How many times?"
• "What logging/monitoring would help debug issues?"

**For performance**:

• "Are there performance constraints I should consider?"
• "What's the expected behavior on slow networks/devices?"
• "How much data will this typically process?"

**For security**:

• "Are there security implications to consider?"
• "Does this handle user data? How should it be protected?"
• "Are there any compliance or regulatory requirements?"

**For maintenance**:

• "What's the migration path for existing users/data?"
• "How will this be tested?"
• "What documentation needs updating?"

NEVER ASSUME. ALWAYS CLARIFY.

Code Quality Standards

Clear Code Principles

Write code as if the person maintaining it is a violent psychopath who knows where you live:

• **NO CLEVER TRICKS**: Clear, obvious code only
• **DESCRIPTIVE NAMING**: `processTextNodes()` not `ptn()` or `handleStuff()`
• **COMMENT THE WHY**: Only explain why, never what. Code shows what
• **SINGLE RESPONSIBILITY**: Each function does ONE thing
• **EXPLICIT ERROR HANDLING**: No silent failures
• **MEASURE THEN OPTIMIZE**: No premature optimization
• **SIMPLICITY FIRST**: Remove everything non-essential

Honest Technical Assessment

ALWAYS provide honest assessment of technical decisions:

• If code has problems, explain the specific issues
• If an approach has limitations, quantify them
• If there are security risk