Skip to content

feat: add brainstorm panel review pack#42

Merged
El-Fitz merged 4 commits into
mainfrom
feat/brainstorm-panel-review-pack
Jun 3, 2026
Merged

feat: add brainstorm panel review pack#42
El-Fitz merged 4 commits into
mainfrom
feat/brainstorm-panel-review-pack

Conversation

@El-Fitz

@El-Fitz El-Fitz commented Jun 2, 2026

Copy link
Copy Markdown
Contributor

Summary

  • record the Pi-backed L2 brainstorm iteration benchmark results
  • add refinery review-brainstorm-panels to generate blind panel review packets plus an answer key
  • document the first-pass L2 panel review and keep score-only as the recommended production default

Verification

  • cargo fmt --all -- --check
  • cargo test -p refinery_cli review_brainstorm_panels
  • cargo clippy -p refinery_cli --all-targets -- -D warnings

@coderabbitai

coderabbitai Bot commented Jun 2, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@El-Fitz, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 43 minutes and 20 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 64880eee-db11-415d-8734-1c8ee498b1ff

📥 Commits

Reviewing files that changed from the base of the PR and between 3c2bd74 and 1ec520a.

📒 Files selected for processing (2)
  • crates/refinery_cli/src/commands/review_brainstorm_panels.rs
  • docs/HANDOFF.md
📝 Walkthrough

Walkthrough

This PR adds a new CLI command review-brainstorm-panels that generates blind review packets from brainstorm run directories by loading evaluation artifacts, extracting answers, selecting panel subsets using various strategies (including lexical dissimilarity), and emitting both a public blind pack and a hidden answer key. Benchmark results for L2 iteration strategies are documented alongside a qualitative panel review analysis, with infrastructure updated to support large Pi JSON event streams.

Changes

Blind Panel Review Pack Generator Command

Layer / File(s) Summary
CLI arguments and output data contracts
crates/refinery_cli/src/commands/review_brainstorm_panels.rs (lines 1–151)
ReviewBrainstormPanelsArgs struct with fields for run dirs, panel selector, strategy filters, prompt-text overrides, and output format; PanelSelector enum mapping selector names; Candidate model with scores; and ReviewPack/ReviewAnswerKey structures for JSON serialization.
Run discovery and evaluation artifact loading
crates/refinery_cli/src/commands/review_brainstorm_panels.rs (lines 242–420)
Locates final round directories, loads evaluation JSON artifacts with per-model score aggregation (ignoring evaluator ≠ evaluatee), reads proposal markdown files, extracts answer text via markdown-fence and malformed-wrapper aware JSON parsing with fallback handling.
Panel selection strategies and lexical dissimilarity
crates/refinery_cli/src/commands/review_brainstorm_panels.rs (lines 421–571)
Implements deterministic selectors for mean/stddev/controversy, controversy-with-quality-floor+backfill logic, and quality_x_lexdiv iterative selection maximizing lexical token dissimilarity with stopword filtering.
Review pack assembly and output
crates/refinery_cli/src/commands/review_brainstorm_panels.rs (lines 152–214, 573–728), unit tests (lines 730–805)
Groups runs by prompt ID with deterministic blind shuffle (hiding strategies), assigns panel/answer labels, constructs ReviewPack/ReviewAnswerKey, emits JSON or Markdown, writes answer key to disk; includes tests for prompt-text parsing, answer extraction variants, and strategy hiding verification.

CLI Integration and Infrastructure

Layer / File(s) Summary
Command registration and documentation
crates/refinery_cli/src/main.rs, crates/refinery_cli/src/commands/mod.rs, crates/refinery_cli/src/commands/README.md
Adds ReviewBrainstormPanels enum variant to Command dispatcher in main.rs, exports review_brainstorm_panels submodule, and documents the command with example usage and review scoring dimensions in README.
Response buffer and streaming infrastructure
crates/tundish_providers/src/process.rs, todos/026-stream-parse-pi-json-events.md
Increases MAX_RESPONSE_SIZE from 1MB to 64MB to accommodate large Pi JSON event streams; creates TODO 026 tracking future incremental streaming parser to avoid buffering entire responses while preserving timeout and error handling.

L2 Iteration Strategy Benchmark Results and Panel Review Analysis

