@xonovex/skills 0.1.0

package/skills/plan-guidelines/reference/code-harden.md

@@ -0,0 +1,30 @@
+# code-harden: Identify Code Hardening Opportunities
+
+**Guideline:** Analyze code for hardening focusing on type safety, validation, logging, and error handling.
+
+**Rationale:** Hardening improves reliability, debugging, and maintainability. Type safety catches bugs compile-time, validation prevents invalid states, logging aids debugging, and explicit error handling prevents silent failures.
+
+**Example:**
+```typescript
+// Before: Weak type safety, no validation
+function processUser(data: any) {
+  return { id: data.id, email: data.email }
+}
+
+// After: Strong types, validation, error handling
+function processUser(data: unknown): Result<User, ValidationError> {
+  const parsed = userSchema.safeParse(data)
+  if (!parsed.success) return Err(parsed.error)
+  logger.info('Processing user', { id: parsed.data.id })
+  return Ok(parsed.data)
+}
+```
+
+**Techniques:**
+- Review project standards by reading CLAUDE.md, AGENTS.md, and style guides
+- Scan for type safety issues: any types, implicit types, unchecked assertions
+- Identify missing validation: unvalidated inputs, absent schema checks, missing guards
+- Analyze error handling patterns: unhandled errors, swallowed exceptions, silent failures
+- Detect logging gaps: missing context, inconsistent levels, inadequate debugging info
+- Find code smells: long functions (>30 lines), deep nesting, complex branches
+- Group issues by severity and category, prioritize by impact and fix effort

package/skills/plan-guidelines/reference/code-shared-extract.md

@@ -0,0 +1,25 @@
+# code-shared-extract: Identify Common Patterns for Shared Library Extraction
+
+**Guideline:** Identify common code patterns across packages for extraction to shared libraries.
+
+**Rationale:** Duplicated code increases maintenance burden and inconsistency risks. Extracting to shared libraries promotes DRY, ensures consistent behavior, simplifies updates.
+
+**Example:**
+```typescript
+// Found in 3 packages: auth validation logic
+// packages/api/src/utils/validateToken.ts
+// packages/web/src/utils/validateToken.ts (duplicate!)
+// packages/admin/src/utils/validateToken.ts (slight variation)
+
+// Extract to: packages/shared-auth/src/validateToken.ts
+export function validateToken(token: string): Result<Payload, Error>
+```
+
+**Techniques:**
+- Scan packages for repeated patterns: functions, components, hooks, middleware, types, constants
+- Use semantic analysis to find similar logic even with different names
+- Group patterns by similarity: identical code, equivalent logic, same interface
+- Rank candidates by impact: occurrences × complexity × cross-package count
+- Determine target: same-package `utils/`, cross-package `shared-*`, or new library
+- Plan phased extraction with minimal breaking changes
+- Validate extraction with typecheck, lint, and test suite

package/skills/plan-guidelines/reference/code-simplify.md

@@ -0,0 +1,33 @@
+# code-simplify: Analyze Code Complexity for Simplification
+
+**Guideline:** Identify consolidation, dead code removal, and simplification opportunities.
+
+**Rationale:** Complexity accumulates through duplication and feature additions. Simplification reduces cognitive load, improves maintainability, and helps new contributors.
+
+**Example:**
+```typescript
+// Dead code: unused export
+export interface LegacyUserType { name: string }
+
+// Duplicate validation repeated 5 times
+if (!email || !email.includes('@')) throw new Error()
+if (!phone || !phone.match(/^\d{10}$/)) throw new Error()
+
+// Over-engineered: single implementation
+interface IUserValidation { validate(u: any): boolean }
+class UserValidation implements IUserValidation { ... }
+// Just use: function validateUser(u: User): boolean
+
+// Large interface needing simplification
+interface Config { host, port, ssl, timeout, retries, backoff, circuit, cache, ... }
+// Split: { server: { host, port, ssl }, network: { timeout, retries } }
+```
+
+**Techniques:**
+- Scan files and build signature index for duplicate detection
+- Find copy-paste duplicates: identical functions, replicated logic (>10 lines)
+- Identify dead code: uncalled functions, unreachable branches, unused exports
+- Detect redundancy: repeated validation, duplicate utilities, hardcoded constants
+- Find over-engineering: single-implementation interfaces, unnecessary wrapper classes
+- Analyze large interfaces: >5 parameters, nested config, inconsistent signatures
+- Group issues by severity, prioritize by impact, and plan phased removal

