# Documentation Review

## Overall Summary

Documentation covers core workflows well but has fallen significantly out of sync with the CLI. 8 commands are completely undocumented, the PyPI README uses nonexistent commands, and several documented behaviors are wrong (task type `task` removed, `status` command misdescribed, wrong Gemini CLI package name).

## Accuracy Issues Found

| Issue | Location | Details |
|-------|----------|---------|
| PyPI README uses nonexistent commands | README_PYPI.md:28-35 | `gza task add`, `gza worker start`, `gza task list` don't exist. Should be `gza add`, `gza work`, `gza ps`/`gza history` |
| Skills doc uses old command name | docs/skills.md:8-14 | References `gza claude-install-skills`. Actual command is `gza skills-install` |
| Wrong Gemini CLI package | docs/quickstart.md:28 | `npm install -g @anthropic-ai/gemini-cli` — should be `@google/gemini-cli` (Google, not Anthropic) |
| `task` type still documented but removed | docs/configuration.md:373,799 | `add --type` lists `task` but CLI only accepts `{explore,plan,implement,review,improve}`. DB migration v19→v20 renamed `task` to `implement` |
| `task` type in bulk import example | docs/examples/bulk-import.md:27,45,89 | Uses `type: task` which is no longer valid |
| `status` command misdescribed | docs/configuration.md:515-519 | Documented as "Show tasks in a group" but it's actually "List running workers (alias for ps)". The `group` command shows tasks in a group |
| `max_steps` missing from config table | docs/configuration.md | Appears in resolution precedence but not in the Optional Configuration table. `DEFAULT_MAX_STEPS = 50` exists in code |
| Default task type not stated | docs/configuration.md, quickstart.md | Default type for `gza add` is `implement` (not `task`), but docs don't clearly state this |

## Missing Information

| Topic | Why Users Need It |
|-------|-------------------|
| `gza advance` command | Major orchestration command (dry-run, batch, auto-resume, review cycles, squash-merge). Critical for automated workflows |
| `gza implement` command | Standalone command to create implementation from a plan. Has --queue, --background, --no-docker, --model, --provider flags |
| `gza iterate` / `gza cycle` command | Automated review/improve cycle for implementation tasks. Has --max-iterations, --dry-run, --continue |
| `gza learnings` command | Manage project learnings (show/update subcommands) |
| `gza refresh` command | Refresh cached diff stats for unmerged tasks. Has --include-failed flag |
| `gza set-status` command | Manually force a task's status (pending, in_progress, completed, failed, dropped) |
| `gza sync-report` command | Sync report file content from disk into DB output_content |
| `gza group` command | Show tasks in a specific group (distinct from `status` which is ps alias) |
| `--model` flag on add/implement | Override model per-task (e.g., `--model claude-3-5-haiku-latest`) |
| `--provider` flag on add/implement | Override provider per-task (claude, codex, gemini) |
| `--no-learnings` flag on add/implement | Skip injecting learnings context |
| `gza advance` config options | `max_resume_attempts`, `max_review_cycles`, `merge_squash_threshold` — not in config reference |
| `dropped` task status | Listed in `set-status` but not in Task Lifecycle section |
| Skills documentation incomplete | docs/skills.md only covers 5 of 11+ skills (missing: gza-test-and-fix, gza-task-debug, gza-task-draft, gza-code-review-full, gza-code-review-interactive, gza-plan-review, gza-docs-review) |

## Minor Issues

- docs/skills.md references `gza claude-install-skills --list` — should be `gza skills-install --list`
- docs/skills.md says "Install specific skills" with old command syntax
- docs/configuration.md line 232: `GZA_BRANCH_MODE` listed but `branch_mode` config (line 26) is for `single`/`multi`, while `branch_strategy` (line 75) handles naming — potential confusion
- README.md lists Gemini as "Partially implemented, coming soon" — should note Codex is also supported
- docs/examples/README.md quick reference doesn't include `gza advance`, `gza implement`, `gza iterate`
- docs/configuration.md `tasks_file` references legacy `tasks.yaml` — may want to note this is deprecated or remove

## Spec Review

Not performed in this review — specs directory contains 29 spec files. A separate spec review pass is recommended.

## Recommendations

1. **Fix README_PYPI.md immediately** — this is what PyPI users see first, and the commands are completely wrong
2. **Fix docs/skills.md command name** — `claude-install-skills` → `skills-install`
3. **Fix Gemini CLI package name** in quickstart — `@anthropic-ai/gemini-cli` → `@google/gemini-cli`
4. **Remove `task` type references** from all docs — it was migrated to `implement`
5. **Fix `status` command description** in configuration.md — it's a `ps` alias, not group viewer
6. **Document `advance` command** — it's the primary automation/orchestration command and has no docs at all
7. **Document `implement`, `iterate`, `learnings`, `refresh`** — these are user-facing commands with no reference
8. **Add `max_steps` to config table** and document advance-related config options
9. **Update skills.md** with all available skills and correct install command
10. **Add `dropped` status** to Task Lifecycle section
