module-spec-generator

# Module Spec Generator Skill

## Purpose

This skill automatically generates comprehensive module specifications from code analysis, ensuring adherence to amplihack's **brick philosophy** and enabling effective module regeneration without breaking system connections.

## When to Use This Skill

- **Creating new modules**: Generate specs before implementation to clarify requirements
- **Documenting existing modules**: Extract specifications from working code for future reference
- **Module reviews**: Verify specs accurately represent implemented contracts
- **Refactoring decisions**: Use specs to understand module boundaries and dependencies
- **Knowledge preservation**: Document expert patterns and design decisions

## Core Philosophy: Bricks & Studs

**Brick** = Self-contained module with ONE clear responsibility
**Stud** = Public contract (functions, API, data models) others connect to
**Regeneratable** = Can be rebuilt from specification without breaking connections

A good spec enables rebuilding ANY module independently while preserving its connection points.

## Specification Template

Every module specification includes these sections:

### 1. Module Overview

```
# [Module Name] Specification

## Purpose
One-sentence description of the module's core responsibility.

## Scope
What this module handles | What it explicitly does NOT handle

## Philosophy Alignment
How this module embodies brick principles and simplicity.
```

### 2. Public Contract (The "Studs")

```
## Public Interface

### Functions
- `function_name(param: Type) -> ReturnType`
  Brief description of what it does.

### Classes/Data Models
- `ClassName`
  - Fields: list with types
  - Key methods: list

### Constants/Enums
Important module-level constants and their purposes.
```

### 3. Dependencies

```
## Dependencies

### External Dependencies
- `library_name` (version): What it's used for

### Internal Dependencies
- `module_path`: How this module depends on it

### NO External Dependencies