package/skills/plan-guidelines/reference/code-template-extract.md

@@ -0,0 +1,34 @@
+# code-template-extract: Analyze Package for Template Extraction
+
+**Guideline:** Analyze packages to identify core patterns for template extraction.
+
+**Rationale:** Templates enable rapid scaffolding while maintaining consistency. Extracting from proven implementations ensures new packages follow established patterns and best practices.
+
+**Example:**
+```
+Analyzing packages/api-auth (successful, reusable):
+├── src/
+│   ├── routes/index.ts
+│   ├── middleware/auth.ts
+│   ├── services/TokenService.ts
+│   └── types/index.ts
+├── tests/
+├── Dockerfile
+├── docker-compose.yml
+└── moon.yml
+
+Template parameters:
+- {{PACKAGE_NAME}}: api-auth
+- {{PORT}}: 3000
+- {{DATABASE_URL}}: postgres://...
+```
+
+**Techniques:**
+- Analyze successful package structure: directories, naming, organization patterns
+- Document configuration templates: package.json, tsconfig.json, build settings
+- Extract code patterns: common handlers, middleware, components, hooks
+- Identify deployment setup: Dockerfile patterns, CI/CD, Kubernetes manifests
+- Catalog testing patterns: utilities, fixtures, test organization
+- Compare across packages to validate reusability and frequency
+- Define parameterization: variables for names, ports, URLs, package-specific values
+- Create template scaffold with substitution markers

package/skills/plan-guidelines/reference/code-template-scaffold.md

@@ -0,0 +1,36 @@
+# code-template-scaffold: Analyze Package Scaffolding Options
+
+**Guideline:** Analyze available templates and generate research report on scaffolding options.
+
+**Rationale:** Understanding available templates before scaffolding ensures correct foundation. Reduces setup time and ensures consistency with established patterns.
+
+**Example:**
+```
+Available templates in .templates/:
+1. api-typescript:
+   - Features: Express, Zod validation, Jest tests, Docker
+   - Use for: RESTful API services
+   - Dependencies: 45, Size: 2.1MB
+
+2. react-vite:
+   - Features: Vite, React 19, TailwindCSS, Vitest
+   - Use for: Frontend applications
+   - Dependencies: 38, Size: 1.8MB
+
+3. shared-library:
+   - Features: Monorepo-friendly, TypeScript, ESM, minimal deps
+   - Use for: Reusable utilities and components
+   - Dependencies: 12, Size: 0.8MB
+
+Recommendation: For new API → use api-typescript
+```
+
+**Techniques:**
+- Discover templates in monorepo (usually in `templates/`, `.templates/`, or `_templates/`)
+- List template types: website, API, library, utility, service
+- Document features and capabilities for each template
+- Identify configuration options and substitution placeholders
+- Catalog dependencies, build systems, and deployment setup
+- Map best use cases and target scenarios for each
+- Compare templates across categories to guide selection
+- Provide recommendations matching requirements to template fit

package/skills/plan-guidelines/reference/general-research.md

@@ -0,0 +1,35 @@
+# general-research: Research Codebase and Web
+
+**Guideline:** Research codebase and web for requirements, presenting findings without creating plans.
+
+**Rationale:** Separates research from planning, allowing exploration and decision-making before implementation. Enables saving research independently from multiple sources (codebase + web).
+
+**Example:**
+```
+Research Topic: "Add OAuth2 authentication to API"
+
+Codebase Findings:
+- Current: JWT-based auth in packages/auth-service
+- Version: @auth/core v5.1
+- Similar: GitHub OAuth in 2 places (admin, web)
+
+Web Research:
+- Latest: @auth/core v6.0 (released Jan 2026)
+- Breaking: Session handling changed
+- Docs: oauth.net/2 reference implementation
+
+Recommendations:
+- Upgrade to v6.0 (more secure)
+- Plan migration of session layer
+- Consolidate OAuth logic to shared-auth package
+```
+
+**Techniques:**
+- Parse research topic and clarify scope with specific requirements
+- Explore codebase patterns using parallel search: grep, glob, file reading
+- Document current library versions and identify similar implementations
+- Research latest versions and releases via web search
+- Fetch and analyze documentation from official sources
+- Map integration points and existing patterns in the codebase
+- Identify relevant guidelines and best practices
+- Synthesize codebase findings and web research into recommendations

package/skills/plan-guidelines/reference/plan-create.md

