Troubleshooting

Use the smallest read-only surface that answers the question before changing workflow state.

Repo-pack health

• flow doctor --json --strict
• If hooks are missing: flow install-hooks
• If doctor reports missing repo-pack files, restore the tracked files under flow/ before debugging anything else.

Active task health

• flow status
• flow check
• flow inspect issue

Typical failures:

• Branch mismatch: switch to the bound issue-<n> or task-<key> branch.
• Plan not ready: run flow plan record ... before tracked edits.
• Missing validation evidence: run flow complete --evidence ....

Acceptance and PR state

• flow accept status
• flow accept check --strict
• flow pr status --json

If a remote request is still unfinished, use:

• flow accept wait-remote --agent <id> --for claim
• flow accept wait-remote --agent <id> --for result
• flow accept sync --agent <id>

Review-context and memory diagnostics

• flow inspect review-context --json --refresh
• flow memory explain search "<query>" --json
• flow memory explain wake-up --json

Benchmark and release diagnostics

• flow eval review-context --config flow/benchmarks/review-context/writeandplay.yaml --json
• flow eval memory-search --config flow/benchmarks/memory-search/writeandplay.yaml --json
• tools/flow-consumer-smoke
• tools/flow-release-check