Proposal: round-aware reviews — track findings across multiple `/octo:review` runs on the same PR

[99xAgency]

Problem

Today, running /octo:review twice on the same PR treats each invocation as
independent. The reviewers see only the current diff — not what they (or the
other providers) flagged in the previous round, what was addressed, what's
still open, or what regressed.

In an iterative review workflow ("Codex flagged 3 issues, I fixed 2 and pushed,
review again"), the second pass lacks the context that would make it most
useful. The state manager tracks workflow phases (Discover → Define → Develop
→ Deliver) but not iterations of a single artefact.

Proposed shape

Per-PR state at ~/.claude-octopus/pr-state/<repo>/<pr-number>.json, populated
by /octo:review and consumed by subsequent runs:

• Round number, head SHA at time of review, findings array per provider
• On run N+1, augment the dispatch prompt with: previous findings + git diff
  since round N's SHA + a brief "addressed / persistent / new / regressed"
  classification

Optional companion command: /octo:review-history <pr> to print the timeline.

Why I'm asking before building

Happy to send a PR — but only if this fits the project's direction. A few open
questions:

1. Is per-artefact iteration state in scope, or do you want that left to
   claude-mem / external tooling?
2. If in scope, should it live in the existing state-manager.sh or as a
   sibling pr-review-state.sh?
3. Any concerns about extra Bash/JSON state files vs the current model?

If the answer is "yes please, here's how we'd want it shaped" — I'll fork
and submit. If it's a "no, intentional gap" — equally happy to hear that and
build it elsewhere.

Thanks for octopus, by the way — the multi-provider consensus model is the
cleanest take on this I've seen.

[nyldn]

Triaged as a valid future enhancement. Directionally this fits best as review-specific state alongside the existing review pipeline, not as part of the bugfix PR for dispatch/PID handling. Leaving open for design/scoping.

[nyldn]

Thanks for the thoughtful write-up — and for asking before forking. Greenlight with shape notes below. If this matches what you had in mind, please open a PR.

Edit (2026-04-29): Revised the surface section after a discoverability discussion. Flags have the same problem as new commands — nobody reads --help. Switched to auto-detect + inline timeline.

Edit 2 (2026-04-29): Tightened the implementation brief: keep this as a sourced review-state module, preserve the current review finding contract (normal|nit|pre-existing severities), and make fresh a slash-command UX that maps to structured profile state for shell/MCP/OpenClaw callers.

Direction

In scope. Per-artefact iteration state fits the multi-provider differentiator — knowing "Codex flagged X round 1, Gemini missed it, regressed in round 3" is exactly the kind of cross-provider signal /octo:review should compound. Not claude-mem's job (that's generic narrative memory; this is structured PR artefact state with a defined schema).

Shape

Sibling review-state module, likely scripts/lib/pr-review-state.sh if it is sourced by the review pipeline. Do not fold it into state-manager.sh. The existing state manager is workflow-phase shaped (Discover → Define → Develop → Deliver) and already 511 LOC; PR iteration is a different concern with a different lifecycle. Keep them split. If a standalone debugging surface is useful later, add a thin CLI wrapper around the library functions.

Storage: ~/.claude-octopus/pr-state/<host>/<owner>/<repo>/<pr-number>.json — host segment matters (GitHub Enterprise, self-hosted Gitea, etc.).

Schema (please draft in the issue before coding)

Suggested skeleton — iterate on this:

{
  "schema": 1,
  "pr": {"host": "github.com", "repo": "nyldn/claude-octopus", "number": 322},
  "rounds": [
    {
      "n": 1,
      "head_sha": "abc123",
      "timestamp": "2026-04-29T18:00:00Z",
      "providers": ["codex", "gemini", "claude"],
      "findings": [
        {"id": "f-001", "providers": ["codex"], "severity": "normal",
         "file": "scripts/foo.sh", "line": 42, "category": "logic",
         "title": "Missing null check", "detail": "...", "confidence": 0.92,
         "status": "open"}
      ]
    }
  ]
}

The example above intentionally follows the current /octo:review finding contract: file, line, severity, category, title, detail, confidence, with severity as normal|nit|pre-existing. If you want to introduce a richer severity model later, treat that as a separate schema/migration decision rather than mixing it into this first pass.

Round N+1 augments dispatch prompt with: prior findings + git diff <prev_sha>..HEAD + classifier output (addressed / persistent / new / regressed). If the previous SHA is unavailable after a rebase/force-push, degrade gracefully: mark prior state stale or skip classification for that round rather than inventing continuity.

Surface — auto-detect, surface inline (revised)