@@ -0,0 +1,37 @@
+# plan-create: Create Implementation Plan with Research
+
+**Guideline:** Generate implementation plan from spec/requirements using research findings.
+
+**Rationale:** Creates actionable plan from research context. Breaks work into tracked tasks with dependencies, enabling parallel or sequential execution as needed.
+
+**Example:**
+```
+## Implementation Plan: Add OAuth2 Authentication
+
+### Goals
+- Support OAuth2 authentication
+- Maintain backward compatibility with JWT
+- Consolidate OAuth logic across services
+
+### Key Decisions
+- Upgrade @auth/core to v6.0
+- Migrate session layer (breaks change)
+- Extract OAuth to shared-auth package
+
+### Tasks
+1. [BLOCKED BY: none] Update @auth/core dependency
+2. [BLOCKED BY: 1] Migrate session handling in auth-service
+3. [PARALLEL TO: 2] Extract GitHub OAuth to shared-auth
+4. [BLOCKED BY: 2,3] Update packages/web to use shared OAuth
+5. [BLOCKED BY: 2,3,4] End-to-end testing and deployment
+```
+
+**Techniques:**
+- Read specification and clarify requirements with stakeholders
+- Synthesize research findings from conversation history and prior analysis
+- Document key architecture decisions: technology choices, versions, rationale
+- Create granular tasks with clear objectives in imperative form
+- Define task dependencies: which tasks block or are blocked by others
+- Identify independent tasks for parallel execution
+- Structure plan sections: overview, goals, current state, findings, tasks
+- Set success criteria and completion indicators for each task

package/skills/plan-guidelines/reference/plan-tdd-create.md

@@ -0,0 +1,44 @@
+# plan-tdd-create: Create TDD Implementation Plan with Research
+
+**Guideline:** Generate TDD implementation plan with RED-GREEN-COMMIT cycles as tracked tasks.
+
+**Rationale:** Creates actionable TDD plan from research context. Each RED-GREEN-COMMIT cycle becomes a tracked task, ensuring test-first development with proper sequencing.
+
+**Example:**
+```
+## TDD Plan: User Authentication
+
+### Story 1: Basic login validation
+[RED] Write test: login() validates email format
+[GREEN] Implement: if (!email.includes('@')) throw
+[COMMIT] "feat: validate email format in login"
+
+### Story 2: Password requirements
+[RED] Write test: password must be 8+ chars
+[GREEN] Implement: if (password.length < 8) throw
+[COMMIT] "feat: enforce 8-char password minimum"
+
+### Story 3: Token generation
+[RED] Write test: login() returns JWT token
+[GREEN] Implement: return jwt.sign({email})
+[COMMIT] "feat: generate JWT token on successful login"
+
+### Story 4: Error handling
+[RED] Write test: invalid credentials return error
+[GREEN] Implement: check hash match, return Err
+[COMMIT] "feat: return error for invalid credentials"
+
+### Story 5: Refactor
+[REFACTOR] Extract validation to schema, improve test coverage
+```
+
+**Techniques:**
+- Read specification and extract research findings from prior analysis
+- Decompose feature into discrete, testable stories
+- Sequence stories: basic → properties → behavior → edge cases → validation
+- Write RED test code matching project's test framework and conventions
+- Define GREEN implementation guidance: minimal to pass test, hardcode acceptable
+- Create sequential task dependencies: each cycle depends on previous completion
+- Structure each task with test code, implementation guidance, and validation steps
+- Plan for refactoring after GREEN phase for code quality
+- Check granularity: independent commit, tests one thing, clear description

package/skills/plan-guidelines/reference/todos.md

@@ -0,0 +1,39 @@
+# todos: Scan and Group TODO Comments
+
+**Guideline:** Scan for TODO comments, group by intent, and generate research report.
+
+**Rationale:** TODO comments accumulate and become difficult to track. Scanning and grouping by intent helps prioritize work, identify systemic issues, and convert notes into actionable plans.
+
+**Example:**
+```
+Scan Results: 47 TODO comments found
+
+Group 1: Auth improvements (12 occurrences, 3 files)
+- "TODO: Add 2FA support"
+- Files: services/auth, packages/web, packages/admin
+- Priority: HIGH (blocks security audit)
+- Action: Convert to plan-create task
+
+Group 2: Performance optimizations (18 occurrences, 7 files)
+- "TODO: Add caching layer"
+- "TODO: Optimize database queries"
+- Files: across services
+- Priority: MEDIUM
+- Action: Create code-simplify analysis
+
+Group 3: Deprecations (17 occurrences, 5 files)
+- "TODO: Remove legacy API"
+- Files: api routes
+- Priority: LOW
+- Action: Schedule for v2.0 release
+```
+
+**Techniques:**
+- Scan directory recursively for TODO patterns (`TODO:`, `FIXME:`, `NOTE:`)
+- Extract unique TODO messages, normalized for whitespace consistency
+- Group TODOs by similarity: identical text, conceptual intent, file patterns
+- Map each group to source files, count occurrences and affected files
+- Infer applicable skills from file extensions and framework indicators
+- Categorize by priority: blocking work, technical debt, nice-to-have
+- Generate report with groups, file counts, and action recommendations
+- Convert high-priority TODOs into tasks for tracking and execution

