# Documentation Review

## Overall Summary

Documentation is comprehensive and well-structured. The main issues are: several CLI commands and options exist in the code but are not documented, AGENTS.md has outdated/incomplete command references vs the actual CLI, and a few documented options don't match current `--help` output.

## Accuracy Issues Found

| Issue | Location | Details |
|-------|----------|---------|
| `claude-install-skills` documented but CLI uses `skills-install` | AGENTS.md | AGENTS.md says `gza claude-install-skills` but the actual CLI command is `gza skills-install` |
| `gza log` flags changed | configuration.md | Docs say `--task, -t` and `--slug, -s` and `--worker, -w` are mutually exclusive lookup flags. CLI now uses positional `identifier` arg with `--slug` and `--worker` as modifiers; `--task/-t` flag no longer exists |
| `gza log --turns` deprecated | configuration.md | Docs list `--turns` as primary flag. CLI shows `--turns` is now a deprecated alias for `--steps-verbose`. New flags are `--steps` and `--steps-verbose` |
| `stats` missing options | configuration.md | Docs only show `--last N`. CLI also has `--all`, `--type`, `--days`, `--start-date`, `--end-date`, `--cycles`, `--task ID`, `--json` |
| `review` missing `--model`/`--provider` | configuration.md | CLI has `--model MODEL` and `--provider PROVIDER` flags not in docs |
| `improve` missing `--model`/`--provider` | configuration.md | CLI has `--model MODEL` and `--provider PROVIDER` flags not in docs |
| `merge` missing `--all` and `--resolve` | configuration.md | CLI has `--all` (merge all unmerged) and `--resolve` (AI conflict resolution with --rebase) not in docs |
| `rebase` missing `--background` | configuration.md | CLI has `--background, -b` flag not in docs |
| `unmerged` missing `--commits-only` and `--all` | configuration.md | CLI has `--commits-only` and `--all` flags not in docs |
| `show` missing `--full` | configuration.md | CLI has `--full` flag for untruncated output not in docs |
| `cleanup` missing `--force` | configuration.md | CLI has `--force` flag to skip confirmation not in docs |
| `history` docs say `--limit` | configuration.md | Docs show `--limit N, -n N` but CLI uses `--last N, -n N` |
| `max_steps` vs `max_turns` in quickstart | quickstart.md | Quickstart shows `max_steps: 80` in config example but AGENTS.md only references `max_turns` |
| AGENTS.md missing many commands | AGENTS.md | Missing: `advance`, `checkout`, `clean`, `cleanup`, `config`, `cycle`/`iterate`, `diff`, `edit`, `group`, `groups`, `implement`, `improve`, `learnings`, `log`, `mark-completed`, `merge`, `pr`, `ps`, `rebase`, `refresh`, `resume`, `retry`, `review`, `set-status`, `show`, `stop`, `sync-report`, `unmerged` — AGENTS.md only shows `init`, `work`, `next`, `history`, `stats`, `validate`, `claude-install-skills` |
| `date_slug` branch strategy preset | AGENTS.md | AGENTS.md lists `date_slug` as a branch_strategy preset but configuration.md only lists `monorepo`, `conventional`, `simple` |

## Missing Information

| Topic | Why Users Need It |
|-------|-------------------|
| `gza advance` workflow guide | `advance` is a key command for lifecycle management but has no dedicated guide in examples/ |
| `gza iterate`/`cycle` guide | Automated review/improve cycles are a common workflow but only briefly mentioned in quickstart |
| Environment variable `GZA_MAX_STEPS` | Config docs list `GZA_MAX_TURNS` but not `GZA_MAX_STEPS` |
| `gza learnings` subcommands | `show` and `update` subcommands not documented in configuration.md |
| `gza set-status` valid statuses | `dropped` status not mentioned in configuration.md (only in Task Lifecycle section) |
| Error recovery after `gza advance` | No docs on what to do when advance encounters issues |
| `gza.local.yaml` allowed keys list | Docs say "only approved keys can be overridden" but don't list which keys |

