# GGUF Metadata Preset Generation Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make `generate_models_preset.py` derive richer `models-preset.ini` values from GGUF metadata only, annotate key numeric values with min/max comments, and stop defaulting to backup creation.

**Architecture:** Keep the work inside `generate_models_preset.py`. Tighten model classification to metadata-backed signals only, add explicit value-selection helpers for model-specific fields, and extend INI rendering so key numeric values are preceded by compact range comments. Cover the new behavior with focused unit tests.

**Tech Stack:** Python 3, `unittest`, existing preset generator script

---

### Task 1: Lock expected behavior with tests

**Files:**
- Create: `tests/test_generate_models_preset.py`
- Modify: `generate_models_preset.py`

- [ ] **Step 1: Write failing tests**

```python
class ClassificationTests(unittest.TestCase):
    def test_moe_detection_uses_metadata_not_filename(self):
        ...

class PresetValueTests(unittest.TestCase):
    def test_moe_values_include_cache_types_and_ncmoe(self):
        ...
```

- [ ] **Step 2: Run test to verify it fails**

Run: `python -m unittest tests.test_generate_models_preset -v`
Expected: FAIL because the new tests assert metadata-only behavior and richer field output that the current implementation does not provide.

- [ ] **Step 3: Write minimal implementation**

```python
def classify_model_family(entry: ModelEntry) -> str:
    ...
```

- [ ] **Step 4: Run test to verify it passes**

Run: `python -m unittest tests.test_generate_models_preset -v`
Expected: PASS

### Task 2: Extend preset rendering and CLI defaults

**Files:**
- Modify: `generate_models_preset.py`
- Test: `tests/test_generate_models_preset.py`

- [ ] **Step 1: Write failing tests**

```python
def test_render_ini_emits_range_comments_for_numeric_values(self):
    ...

def test_parser_disables_backup_by_default(self):
    ...
```

- [ ] **Step 2: Run test to verify it fails**

Run: `python -m unittest tests.test_generate_models_preset -v`
Expected: FAIL because current output omits the new comments and currently enables backup by default.

- [ ] **Step 3: Write minimal implementation**

```python
def build_value_comments(...):
    ...
```

- [ ] **Step 4: Run test to verify it passes**

Run: `python -m unittest tests.test_generate_models_preset -v`
Expected: PASS

### Task 3: Verify against generated preset output

**Files:**
- Modify if needed: `generate_models_preset.py`

- [ ] **Step 1: Generate a fresh preset**

Run: `python generate_models_preset.py --models-dir "<models-dir>" --output "models-preset.generated.ini" --select all --profile smart --alias-style section`
Expected: command succeeds and writes a preset with richer model-specific fields and range comments.

- [ ] **Step 2: Inspect one MoE section**

Look for:

```ini
; ctx-size range = ...
; n-gpu-layers range = ...
; n-cpu-moe range = ...
cache-type-k = q8_0
cache-type-v = q8_0
```

- [ ] **Step 3: Adjust implementation only if the generated output contradicts the tests**

```python
# Keep changes inside the preset heuristics helpers and comment rendering.
```