package/skills/presentation-guidelines/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: presentation-guidelines
+description: >-
+  Trigger on presentation/slides creation tasks. Use when creating presentations from codebase analysis. Apply for scaffolding motion presentation packages. Keywords: presentation, slides, codebase analysis, GraphViz diagrams, Motion, React components, visual flow, narrative structure.
+---
+
+# Presentation Guidelines
+
+## Core Principles
+
+- **Explore First** - Use Task agents to gather context from codebase
+- **Structure Slides** - Organize findings into clear narrative flow
+- **Visual Diagrams** - Create GraphViz diagrams for architecture and flows
+- **Factory Pattern** - Use factory functions for automatic maxSteps calculation
+- **Theme Consistency** - Extract and apply brand colors throughout
+
+## Workflow
+
+- **Create Presentation** - Explore codebase and generate markdown presentation, see [reference/presentation-create.md](reference/presentation-create.md)
+- **Scaffold Package** - Convert markdown to Motion presentation package, see [reference/presentation-motion-scaffold.md](reference/presentation-motion-scaffold.md)
+
+## Progressive Disclosure
+
+- **Create presentation document** - Explore codebase and structure into slides, see [reference/presentation-create.md](reference/presentation-create.md)
+- **Scaffold motion package** - Generate React+Motion package from markdown, see [reference/presentation-motion-scaffold.md](reference/presentation-motion-scaffold.md)

package/skills/presentation-guidelines/reference/presentation-create.md

@@ -0,0 +1,41 @@
+# presentation-create: Create Presentation Document from Codebase
+
+**Guideline:** Generate markdown presentation by exploring codebase and structuring findings into slides.
+
+**Rationale:** Transforms technical findings from codebase analysis into structured narrative flow with clear narrative arcs, enabling effective communication of architecture and decisions to various audiences.
+
+**Example:**
+
+```markdown
+# Microservices Architecture
+
+---
+
+## Overview
+- 12 services, 15 shared packages
+- Kubernetes orchestration, GitOps deployment
+- Found in: services/, clusters/
+
+---
+
+## Core Services
+- API Gateway (packages/services/api-gateway)
+- Auth Service (packages/services/auth)
+- User Service (packages/services/users)
+
+---
+
+## Next Steps
+- Scale to 20 services
+- Implement service mesh
+```
+
+**Techniques:**
+- Parse topic and identify relevant codebase areas and packages
+- Clarify scope with questions: packages, depth, audience, style
+- Scan codebase using parallel exploration: architecture, schemas, integration points
+- Synthesize findings into logical narrative with file references
+- Generate diagrams: ASCII art for markdown or GraphViz for motion
+- Structure content into slides: title, summary, challenges, solutions, implementation
+- Extract and document style preferences: colors, fonts, logo, themes
+- Create markdown with `---` separators for slide boundaries

package/skills/presentation-guidelines/reference/presentation-motion-scaffold.md

