# Developer Experience & Usability Improvements

**Status**: Proposal
**Created**: 2026-02-08
**Scope**: CLI UX, onboarding, error handling, configuration, dev workflow, IDE support, debugging

---

## Executive Summary

Prism has **good foundational UX** with excellent scaffolding, clear command organization, smart file preservation mechanisms (protected regions, file strategies), and rich console output. However, meaningful gaps exist in **debugging support** (no `--verbose`/`--debug` flags), **IDE integration** (no JSON schema for TOML autocomplete), **onboarding** (no in-CLI quickstart), and **error messaging** (errors lack actionable suggestions).

**Overall DX Score: 7/10**

---

## Findings by Area

### 1. CLI Organization (67+ commands, 12 groups)

**Strengths**:
- Logical command grouping (db, review, docker, deploy, auth, etc.)
- Consistent help text patterns with clear descriptions
- Rich library for colored output (blue=action, green=success, yellow=warning, red=error)
- Progress spinners during long operations (`cli.py:404-426`)
- Confirmation prompts for destructive operations

**Gaps**:

| Issue | Location | Impact |
|-------|----------|--------|
| No command aliases | All commands full-length only | Verbosity for power users |
| No interactive mode | All commands require flags | Steeper learning curve |
| Confusing `prism init` | `cli.py:2435` — DB-only, not project init | Users confused about purpose |
| Minimal help examples | `cli.py:1039` — generate docstring sparse | Users must guess usage patterns |
| No command browser | No `prism --guide` | Discoverability limited to `--help` |

**Recommendations**:
- Add command aliases (e.g., `gen` → `generate`, `reset` → `db reset`)
- Add comprehensive examples to command docstrings
- Rename or deprecate `prism db init` (since `prism generate` handles it)
- Create `prism quickstart` interactive guide command

### 2. Onboarding Experience

**Strengths**:
- Excellent `prism create` with progress spinners and "next steps" panel (`cli.py:535-561`)
- 7 project templates (minimal, api-only, mcp-only, website, app, enterprise-platform, saas)
- Spec file preservation on project recreation (`cli.py:340-425`)
- Clear warning when no `prisme.toml` found (`cli.py:1051-1063`)

**Gaps**:

| Issue | Impact |
|-------|--------|
| No in-CLI quickstart guide | Users must leave CLI to read external docs |
| Too many options for first-time users | 7 templates + 10 flags on `prism create` |
| No guided tour of generated code | Users see many files but don't understand structure |
| No "next steps" after `prism generate` | Users don't know what to do after generation |

**Recommendations**:
- Create `prism quickstart` command showing the 4-step flow: create → define → generate → dev
- Add `--starter-config` mode to `prism create` with sensible defaults
- Print "next steps" after successful generation (review, test, dev)
- Add `--help-advanced` to show all options separately from common ones

### 3. Error Handling

**Strengths**:
- Custom exception hierarchy with context (`SpecLoadError`, `SpecValidationError`, `ConfigLoadError`)
- Structured validation errors with "fix" suggestions (`spec/validators.py:60-83`)
- Error classification in config loading (`config/loader.py:76-92`)

**Gaps**:

| Issue | Location | Impact |
|-------|----------|--------|
| Stack traces exposed to users | `spec_loader.py:191-194` | Raw Python errors shown |
| Error context lost in CLI | `cli.py:1356` — doesn't use `e.path` or `e.errors` | Better diagnostics available but unused |
| Validation errors not formatted | `cli.py:1356-1358` — just prints summary | 5 errors shown as one blob |
| No recovery suggestions | `spec_loader.py:118-119` | File not found with no "did you mean?" |
| No `--verbose` mode | Entire CLI | Can't increase logging for debugging |
| Config errors silently swallowed | `cli.py:142-148` — `logger.debug("Ignoring error")` | Problems hidden from users |

**Recommendations**:
- Create structured `ErrorReporter` class that formats errors as numbered list with fix suggestions
- Add global `--verbose` and `--debug` flags to main CLI group
- Implement "did you mean?" suggestions using `difflib.get_close_matches`
- Parse and explain Pydantic validation errors in user-friendly format
- Stop silently swallowing config loading errors

### 4. Configuration Ergonomics

**Strengths**:
- Intelligent spec file resolution with fallbacks (`cli.py:96-129`)
- Modular TOML config with `prisme.d/` include directory (`config/loader.py:30-54`)
- Cross-model validation (`spec/validators.py:15-120`)

**Gaps**:

| Issue | Impact |
|-------|--------|
| No JSON schema export for `prisme.toml` | No IDE autocomplete for TOML config |
| No config validation command | Must wait for generation to fail to find TOML errors |
| Split Python/TOML config is confusing | Domain in Python, project in TOML — users switch contexts |
| No comments in generated `prisme.toml` | Users don't know which options are required vs optional |

**Recommendations**:
- Add `prism export-schema` command to generate JSON schema from Pydantic models
- Add `prism validate-config` command for TOML validation
- Generate `prisme.toml` with inline comments explaining each option
- Document the Python vs TOML split rationale clearly

### 5. Edit-Regenerate Workflow

**Strengths**:
- Protected regions for safe customization (`utils/file_handler.py:37-106`)
- 4 file strategies (ALWAYS_OVERWRITE, GENERATE_ONCE, GENERATE_BASE, MERGE)
- Override tracking with metadata (path, strategy, hashes, timestamps)
- Comprehensive `prism review` command group (`cli.py:3728-3900`)
- Optional `--watch` mode for auto-regeneration (`cli.py:2919-2940`)

**Gaps**:

