Troubleshooting

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

Repo-pack health

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

Active task health

• wap-flow status
• wap-flow check
• wap-flow inspect issue

Typical failures:

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

Acceptance and PR state

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

If a remote request is still unfinished, use:

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

Review-context and memory diagnostics

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

Benchmark and release diagnostics

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