@@ -0,0 +1,38 @@
+# presentation-motion-scaffold: Create Motion Presentation Package
+
+**Guideline:** Scaffold Motion React presentation package from markdown presentation document.
+
+**Rationale:** Converts markdown presentations into fully-functional React + Motion slide decks with animations and interactive features.
+
+**Example:**
+```
+Input: presentation.md with:
+- Title: "Microservices Architecture"
+- Theme colors: #2563eb, #dc2626, #16a34a
+- Slides: overview, services, challenges, next steps
+
+Output structure:
+packages/presentations/microservices/
+├── src/
+│   ├── slides/
+│   │   ├── Title.tsx
+│   │   ├── Overview.tsx
+│   │   ├── Services.tsx
+│   │   └── NextSteps.tsx
+│   ├── App.tsx
+│   └── theme.ts (generated colors)
+├── public/assets/
+├── package.json (generated)
+└── vite.config.ts (generated)
+```
+
+**Techniques:**
+- Parse markdown: extract title, style guide, slides separated by `---`
+- Determine slide types from content: title, bullets, diagrams, chapter headers, closing
+- Create package structure at `packages/presentations/[name]/` with configs
+- Generate TSX components for each slide type with factory functions
+- Extract theme colors from Style Guide section (#hex format)
+- Convert ASCII diagrams to GraphViz .dot files for SVG generation
+- Download and place external logos/images to `public/assets/`
+- Generate configs: package.json, moon.yml, tsconfig.json, vite.config.ts
+- Create factory functions for each slide with automatic step calculation

package/skills/python-guidelines/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: python-guidelines
+description: >-
+  Trigger on `.py` files. Use when writing Python 3.12+ code. Apply for API development, data processing, file operations, resource management. Keywords: Python, async/await, dataclasses, type hints, generators, pathlib, pytest, context managers, @cache, f-strings.
+---
+
+# Python Coding Guidelines
+
+## Requirements
+
+- Python ≥ 3.12; pytest ≥ 8.
+
+## Essentials
+
+- **Data models** - Use dataclasses and type hints, see [reference/dataclasses-type-hints.md](reference/dataclasses-type-hints.md), [reference/type-checking.md](reference/type-checking.md)
+- **Iteration** - Prefer generators/comprehensions for data processing, see [reference/generators-comprehensions.md](reference/generators-comprehensions.md)
+- **Async I/O** - Use async/await for I/O operations, see [reference/async-await-patterns.md](reference/async-await-patterns.md)
+- **Performance** - Cache pure functions with `@cache`, see [reference/caching-functions.md](reference/caching-functions.md)
+- **Resource management** - Use context managers for cleanup, see [reference/resource-management.md](reference/resource-management.md)
+- **Modern syntax** - Use pathlib, f-strings, specific exceptions, see [reference/pathlib-file-ops.md](reference/pathlib-file-ops.md), [reference/string-formatting.md](reference/string-formatting.md), [reference/exception-handling.md](reference/exception-handling.md)
+
+## Progressive disclosure
+
+- Read [reference/dataclasses-type-hints.md](reference/dataclasses-type-hints.md) - When defining structured data models or adding type annotations
+- Read [reference/type-checking.md](reference/type-checking.md) - When using Protocols, type aliases, or complex Union types
+- Read [reference/async-await-patterns.md](reference/async-await-patterns.md) - When building async APIs or handling concurrent I/O operations
+- Read [reference/resource-management.md](reference/resource-management.md) - When working with files, connections, or resources needing cleanup
+- Read [reference/caching-functions.md](reference/caching-functions.md) - When optimizing expensive computations or repeated function calls
+- Read [reference/generators-comprehensions.md](reference/generators-comprehensions.md) - When processing large datasets or streaming data
+- Read [reference/string-formatting.md](reference/string-formatting.md) - When formatting output, building messages, or templating
+- Read [reference/pathlib-file-ops.md](reference/pathlib-file-ops.md) - When reading/writing files or traversing directories
+- Read [reference/exception-handling.md](reference/exception-handling.md) - When defining error handling or creating custom exceptions

package/skills/python-guidelines/reference/async-await-patterns.md

@@ -0,0 +1,62 @@
+# async-await-patterns: Async/Await Patterns
+
+**Guideline:** Use async/await for I/O-bound operations with proper concurrent execution patterns.
+
+**Rationale:** Async programming enables efficient I/O operations without blocking threads. Using `asyncio.gather()` allows multiple operations to run concurrently, improving performance. Async generators enable memory-efficient streaming of data. Proper async context management ensures resources are cleaned up correctly.
+
+**Example:**
+
+```python
+import asyncio
+import aiohttp
+from typing import Sequence
+
+# Async function with type hints
+async def fetch_url(session: aiohttp.ClientSession, url: str) -> str:
+    async with session.get(url) as response:
+        response.raise_for_status()
+        return await response.text()
+
+# Async context manager
+async def fetch_multiple(urls: Sequence[str]) -> list[str]:
+    async with aiohttp.ClientSession() as session:
+        tasks = [fetch_url(session, url) for url in urls]
+        return await asyncio.gather(*tasks)
+
+# Async generator
+async def fetch_paginated(
+    session: aiohttp.ClientSession,
+    base_url: str,
+    page_size: int = 100
+):
+    page = 1
+    while True:
+        url = f"{base_url}?page={page}&size={page_size}"
+        data = await fetch_url(session, url)
+
+        if not data:
+            break
+
+        yield data
+        page += 1
+
+# Usage
+async def main():
+    urls = ["https://api.example.com/1", "https://api.example.com/2"]
+    results = await fetch_multiple(urls)
+
+    async with aiohttp.ClientSession() as session:
+        async for page_data in fetch_paginated(session, "https://api.example.com/items"):
+            process_page(page_data)
+
+# Run
+asyncio.run(main())
+```
+
+**Techniques:**
+- Define async functions with `async def`
+- Use `await` for async operations
+- Use `async with` for async context managers
+- Gather concurrent operations with `asyncio.gather(*tasks)`
+- Create async generators with `async def` and `yield`
+- Run async code with `asyncio.run(main())`

package/skills/python-guidelines/reference/caching-functions.md

@@ -0,0 +1,47 @@
+# caching-functions: Caching Pure Functions
+
+**Guideline:** Cache expensive pure function results with `@cache` or `@lru_cache` decorators.
+
+**Rationale:** Caching eliminates redundant computations for pure functions (functions that always return the same output for the same input). `@cache` provides unbounded caching for small datasets, while `@lru_cache` offers size-limited caching with LRU eviction for larger datasets. This dramatically improves performance for recursive algorithms and expensive operations.
+
+**Example:**
+
+```python
+from functools import cache, lru_cache
+from pathlib import Path
+
+# Cache with @cache (unbounded cache)
+@cache
+def load_config() -> dict[str, str]:
+    """Load and parse config file (cached after first call)"""
+    return parse_config(Path("config.txt").read_text())
+
+# LRU cache with size limit
+@lru_cache(maxsize=128)
+def fibonacci(n: int) -> int:
+    """Calculate Fibonacci number (cached with LRU eviction)"""
+    if n < 2:
+        return n
+    return fibonacci(n - 1) + fibonacci(n - 2)
+
+# Cache expensive computations
+@lru_cache(maxsize=1000)
+def calculate_hash(data: str) -> str:
+    """Compute expensive hash (cached)"""
+    import hashlib
+    return hashlib.sha256(data.encode()).hexdigest()
+
+# Usage - function only runs once per unique input
+config1 = load_config()  # Loads from file
+config2 = load_config()  # Returns cached value
+
+fib_10 = fibonacci(10)  # Calculates
+fib_10_again = fibonacci(10)  # Returns cached
+```
+
+**Techniques:**
+- Use `@cache` for unbounded caching of pure functions
+- Use `@lru_cache(maxsize=N)` for size-limited caching
+- Only cache pure functions (no side effects, deterministic output)
+- Consider cache size based on memory constraints
+- Cache is per-function-call signature (different args = different cache entry)

package/skills/python-guidelines/reference/dataclasses-type-hints.md

@@ -0,0 +1,63 @@
+# dataclasses-type-hints: Dataclasses and Type Hints
+
+**Guideline:** Use dataclasses with type hints for structured data definitions.
+
+**Rationale:** Dataclasses reduce boilerplate code while providing automatic `__init__`, `__repr__`, and comparison methods. Type hints enable static analysis, IDE support, and self-documenting code. Frozen dataclasses create immutable objects that are safer in concurrent contexts.
+
+**Example:**
+
+```python
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+
+# Immutable dataclass with type hints
+@dataclass(frozen=True)
+class User:
+    id: str
+    email: str
+    name: str
+    created_at: datetime
+    metadata: dict[str, str] = field(default_factory=dict)
+
+# Mutable dataclass
+@dataclass
+class Config:
+    host: str = "localhost"
+    port: int = 5432
+    debug: bool = False
+    timeout: float = 30.0
+
+# Optional and union types
+@dataclass(frozen=True)
+class Response:
+    status: int
+    data: dict[str, any]
+    error: Optional[str] = None
+
+# Generic types
+@dataclass
+class Page[T]:
+    items: list[T]
+    total: int
+    page: int
+    page_size: int
+
+# Usage with type safety
+user = User(
+    id="123",
+    email="user@example.com",
+    name="John Doe",
+    created_at=datetime.now()
+)
+
+# Type checker knows this is str
+print(user.email)
+```
+
+**Techniques:**
+- Import `dataclass` decorator and type hints
+- Annotate all fields with types using modern syntax (`list[T]`, `dict[K,V]`)
+- Use `frozen=True` for immutable data structures
+- Use `field(default_factory=...)` for mutable defaults
+- Leverage generics with `[T]` syntax for reusable data structures