| Issue | Impact |
|-------|--------|
| Protected regions require manual markup | Easy to forget, code lost on regeneration |
| No IDE support for region markers | No syntax highlighting, no typo detection |
| `--watch` is opt-in, not default | Users must remember to add flag |
| Dry-run doesn't show file strategies | Users can't tell which files are safe to edit |
| MERGE conflicts require manual resolution | No tooling assistance |
| No migration check for protected code | Spec changes could break protected code silently |

**Recommendations**:
- Make `--watch` the default in `prism dev`, add `--no-watch` opt-out
- Enhance dry-run output to show file strategies with color coding
- Add warning when protected region markers appear malformed
- Add merge conflict resolution helper (`prism review merge <file>`)

### 6. Progress & Output Quality

**Strengths**:
- Rich library throughout (spinners, panels, tables, colored text)
- Consistent color coding for message types
- Structured panels for success/error summaries
- Colored subprocess output with service prefixes

**Gaps**:

| Issue | Impact |
|-------|--------|
| No progress bars for file generation | When generating 50 files, only spinner — no count |
| Quiet mode is binary | No intermediate verbosity levels |
| No log file output | Can't save generation output for CI/CD or debugging |
| No structured output format | No `--format json` for machine parsing |

**Recommendations**:
- Add progress bars: `[=====>----] 43/100 43%` for file generation
- Add `--log-level` (QUIET/ERROR/WARN/INFO/DEBUG) and `--log-file` options
- Add `--format json` for machine-readable output in CI pipelines

### 7. Migration & Upgrade Path

**Strengths**:
- Version detection exists (`migration/detector.py:50-103`)
- `prism migrate plan` / `prism migrate apply` commands exist
- Semantic versioning in changelog

**Gaps**:

| Issue | Impact |
|-------|--------|
| No automatic migration warning on upgrade | Users must manually discover they need to migrate |
| Upgrade path unclear | "(coming soon)" for 0.x → 1.0 migration |
| No pre-flight compatibility check | Users discover issues only when generation fails |
| Mixed versioning across config files | Domain v2, project v1, config v1 — confusing |
| No migration documentation | How does v1→v2 migration work? |

**Recommendations**:
- Add version check at CLI startup to warn about needed migrations
- Create `prism compat-check` command for pre-upgrade verification
- Document migration paths per version in `docs/guides/migration.md`
- Suggest migration proactively when legacy config detected

### 8. Debug & Troubleshooting

**Strengths**:
- `prism doctor` health check (structure, deps, database, git)
- `prism validate` for spec validation
- `prism check` for project setup verification
- `prism diff` for regeneration preview

**Gaps**:

| Issue | Impact |
|-------|--------|
| No `--verbose`/`--debug` global flags | Cannot increase logging |
| Doctor only checks structure, not functionality | Doesn't verify imports, DB access, migration applicability |
| No diagnostics export | Can't attach diagnostic info to bug reports |
| Debug logging not user-accessible | Must modify Python code to see debug logs |
| No performance profiling | Can't identify slow generators |

**Recommendations**:
- Add `--verbose` and `--debug` to main CLI group
- Enhance doctor to test functionality (import spec, connect DB, apply migrations)
- Add `prism diagnostic` command to export JSON for bug reports
- Add `--profile` option to show per-generator timing

### 9. IDE Support

**Strengths**:
- Python type hints work in specs (Pydantic models give autocomplete)
- Typed CLI functions throughout

**Gaps**:

| Issue | Impact |
|-------|--------|
| No JSON schema for `prisme.toml` | TOML editing blind — no autocomplete or validation |
| No language server for specs | Basic IDE help only, no hover docs |
| No protected region IDE support | Markers not highlighted, typos not caught |
| No VS Code extension | All features are manual |

**Recommendations**:
- Implement `prism export-schema` to generate JSON schema from PrismeConfig
- Create basic VS Code extension for protected region highlighting
- Publish JSON schema to SchemaStore for automatic TOML validation

### 10. Dev Container Experience

**Strengths**:
- Comprehensive CLI for container management (start, shell, list, stop, restart, destroy)
- Smart volume persistence for dependencies and database
- Auto-detection of devcontainer environment
- Traefik integration for service routing

**Gaps**:
- Complex setup required with no guided setup
- Unclear when dev containers are beneficial vs `prism dev`
- No `prism devcontainer health` command
- No container upgrade path
- Sparse documentation (one page)

---

## Top 3 High-Impact, Low-Effort Improvements

### 1. Add Global `--verbose`/`--debug` Logging

**Why**: Essential for troubleshooting. Users cannot debug errors without verbose output.

```python
@click.group()
@click.option("--verbose", "-v", is_flag=True)
@click.option("--debug", is_flag=True)
def main(verbose, debug):
    if debug:
        logging.getLogger("prisme").setLevel(logging.DEBUG)
    elif verbose:
        logging.getLogger("prisme").setLevel(logging.INFO)
```

**Effort**: 2-3 hours | **Impact**: Enables all debugging workflows

### 2. Export JSON Schema for IDE Autocomplete

**Why**: Eliminates TOML config errors before generation runs. Major quality-of-life improvement.

```python
@main.command()
def export_schema():
    schema = PrismeConfig.model_json_schema()
    Path("prisme.schema.json").write_text(json.dumps(schema, indent=2))
```

**Effort**: 2-3 hours | **Impact**: High user satisfaction

### 3. Create In-CLI Quickstart Guide

**Why**: New users see guidance immediately without leaving CLI.

```python
@main.command()
def quickstart():
    console.print(Panel("[bold cyan]Prism Quickstart[/]"))
    console.print("1. Create: prism create my-app")
    console.print("2. Define: Edit specs/models.py")
    console.print("3. Generate: prism generate")
    console.print("4. Develop: prism dev")
```

**Effort**: 1-2 hours | **Impact**: Huge onboarding improvement

---

**Analysis Date**: 2026-02-08