Layer / File(s) Summary
Benchmark execution and quantitative results
docs/brainstorms/2026-05-30-brainstorm-l2-iteration-strategy-benchmark.md
Documents L2 benchmark design (Pi-backed routing, six-prompt suite, four strategies: blind/score-only/own-reviews/full-visibility), aggregate selector metrics across mean/stddev/controversy/controversy_floor_7 with quality/disagreement/overlap/meta columns, operational notes about earlier concurrent Pi lock contention and stdout overflow, and mitigation via serial execution and 64MB buffer.
Qualitative panel review and strategy comparison
docs/brainstorms/2026-06-01-brainstorm-l2-panel-review.md
Records first-pass qualitative review using blind L2 panel pack with per-prompt 1–5 ratings across five dimensions (score quality, diversity, challenger value, overlap concern, regret), strategy-level aggregates, and five qualitative findings comparing full-visibility vs. score-only quality tradeoff, own-reviews positioning, and lexical convergence concerns.
Research plan and tracking updates
docs/plans/2026-05-23-001-research-brainstorm-strategy-benchmarks-plan.md, todos/013-brainstorm-strategy-benchmarks.md, docs/HANDOFF.md
Adds dated addenda for L2 iteration suite completion, blind generator implementation, and first-pass review; expands implementation progress with benchmark metrics table and qualitative conclusions; updates verification checklist; refreshes TODO 013 deliverables and status; updates handoff document with recent context, next clean session steps, and new TODO 026 entry for streaming optimization.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

  • Lightless-Labs/refinery#37: Introduces quality-floor selection and strategy naming conventions that directly support the panel selection strategies and recommendation logic in this PR's blind review pack generator.

Poem

A rabbit shuffles runs through careful blind,
Hides strategies while answers intertwine,
Lexical dissimilarity shines bright,
The panel speaks—yet strategies take flight! 🐰✨
Score-only keeps its throne another night.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 17.14% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The pull request title directly and clearly summarizes the main code change: adding a new brainstorm panel review pack command.
Description check ✅ Passed The pull request description is directly related to the changeset, detailing the three main objectives (benchmark results, CLI command addition, and documentation) that align with the file changes.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/brainstorm-panel-review-pack

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a new CLI command review-brainstorm-panels to generate blind brainstorm panel review packs and corresponding answer keys. It also increases the maximum captured stdout size for provider processes to 64MB to accommodate large Pi JSON event streams, adds comprehensive documentation, and updates plans and TODOs regarding iteration strategy benchmarks. Feedback on the changes highlights a bug in the new command where specifying a relative path with no directory components for the answer key path causes std::fs::create_dir_all to fail with a NotFound error.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

Comment on lines +233 to +236
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent)
.map_err(|e| format!("failed to create {}: {e}", parent.display()))?;
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

When --key-path is specified as a relative path with no directory components (e.g., panel-review-key.json as shown in the README.md example), path.parent() returns Some("") (the empty path). Calling std::fs::create_dir_all("") will fail on Unix/Linux with a NotFound error, causing the entire command to abort.

To fix this, ensure that create_dir_all is only called when the parent path is not empty.

Suggested change
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent)
.map_err(|e| format!("failed to create {}: {e}", parent.display()))?;
}
if let Some(parent) = path.parent() {
if !parent.as_os_str().is_empty() {
std::fs::create_dir_all(parent)
.map_err(|e| format!("failed to create {}: {e}", parent.display()))?;
}
}

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 1ec520a: write_answer_key now skips create_dir_all for bare filename paths, and the new unit test covers this documented usage.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3c2bd74b3d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

proposal_path.display()
)
})?;
let answer = proposal_answer_text(&proposal);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve already-parsed proposal text

For current brainstorm artifacts, propose-*.md is already the parsed user-facing answer (the brainstorm saver writes round.proposals directly), so reparsing it as a JSON wrapper can corrupt legitimate answers. If a generated answer starts with a fenced JSON example like json {"answer":"..."} , the review packet emits only that inner field instead of the full proposal, which changes what reviewers score. The wrapper extraction should only be used for known raw transport responses, not unconditionally for saved proposal text.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 1ec520a: saved propose-*.md artifacts are now preserved verbatim in review packs instead of being reparsed as JSON wrappers.