Original draft proposed --history / --no-history / --reset flags. Bad call. Flags have the same discoverability tax as new commands — users don't read --help any more than they read the command list. Better default: make it smart, surface the value inline.

Auto-on by default. /octo:review already resolves PR context via gh. If pr-state/<...>/<pr>.json exists → round-aware mode fires automatically. Zero discovery cost. First review writes round 1 silently; second invocation gets the value without the user knowing the feature exists.

Inline timeline in the existing review banner. No new command, no flag to remember:

🐙 Round 2 of N — head abc123 (round 1 was def456, 2h ago)

Carry-over from round 1:
  ✓ Addressed: 2  (foo.sh:42 logic, bar.sh:88 null-check)
  ⚠ Persistent: 1 (baz.sh:120 — Codex flagged again)
  🆕 New: 3
  🔁 Regressed: 0

Users learn the feature by seeing it work.

Post-run nudge for clean-slate reruns. One line at end of output, only when state was used:

[Round-aware mode used prior findings. Want a clean slate? Run /octo:review fresh]

fresh should be a positional slash-command UX, but internally it should map to structured review profile state, e.g. "history":"fresh", so shell, MCP, and OpenClaw callers can get the same behavior without parsing freeform command text.

Global opt-out via env var, surfaced in /octo:setup post-install summary:

Round-aware reviews: ENABLED — /octo:review tracks findings across iterations.
                              Disable: OCTOPUS_PR_HISTORY=0

Net surface delta:

• Auto-detect via state file presence (no --history flag)
• fresh positional arg for one-shot reset (no --reset flag)
• Structured profile field for non-slash callers, e.g. history=fresh
• OCTOPUS_PR_HISTORY=0 env var for global opt-out (no --no-history flag)
• Timeline output inline in standard banner, not behind any toggle
• No /octo:review-history command

Constraints (non-negotiable)

• schema field, versioned. Forward-compat from day one — migrations are cheap when planned, expensive when retrofitted.
• Preserve the current review finding contract. Store synthesized findings using the existing normal|nit|pre-existing severity vocabulary unless the schema draft explicitly proposes a migration.
• Provider drift. Round 1 = Codex+Gemini, Round 2 adds Perplexity. Classifier must handle missing-provider rounds without crashing or false-flagging "regressed".
• TTL / cleanup. PR closed/merged/force-pushed → state goes stale. On read, use gh pr view --json state,headRefOid where available; prune closed PRs older than 30 days; if stored SHAs cannot be compared, skip continuity rather than misclassifying.
• Diff cap. Skip persistence (or truncate findings) if PR diff exceeds a threshold — don't blow up the JSON file on a 50k-line refactor.
• macOS bash 3.2 compat. No ${var,,}, no mapfile, no ((VAR++)) (use VAR=$((VAR+1))). Check CLAUDE.md gotchas list.
• BSD/GNU sed conditionals if used. No command grouping (sed '/pat/,/pat/{...}') — use awk for multi-line.
• No set -u escalation. If sourced, match state-manager.sh (set -eo pipefail, not -euo) — see [BUG] octo:embrace doesn't detect bash version #108, [BUG] PURPLE unbound variable crashes setup_wizard #189.
• Tests. Use ALL_SRC pattern + test-framework.sh. Add unit coverage for state path generation, schema validation, read/write, stale-state handling, and classification fixtures. Smoke + unit should pass on both ubuntu-latest and macos-latest.

Privacy

Findings JSON contains code snippets and AI commentary. State lives under ~/.claude-octopus/, not in the repo, so no .gitignore concern — but document the storage path in the command help and /octo:setup summary so users know where it lives.

Suggested PR sequence

1. Draft schema in this issue first. Iterate on field names / classifier semantics before any code. Cheap to change here, expensive to change post-merge.
2. PR 1: scripts/lib/pr-review-state.sh + tests, no integration. Pure path/read/write/schema/classify helpers, no /octo:review behavior changes. Mergeable in isolation.
3. PR 2: Wire into scripts/lib/review.sh and commands/review.md: dispatch prompt augmentation, inline timeline banner, fresh profile mode, OCTOPUS_PR_HISTORY env var.
4. PR 3: TTL/cleanup hook, closed-PR pruning, /octo:setup summary line.

Splitting like this keeps reviews tractable and gives us rollback granularity if any layer misbehaves.

Open question for you

How do you want findings de-duplicated across providers? My default would be one logical synthesized finding with providers/sources listing the providers that raised it, but there is a real alternative where each provider's finding remains separate. This affects classifier semantics: is a finding "addressed" only when all providers stop flagging it, or when the synthesized logical finding no longer reproduces? Worth deciding before round-trip code.

Excited to see this land. Ping here when the schema draft is up.