Requirements: Documentation Audit & Sync

Requirements: Documentation Audit & Sync

Status: APPROVED Created: 2026-02-06 Feature: documentation-audit-sync Trigger: PR #166 shipped --tone flag but wiki/docs updates were incomplete

Problem Statement

PR #166 claimed to "Update CHANGELOG, README, CLAUDE.md, wiki, and command docs" for the --tone flag, but the wiki Command-Reference received only a single table row (+1 line). No explanation, no examples, no tone descriptions. This is symptomatic of a broader pattern: new flags ship without full documentation coverage across all documentation surfaces.

A complete audit reveals multiple flags exist in the Python CLI code that are missing or underrepresented across the documentation ecosystem.

Audit Findings

Critical Gaps (flags in code, missing from docs)

/zerg:rush — 4 flags missing from commands-quick.md AND wiki

/zerg:plan — 1 flag missing from commands-quick.md AND wiki

/zerg:debug — 2 flags missing from commands-quick.md

/zerg:merge — 1 flag missing from commands-quick.md

/zerg:retry — 1 flag missing from commands-quick.md

/zerg:analyze — 1 flag missing from commands-quick.md

Incomplete Documentation (flag listed but inadequately described)

Wiki Command-Reference.md: /zerg:document --tone

• Current: Single table row: | --tone | educational|reference|tutorial | educational | Documentation tone — controls output style |
• Missing: No explanation of what each tone does, no examples showing output differences, no mention of config default, no workflow diagram update

Wiki Command-Reference.md: /zerg:git --admin

• Current: Brief mention in ship section flags table
• Missing: No "Why Use It" explanation, no example showing when admin merge is needed

Documentation Surface Coverage

Functional Requirements

FR-1: Fix Missing Flags in commands-quick.md

Add all 10 missing flags to docs/commands-quick.md in the correct command sections:

• /zerg:rush: --check-gates, --what-if, --risk, --skip-tests
• /zerg:plan: --from-issue
• /zerg:debug: --deep, --env
• /zerg:merge: --target
• /zerg:retry: --worker
• /zerg:analyze: --performance

Each flag entry must include: flag name, type, default, and description matching the Python click option help text.

FR-2: Fix Missing Flags in Wiki Command-Reference.md

Add all 10 missing flags to .gsd/wiki/Command-Reference.md in the correct command sections. Follow the existing format: flag tables with description.

For /zerg:rush, also update the "Using It" section to show examples of --what-if and --risk.

FR-3: Expand /zerg:document --tone in Wiki

Replace the stub --tone row in wiki Command-Reference.md with a full explanation:

1. Add a "Tone Options" subsection (like the existing "Depth Levels" in the wiki)
2. Describe each tone value (educational, reference, tutorial) with 2-3 sentences
3. Add usage examples showing --tone with each value
4. Mention config default (documentation.default_tone in .zerg/config.yaml)
5. Update the workflow diagram to show tone selection step

FR-4: Expand /zerg:document --tone in Wiki Tutorial

Update .gsd/wiki/Tutorial.md to include a hands-on example of --tone usage in the documentation section (currently only 3 lines at the end). Show before/after output for at least educational vs reference tones.

FR-5: Sync commands-deep.md with All Current Flags

Verify and update the /zerg:document section in docs/commands-deep.md to ensure it matches the current codebase. Specifically:

• --tone section exists and is complete (already done in PR #166 — verify)
• All other command sections that have new flags are updated

FR-6: Push Wiki Changes to GitHub

After all wiki files are updated, the changes must be pushed to the GitHub wiki repo so they appear at https://github.com/rocklambros/zerg/wiki/.

FR-7: Update CHANGELOG.md

Add entry under [Unreleased] → Changed:

• docs: comprehensive documentation audit — sync all commands and flags across wiki, command references, and tutorials

Non-Functional Requirements

NFR-1: Consistency

All documentation surfaces must agree on:

• Flag names and types
• Default values
• Description wording (can vary in detail level but must not contradict)

NFR-2: Educational Tone for Wiki

All wiki updates should follow the educational tone pattern: explain why before how, include diagrams where helpful.

NFR-3: No Code Changes

This is a documentation-only feature. No Python code, no template changes, no test changes.

Acceptance Criteria

1. All 10 missing flags appear in docs/commands-quick.md
2. All 10 missing flags appear in .gsd/wiki/Command-Reference.md
3. /zerg:document --tone has full explanation in wiki (not just a table row)
4. /zerg:document --tone has hands-on example in wiki Tutorial
5. docs/commands-deep.md matches current codebase for all commands
6. Wiki changes are pushed to GitHub wiki
7. CHANGELOG.md updated
8. No contradictions between any documentation surface

Scope Boundaries

In Scope

• docs/commands-quick.md flag additions
• .gsd/wiki/Command-Reference.md flag additions + tone expansion
• .gsd/wiki/Tutorial.md tone example
• docs/commands-deep.md verification/fixes
• CHANGELOG.md update
• Wiki push to GitHub

Out of Scope

• Python code changes
• New documentation pages
• Template changes
• Test changes
• README.md changes (already adequate)
• CLAUDE.md changes (already adequate)

Files to Modify

Documentation Impact Analysis

This IS the documentation update feature. No additional documentation surfaces needed.

Dependencies

• Current codebase on main branch (source of truth for flags)
• GitHub wiki push access

Open Questions

None.