2504 Design 61068c92

# Technical Design: z-shortcut-and-rename

## Metadata
- **Feature**: z-shortcut-and-rename
- **Status**: DRAFT
- **Created**: 2026-01-30

---

## 1. Overview

### 1.1 Summary
Two coordinated changes: (1) generate `z:*.md` shortcut files that redirect to `zerg:*.md` slash commands, update install/uninstall to handle both prefixes; (2) rename `troubleshoot` → `debug` across all code, commands, docs, and tests (26+ files).

### 1.2 Goals
- `/z:rush` works identically to `/zerg:rush` for all 20 commands
- `zerg debug` replaces `zerg troubleshoot` at CLI
- Zero behavioral regression

### 1.3 Non-Goals
- Changing any diagnostic logic or test assertions
- Adding new troubleshoot/debug features
- Backward compat alias (old name simply stops existing)

---

## 2. Architecture

### 2.1 `/z` Shortcut Approach

Each `z:*.md` file is a thin redirect that includes the full `zerg:*.md` content. Implementation:

```
# zerg/data/commands/z:rush.md (generated)
<!-- Z-SHORTCUT: This is a shortcut for /zerg:rush -->
<!-- Auto-generated by ZERG. Do not edit directly. Edit zerg:rush.md instead. -->

<command-name>/z:rush</command-name>
<import>zerg:rush</import>
```

However, Claude Code slash commands don't support `<import>`. The practical approach:

**Option A**: Duplicate content (bloat, drift risk)
**Option B**: Generate `z:*.md` at install time by copying content with `zerg:` → `z:` in the command-name tag
**Option C**: Symlink `z:rush.md` → `zerg:rush.md` (simplest, no drift)

**Decision**: **Option C — Symlinks**. `install-commands` already uses symlinks. Each `z:*.md` symlinks to the corresponding `zerg:*.md` source file. The slash command system reads the file content regardless of name. The file _name_ determines the command prefix (`z:rush` vs `zerg:rush`), but the _content_ is shared.

### 2.2 Install Commands Changes

```python
# Current: COMMAND_GLOB = "zerg:*.md"
# New: Also generate z:*.md symlinks pointing to zerg:*.md source files

def _install(...):
    # 1. Install zerg:*.md as before
    # 2. For each zerg:*.md, create z:*.md symlink → same source
```

### 2.3 Rename Strategy

Pure file rename + find-and-replace. No architectural changes.

**Rename map:**
| From | To |
|------|----|
| `zerg/commands/troubleshoot.py` | `zerg/commands/debug.py` |
| `zerg/data/commands/zerg:troubleshoot.md` | `zerg/data/commands/zerg:debug.md` |
| `tests/unit/test_troubleshoot_cmd.py` | `tests/unit/test_debug_cmd.py` |
| `tests/integration/test_troubleshoot.py` | `tests/integration/test_debug.py` |

**Symbol renames:**
| From | To |
|------|----|
| `TroubleshootPhase` | `DebugPhase` |
| `TroubleshootConfig` | `DebugConfig` |
| `TroubleshootCommand` | `DebugCommand` |
| `troubleshoot` (click cmd) | `debug` (click cmd) |
| `get_logger("troubleshoot")` | `get_logger("debug")` |

---

## 3. Key Decisions

### Decision: Symlinks for `/z` shortcuts
**Context**: Need `/z:rush` to behave identically to `/zerg:rush`.
**Options**: (1) Duplicate files, (2) Generate at install, (3) Symlink
**Decision**: Symlink. `z:rush.md` → `zerg:rush.md` in the install target directory.
**Rationale**: Zero drift, zero maintenance, install-commands already uses symlinks.

### Decision: No backward compat for `troubleshoot`
**Context**: Keep old name as alias?
**Decision**: No. Clean break. `zerg troubleshoot` → error.
**Rationale**: Backlog item explicitly says "rename", not "alias". Keeping both adds confusion.

---

## 4. Implementation Plan

### Phase Summary

| Phase | Level | Tasks | Parallel |
|-------|-------|-------|----------|
| Foundation | 1 | 2 | Yes |
| Core Rename | 2 | 4 | Yes |
| Integration | 3 | 3 | Yes |
| Testing | 4 | 2 | Yes |
| Quality | 5 | 1 | No |

### File Ownership

| File | Task ID | Operation |
|------|---------|-----------|
| `zerg/commands/debug.py` | ZR-L1-001 | create (from rename) |
| `zerg/commands/install_commands.py` | ZR-L1-002 | modify |
| `zerg/commands/__init__.py` | ZR-L2-001 | modify |
| `zerg/cli.py` | ZR-L2-002 | modify |
| `zerg/data/commands/zerg:debug.md` | ZR-L2-003 | create (from rename) |
| `zerg/diagnostics/*.py` (6 files) | ZR-L2-004 | modify |
| `zerg/data/commands/zerg:troubleshoot.md` | ZR-L2-003 | delete |
| `tests/unit/test_debug_cmd.py` | ZR-L3-001 | create (from rename) |
| `tests/integration/test_debug.py` | ZR-L3-002 | create (from rename) |
| `tests/unit/test_diagnostics/test_recovery.py` | ZR-L3-003 | modify |
| `README.md` + docs (7 files) | ZR-L4-001 | modify |
| `CLAUDE.md` + PROJECT_INSTRUCTIONS.md | ZR-L4-002 | modify |
| All files | ZR-L5-001 | verify |

### Dependency Graph

```
L1: ZR-L1-001 (rename cmd file) ──┐
    ZR-L1-002 (install_commands)──┤
                                   │
L2: ZR-L2-001 (__init__.py)      ─┤─ depends on L1
    ZR-L2-002 (cli.py)           ─┤
    ZR-L2-003 (slash cmd)        ─┤
    ZR-L2-004 (diagnostics refs) ─┘
                                   │
L3: ZR-L3-001 (unit tests)      ─┤─ depends on L2
    ZR-L3-002 (integration tests)─┤
    ZR-L3-003 (diag test refs)   ─┘
                                   │
L4: ZR-L4-001 (docs)            ─┤─ depends on L3
    ZR-L4-002 (project docs)    ─┘
                                   │
L5: ZR-L5-001 (quality gates)   ──┘─ depends on L4
```

---

## 5. Risk Assessment

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Missed reference | Medium | Low | grep sweep in quality gate |
| Symlink not supported on Windows | Low | Low | install_commands already falls back to copy |
| Import cycle from rename | Low | Medium | Straightforward 1:1 rename, no new deps |

---

## 6. Parallel Execution Notes

### Recommended Workers
- Minimum: 2 workers
- Optimal: 4 workers (widest level is L2 with 4 tasks)
- Maximum: 4 workers

---

## 7. Approval

| Role | Name | Date | Signature |
|------|------|------|-----------|
| Architecture | | | PENDING |