## Minor Issues

- skills.md references `gza-interactive-review` as the skill name but the installed skill name is `gza-code-review-interactive`
- quickstart.md references `Node.js` as prerequisite but doesn't mention it's only needed if using Docker
- quickstart.md shows `gza log -t 1` which uses the removed `-t` flag; should be `gza log 1`
- configuration.md troubleshooting says `gza status <group>` but `status` is an alias for `ps`, not `group`
- AGENTS.md `verify_command` section mentions `task` as a task type but the valid types are `explore`, `plan`, `implement`, `review`, `improve`

## Spec Review

### Outdated Specs

| Spec | Issue | Details |
|------|-------|---------|
| task-workflow-orchestration.md | Missing commands from Phases 3-5 | `gza dashboard`, `gza summary` (CLI), `gza changelog` are described but not implemented. Phase 1-2 (`advance`) is implemented. |
| async-human-in-the-loop.md | Partially implemented | `session_id` field exists but question marker detection and `waiting_input` status not found in code |

### Possibly Aspirational

| Spec | Notes |
|------|-------|
| autonomous-daemon.md | Describes `gza daemon start/stop/status`, budget tracking, goal-directed planning — no implementation found |
| cto-agent.md | Describes conversational CTO agent with briefing mode — no implementation found |
| beads-integration.md | Describes beads integration — no beads code found |
| dspy-integration.md | Describes DSPy integration — no DSPy code found |
| tmux-attach.md | Describes `gza attach` for tmux session viewing — no implementation found |
| watch-loop.md | Describes `gza watch` continuous loop — no implementation found |
| shared-task-state.md | Describes shared task state for distributed execution — likely aspirational |
| rich-console-output.md | Describes rich/TUI console output — may be partially implemented |
| replace-sqlite3-with-python-api.md | Describes replacing sqlite3 module with Python DB-API — not done, still uses sqlite3 directly |

### Specs OK

- task-chaining.md — matches implementation (based_on, depends_on fields work)
- improve-task-type.md — fully implemented
- merge-status-tracking.md — fully implemented with migrations
- failure-reason-tracking.md — fully implemented
- max-steps-abstraction-spec.md — fully implemented with backward compatibility
- learning-accumulation.md — fully implemented
- pr-code-review.md — fully implemented
- task-provider-routing.md — fully implemented
- branch-naming-strategies.md — implemented (presets and custom patterns)
- task-import.md — implemented (gza import command works)
- task-resume.md — implemented (gza resume command works)
- review-improve-loop.md — implemented (gza iterate/cycle command)
- pypi-publishing.md — implemented (package published as gza-agent)
- codex-provider.md — implemented
- concurrent-work.md — implemented (background workers, worktrees)
- docker-testing.md — implemented
- rebase-resolve.md — implemented (gza rebase --resolve)
- message-step-logging.md — implemented (step tracking in logs)
- plan-persistence.md — implemented (plans stored in .gza/plans/)

## Recommendations

1. **Update AGENTS.md command reference** — it only lists 7 commands but 40+ exist. At minimum add the commonly-used ones: `advance`, `review`, `improve`, `merge`, `pr`, `log`, `unmerged`
2. **Fix `gza log` flags in configuration.md** — remove `--task/-t`, document new `--steps`/`--steps-verbose` flags
3. **Update `stats` docs** — add the many missing options (`--cycles`, `--json`, date filters)
4. **Add missing `--model`/`--provider` flags** to `review` and `improve` command docs
5. **Fix `claude-install-skills` → `skills-install`** in AGENTS.md
6. **Fix `gza log -t 1` → `gza log 1`** in quickstart.md
7. **Add `merge --all` and `merge --resolve`** to merge command docs
8. **Document `date_slug` branch strategy** or remove from AGENTS.md if it doesn't exist