coderabbitai[bot]
coderabbitai Bot previously requested changes Jun 2, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/refinery_cli/src/commands/review_brainstorm_panels.rs`:
- Around line 254-257: The code currently treats metadata.iteration_strategy and
CLI --strategies as free text; instead, validate and normalize them against the
canonical brainstorm strategy enum (the enum declared in
crates/refinery_core/src/brainstorm.rs, e.g. the brainstorm iteration strategy
enum) so typos fail fast. Change the load/usage path: when reading
metadata.iteration_strategy from load_run_metadata and when parsing the
--strategies CLI input, map the string to the enum (using a FromStr/parse
function or explicit matcher on the enum) and return a clear error if the string
is not a known variant; update any downstream uses to consume the enum variant
rather than raw String. Ensure you reference and use the enum type (rather than
raw strings) in the logic handling iteration_strategy and --strategies.
- Around line 232-236: The code in write_answer_key calls create_dir_all on
path.parent() even when the parent is an empty path (e.g., when --key-path is
just "panel-review-key.json"), causing failure; change the logic in
write_answer_key to only call std::fs::create_dir_all(parent) if
parent.as_os_str() is not empty (or otherwise has components) after obtaining
parent via path.parent(), so skip create_dir_all for a bare filename and
preserve the existing map_err behavior when creating real directories fails.

In `@docs/HANDOFF.md`:
- Line 5: The Last updated timestamp in docs/HANDOFF.md currently reads "**Last
updated:** 2026-06-01" and should be updated to the actual edit date for this
PR; replace that string with "**Last updated:** 2026-06-02" in docs/HANDOFF.md
and ensure the file is updated at session end or before compaction per the
handoff guidance so it reflects current project state, architecture gotchas,
open work, and review process.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c9d4b15b-7f7e-494a-a9c4-d900fd7310dc

📥 Commits

Reviewing files that changed from the base of the PR and between defabfa and 3c2bd74.

📒 Files selected for processing (11)
  • crates/refinery_cli/src/commands/README.md
  • crates/refinery_cli/src/commands/mod.rs
  • crates/refinery_cli/src/commands/review_brainstorm_panels.rs
  • crates/refinery_cli/src/main.rs
  • crates/tundish_providers/src/process.rs
  • docs/HANDOFF.md
  • docs/brainstorms/2026-05-30-brainstorm-l2-iteration-strategy-benchmark.md
  • docs/brainstorms/2026-06-01-brainstorm-l2-panel-review.md
  • docs/plans/2026-05-23-001-research-brainstorm-strategy-benchmarks-plan.md
  • todos/013-brainstorm-strategy-benchmarks.md
  • todos/026-stream-parse-pi-json-events.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (3)
**/*.rs

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.rs: Run cargo test --workspace to run all tests
Use cargo build --workspace to build all crates

Files:

  • crates/refinery_cli/src/commands/mod.rs
  • crates/tundish_providers/src/process.rs
  • crates/refinery_cli/src/main.rs
  • crates/refinery_cli/src/commands/review_brainstorm_panels.rs
docs/plans/**

📄 CodeRabbit inference engine (CLAUDE.md)

docs/plans/**: Update plan headers with enhancement dates using format 'Enhanced: YYYY-MM-DD (via /deepen-plan)'
Update plan headers with review dates using format 'Reviewed: YYYY-MM-DD (via /$SKILL / $COMMAND)'
Update plan headers with completion dates using format 'Completed: YYYY-MM-DD'
Add addendums to plans using format 'Addendum: YYYY-MM-DD — description of what was added and why'
Create a dedicated plan when picking up a milestone from a roadmap or general plan if the milestone does not have one

Files:

  • docs/plans/2026-05-23-001-research-brainstorm-strategy-benchmarks-plan.md
docs/HANDOFF.md

📄 CodeRabbit inference engine (CLAUDE.md)

Update docs/HANDOFF.md before compaction or at session end with project state, architecture gotchas, open work, and review process

Files:

  • docs/HANDOFF.md
🔇 Additional comments (9)
docs/brainstorms/2026-05-30-brainstorm-l2-iteration-strategy-benchmark.md (1)

1-189: LGTM!

docs/brainstorms/2026-06-01-brainstorm-l2-panel-review.md (1)

1-137: LGTM!

docs/plans/2026-05-23-001-research-brainstorm-strategy-benchmarks-plan.md (1)

14-16: LGTM!

Also applies to: 149-176, 179-179, 191-193

todos/013-brainstorm-strategy-benchmarks.md (1)

7-7: LGTM!

Also applies to: 20-23, 101-106

crates/tundish_providers/src/process.rs (1)

13-18: LGTM!

todos/026-stream-parse-pi-json-events.md (1)

1-33: LGTM!

crates/refinery_cli/src/commands/review_brainstorm_panels.rs (1)

734-789: LGTM!

crates/refinery_cli/src/main.rs (1)

43-45: Please run the workspace-wide Rust checks before merging.

This changes the top-level CLI surface, but the PR description only lists refinery_cli-scoped verification. Please also run cargo build --workspace and cargo test --workspace here. As per coding guidelines, "**/*.rs: Run cargo test --workspace to run all tests" and "Use cargo build --workspace to build all crates`".

Also applies to: 79-79

crates/refinery_cli/src/commands/mod.rs (1)

4-4: LGTM!

Comment thread crates/refinery_cli/src/commands/review_brainstorm_panels.rs
Comment thread crates/refinery_cli/src/commands/review_brainstorm_panels.rs Outdated
Comment thread docs/HANDOFF.md Outdated
@El-Fitz

El-Fitz commented Jun 2, 2026

Copy link
Copy Markdown
Contributor Author

Addressed review feedback in 1ec520a. Verification after fixes: cargo fmt --all, cargo test -p refinery_cli review_brainstorm_panels, cargo clippy -p refinery_cli --all-targets -- -D warnings, cargo build --workspace, and cargo test --workspace.

@El-Fitz

El-Fitz commented Jun 2, 2026

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jun 2, 2026

Copy link
Copy Markdown
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@El-Fitz El-Fitz dismissed coderabbitai[bot]’s stale review June 2, 2026 06:45

All CodeRabbit findings addressed in 1ec520a; CodeRabbit acknowledged each resolved inline comment.

@El-Fitz El-Fitz added this pull request to the merge queue Jun 3, 2026
Merged via the queue into main with commit fbc9923 Jun 3, 2026
5 checks passed
@El-Fitz El-Fitz deleted the feat/brainstorm-panel-review-pack branch June 3, 2026 13:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant