# Documentation Review

## Overall Summary

The documentation is generally well-organized and accurate for core commands. However, several documented commands have inaccurate flag descriptions, multiple undocumented commands exist, and several spec files describe features that are either aspirational or outdated.

## Accuracy Issues Found

| Issue | Location | Details |
|-------|----------|---------|
| `gza clean` docs outdated | [configuration.md:348-378](docs/configuration.md#L348-L378) | Docs say `--dry-run` shows "what would be deleted" but CLI actually does archiving by default with `--purge` for deletion. Missing `--purge` flag entirely. |
| `gza delete` flag outdated | [configuration.md:341](docs/configuration.md#L341) | Docs show `--force`, `-f` but CLI has deprecated this in favor of `--yes`, `-y` |
| `gza merge` missing flags | [configuration.md:478-485](docs/configuration.md#L478-L485) | Missing `--remote` and `--mark-only` flags that exist in CLI |
| `gza edit` missing options | [configuration.md:286](docs/configuration.md#L286) | Missing `--review`, `--prompt-file`, `--prompt` flags |
| `gza history` missing options | [configuration.md](docs/configuration.md) | `gza history` command not documented at all, but exists with `--limit`, `--all`, `--status`, `--type` flags |
| `gza log` syntax incorrect | [configuration.md:293-307](docs/configuration.md#L293-L307) | Docs don't mention that `--task`, `--slug`, or `--worker` flags are mutually exclusive and one is required |
| `gza resume`/`retry` missing flags | [configuration.md:448-470](docs/configuration.md#L448-L470) | Missing `--run` and `--max-turns` flags |
| `gza work` missing flag | [configuration.md:240-252](docs/configuration.md#L240-L252) | Missing `--max-turns` flag |

## Missing Information

### Undocumented Commands

| Command | Why Users Need It |
|---------|-------------------|
| `gza checkout` | Users need to know how to checkout a task's branch, especially with `--force` for stale worktrees |
| `gza diff` | Users doing code review need to see task changes vs main |
| `gza rebase` | Users need to rebase task branches onto main; has `--onto`, `--remote`, `--force` flags |
| `gza history` | Core command for viewing completed/failed tasks with filtering |
| `gza cleanup` | Different from `gza clean` - removes stale worktrees, logs, and workers |
| `gza improve` | Critical for iterate-on-review workflow; docs in AGENTS.md but not configuration.md |

### Missing Conceptual Documentation

| Topic | Why Users Need It |
|-------|-------------------|
| Task types reference | No single place explaining all task types (task, explore, plan, implement, review, improve) and their behaviors |
| Worktree lifecycle | Users don't know when worktrees are created/deleted or how to manage them |
| Session resume semantics | When resume works vs when retry is needed; session expiration |
| Cost estimation | No guidance on expected costs per task type |
| Output file locations | Where plans, reviews, summaries, explorations are saved is scattered |
| Branch cleanup | When/how branches are deleted; `--delete` flag vs manual cleanup |

### Missing from Quickstart/README

| Item | Impact |
|------|--------|
| Claude Code installation | Quickstart assumes `claude` CLI is installed but doesn't mention `npm install -g @anthropic-ai/claude-code` |
| Docker requirements | Must have Docker installed for default behavior |
| First task walkthrough | No end-to-end example from install to merged PR |

## Minor Issues

- [configuration.md:627-628](docs/configuration.md#L627-L628): References `gza next` for "No pending tasks" troubleshooting, but `gza next` is not documented in the command reference section
- [AGENTS.md:89-90](AGENTS.md#L89-L90): References `tests/test_cli.py` patterns but doesn't explain fixture patterns
- [docs/docker.md](docs/docker.md): Example Python Dockerfile installs uv but path setup may not work in all cases
- Several docs use `--project` but CLI help shows `-C` as the short form (both work, but inconsistent)
- [configuration.md:31](docs/configuration.md#L31): `claude_args` default shown but may be outdated

## Spec Review

### Outdated Specs

| Spec | Issue | Details |
|------|-------|---------|
| [specs/concurrent-work.md](specs/concurrent-work.md) | Command name changed | Spec references `gza logs <worker_id>` but implemented as `gza log -w <worker_id>` |
| [specs/task-resume.md:160-165](specs/task-resume.md#L160-L165) | Missing options | Spec shows only `--no-docker` but CLI has `--run`, `--max-turns`, `--background` |
| [specs/docker-testing.md](specs/docker-testing.md) | Package name | Shows `uv pip install --system gza` but package is `gza-agent` per quickstart |
| [specs/rich-console-output.md:58-65](specs/rich-console-output.md#L58-L65) | File references | References specific line numbers in runner.py that may have shifted |
| [specs/rebase-resolve.md](specs/rebase-resolve.md) | Not implemented | Describes `--resolve` flag for `gza rebase` that doesn't exist in CLI |

### Possibly Aspirational (needs human review)

| Spec | Notes |
|------|-------|
| [specs/beads-integration.md](specs/beads-integration.md) | Describes integration with beads issue tracker - no beads code found in src/ |
| [specs/task-workflow-orchestration.md](specs/task-workflow-orchestration.md) | Describes `gza dashboard`, `gza advance`, `gza summary`, `gza changelog` commands that don't exist |
| [specs/codex-provider.md](specs/codex-provider.md) | Describes OpenAI Codex provider - likely aspirational, no codex provider in codebase |

### Specs OK

- [specs/task-chaining.md](specs/task-chaining.md) - matches implementation for `depends_on`, `same_branch`, groups
- [specs/improve-task-type.md](specs/improve-task-type.md) - matches `gza improve` command implementation
- [specs/pr-code-review.md](specs/pr-code-review.md) - matches review/PR integration; spec notes implementation status

## Recommendations

1. **Add undocumented commands to configuration.md**: `checkout`, `diff`, `rebase`, `history`, `cleanup`, `improve`

2. **Update `gza clean` documentation**: Change description from "delete old files" to "archive old files" and document `--purge` flag

3. **Add task types reference**: Create a section explaining each task type's purpose, output location, and typical usage

4. **Fix flag inconsistencies**: Update `delete --force` to `delete --yes`, add missing flags to resume/retry/work

5. **Document session/worktree lifecycle**: Explain when worktrees are created, when they persist, and when they're cleaned up

6. **Mark aspirational specs**: Add header notes to specs for unimplemented features (dashboard, advance, codex, beads)

7. **Add Claude Code installation to quickstart**: Users need `npm install -g @anthropic-ai/claude-code`

8. **Update specs/docker-testing.md**: Change package name from `gza` to `gza-agent`
