Technical Design: git-cleanup-issues-docs

Technical Design: git-cleanup-issues-docs

Metadata

• Feature: git-cleanup-issues-docs
• Status: DRAFT
• Created: 2026-02-02
• Author: /zerg:design

1. Overview

1.1 Summary

Add two new actions (cleanup and issue) to /zerg:git, rename all wiki files from Command-*.md to zerg-*.md with full cross-reference updates, and audit all documentation for stale flag references from PR #83's flag inversions.

1.2 Goals

• Repository hygiene via /zerg:git --action cleanup (branches, refs, worktrees, Docker)
• AI-optimized issue creation via /zerg:git --action issue with strict template
• Consistent /zerg: prefix naming throughout all documentation
• All deprecated flags (--uc, --compact) replaced with current flags (--no-compact, --no-loop, --iterations)

1.3 Non-Goals

• Python runtime implementation (these are Claude Code slash commands — .md files ARE the implementation)
• Removing deprecated flags from cli.py (tracked in issue #84)
• Fixing CI test failures (tracked in issue #85)

2. Architecture

2.1 High-Level Design

This feature is entirely documentation/prompt engineering — no Python code changes except sidebar.py. The "architecture" is the command file structure:

zerg/data/commands/git.md          ← main entry (actions table + flags)
zerg/data/commands/git.core.md     ← quick reference (~30%)
zerg/data/commands/git.details.md  ← deep reference (~70%, action sections)

.zerg/wiki/zerg-*.md               ← renamed from Command-*.md (27 files)
.zerg/wiki/_Sidebar.md             ← navigation with /zerg: prefix
zerg/doc_engine/sidebar.py         ← hardcoded page name references

2.2 Component Breakdown

3. Key Decisions

3.1 Wiki File Naming Convention

Context: Wiki files are Command-init.md but user wants /zerg: prefix everywhere.

Decision: Rename to zerg-init.md (filesystem-safe, no colons).

Rationale: Colons are illegal in filenames on Windows/macOS. zerg- prefix is clean and maps clearly to /zerg:init. Display text in sidebar uses the full /zerg:init form.

3.2 Issue Template Strictness

Context: Issues need maximum detail for AI coding assistants.

Decision: Strict template with 8 mandatory sections: Problem Statement, Root Cause Analysis, Affected Files (with line numbers), Reproduction Steps, Proposed Solution (with code sketches), Acceptance Criteria (with verification commands), Dependencies, Context for AI Assistants.

Rationale: Removes all ambiguity. An AI assistant reading the issue has everything needed to implement a fix without guessing.

3.3 Cleanup Docker Auto-Detection

Context: Should Docker cleanup require an explicit flag?

Decision: Auto-detect ZERG containers. --no-docker flag to skip.

Rationale: If ZERG containers exist, they should be cleaned. Users who want to keep them opt out explicitly.

4. Implementation Plan

4.1 Phase Summary

4.2 File Ownership

4.3 Dependency Graph

L0: T-001 + T-002 + T-003 + T-004 + T-005    [parallel, no deps]
L1: T-006 + T-007                               [parallel, depends on L0]
L2: T-008 + T-009                               [parallel, depends on L1]
L3: T-010 → T-011                               [sequential, depends on L2]

5. Risk Assessment

6. Parallel Execution Notes

6.1 Recommended Workers

• Optimal: 5 workers (matches L0 width)
• Maximum useful: 5 (L0 has 5 parallel tasks, L1-L3 have ≤2)

6.2 Estimated Duration

• Sequential: ~86 min
• With 5 workers: ~43 min
• Speedup: ~2x

9. Approval