@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/receiving-code-review/SKILL.md

@@ -1,81 +0,0 @@
----
-name: receiving-code-review
-description: "Use when responding to code review feedback, incorporating reviewer suggestions, handling disagreements constructively, iterating through review cycles, or learning from repeated feedback patterns."
----
-# Receiving Code Review
-
-## Purpose
-
-Transform code review from a defensive ordeal into a high-leverage learning opportunity. This skill provides a systematic approach to processing reviewer feedback, responding constructively, incorporating changes efficiently, and extracting lasting lessons from repeated patterns — reducing review cycles, strengthening team relationships, and accelerating personal growth as an engineer.
-
-## When to Use
-
-- Responding to reviewer comments on a pull request
-- Deciding how to handle feedback you disagree with
-- Iterating through multiple review rounds efficiently
-- Learning from repeated reviewer feedback to avoid future issues
-- Managing conflicting feedback from multiple reviewers
-- Determining when to push back and when to accept suggestions
-
-## Instructions
-
-1. **Read all feedback before responding** — read every comment across the entire PR before writing any response, because reacting comment-by-comment leads to contradictory responses and misses cross-cutting themes that reviewers are collectively surfacing.
-
-2. **Respond to every comment** — acknowledge every piece of feedback with either a resolution, a question, or a brief "Done", because unacknowledged comments signal disrespect for the reviewer's time and leave ambiguity about whether the feedback was seen or ignored.
-
-3. **Distinguish blocking from non-blocking feedback** — identify which comments are must-fix (correctness, security, breaking changes) versus nice-to-have (style, naming, minor refactors), because treating all feedback as equally urgent wastes time on low-impact changes while potentially delaying critical fixes.
-
-4. **Ask clarifying questions when feedback is ambiguous** — when a comment isn't clear, ask a specific follow-up question rather than guessing the reviewer's intent, because misinterpreting feedback leads to wasted implementation effort and additional review rounds.
-
-5. **Make requested changes promptly** — address blocking feedback as quickly as possible after the review is complete (not piecemeal during the review), because fast turnaround keeps the reviewer's context fresh and prevents the PR from going stale in the queue.
-
-6. **Explain trade-offs when pushing back** — when you disagree with feedback, present your reasoning with specific trade-offs rather than simply declining, because reviewers are more receptive to well-reasoned alternatives than unexplained resistance, and the discussion often surfaces a better solution than either original proposal.
-
-7. **Use suggestion commits for small fixes** — adopt GitHub's suggestion feature or create small fixup commits for trivial changes (typos, naming, formatting), because atomic change tracking makes it easy for reviewers to verify their feedback was addressed without re-reviewing the entire diff.
-
-8. **Batch responses rather than replying piecemeal** — collect all your responses and push all changes together in a single update, because piecemeal updates trigger multiple notification rounds that fragment the reviewer's attention and make it harder to see the complete resolution.
-
-9. **Update PR description when scope changes** — modify the PR description to reflect any scope changes, new limitations, or additional context that emerged during review, because the description is the permanent record of the change and future readers will rely on it, not the review comments.
-
-10. **Resolve conversations only when addressed** — mark a comment as resolved only after the feedback has been genuinely addressed (code changed, question answered, or explicit agreement to defer), because prematurely resolving conversations hides unfinished work from reviewers.
-
-11. **Re-request review after addressing all comments** — explicitly re-request review with a summary of what changed rather than waiting for reviewers to notice your updates, because reviewers manage multiple PRs and a clear "ready for re-review" signal moves yours back to the top of their queue.
-
-12. **Learn from repeated feedback patterns** — track feedback themes you receive across multiple reviews (missing tests, unclear naming, insufficient error handling) and proactively address these in future PRs, because systematic pattern recognition converts reactive feedback into proactive quality habits.
-
-13. **Handle conflicting reviewer opinions** — when two reviewers disagree, surface the conflict explicitly and propose a resolution rather than picking one reviewer's side silently, because hidden conflicts lead to flip-flopping changes across review rounds and erode trust.
-
-14. **Manage review cycles without scope creep** — resist the temptation to expand scope based on review feedback and instead create follow-up issues for good ideas that are out of scope, because unbounded scope growth turns focused PRs into sprawling changes that are harder to review, test, and revert.
-
-## Output Format
-
-When responding to review feedback, provide:
-
-1. **Feedback summary** — categorized list of all reviewer comments (blocking/non-blocking/questions)
-2. **Response plan** — how each comment will be addressed (fix, discuss, defer)
-3. **Changes made** — summary of code changes in response to feedback
-4. **Open questions** — any feedback that needs further discussion
-5. **Re-review request** — clear signal that changes are ready for re-review with context
-
-## References
-
-| File | Purpose |
-|------|---------|
-| `references/feedback-response-patterns.md` | Templates for responding to different types of review feedback constructively |
-| `references/disagreement-resolution.md` | Strategies for handling pushback and resolving conflicts during code review |
-| `references/review-iteration.md` | Techniques for efficiently iterating through multiple review cycles |
-
-## Codex Platform Notes
-
-- Codex supports native subagents via `.codex/agents/*.toml` files with `name`, `description`, and `developer_instructions`.
-- Each subagent TOML can specify `model` and `model_reasoning_effort` to optimize cost per task difficulty:
-  - Light tasks (exploration, docs): `model = "gpt-5.3-codex-spark"`, `model_reasoning_effort = "medium"`
-  - Heavy tasks (security audit, orchestration): `model = "gpt-5.4"`, `model_reasoning_effort = "high"`
-  - Standard tasks (implementation): inherit parent model (omit `model` field).
-- Built-in agents: `default`, `worker`, `explorer`. Custom agents extend these via TOML definitions.
-- Codex operates under network restrictions — skills should not assume outbound HTTP access.
-- Use `$ARGUMENTS` to access user-provided arguments when the skill is invoked.
-- All skill guidance executes within the sandbox; file I/O is confined to the workspace.
-- Skills are installed at `.agents/skills/<skill-id>/SKILL.md`. Workflow skills can also be compiled to `.agents/skills/<workflow-id>/SKILL.md` as `generatedSkills`.
-- Codex supports three autonomy levels: `suggest`, `auto-edit`, `full-auto`.
-- MCP skill tools are available when the Cubis Foundry MCP server is connected.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/receiving-code-review/evals/assertions.md

@@ -1,35 +0,0 @@
-# Receiving Code Review — Eval Assertions
-
-## Eval 1: Categorizing and responding to mixed feedback
-
-### Assertion 1: Race condition as blocking
-The skill must identify the race condition comment as the highest priority. Race conditions cause data corruption and are correctness bugs — they must be fixed before merge.
-
-### Assertion 2: Variable naming as non-blocking
-Naming feedback is a style improvement that doesn't affect behavior. Categorizing it correctly prevents over-prioritizing cosmetic changes.
-
-### Assertion 3: Acknowledge positive feedback
-Responding to praise builds reviewer rapport and signals that all feedback is valued, not just criticism.
-
-### Assertion 4: Integration tests for cache miss
-When a reviewer asks "why no tests?", the correct response is usually to add the tests. The skill should recommend writing them.
-
-### Assertion 5: Technical approach for race condition
-The response should include a specific fix strategy (locking, atomic operations, or compare-and-swap), not just acknowledge the problem.
-
-## Eval 2: Handling conflicting reviewer opinions
-
-### Assertion 1: Surface the conflict explicitly
-Silently choosing one reviewer's approach leads to confusion. The skill must recommend making the disagreement visible.
-
-### Assertion 2: Trade-off analysis
-Both approaches have valid merits. The skill must analyze testability vs simplicity trade-offs with specific reasoning.
-
-### Assertion 3: Resolution mechanism
-Async comment threads can spiral. The skill should suggest a synchronous discussion for faster resolution.
-
-### Assertion 4: YAGNI consideration
-Bob's concern about unnecessary abstraction for a single implementation is a valid YAGNI argument that should be weighed.
-
-### Assertion 5: Document the decision
-Regardless of outcome, the reasoning should be captured so future developers understand the choice.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/receiving-code-review/evals/evals.json

@@ -1,24 +0,0 @@
-{
-  "evals": [
-    {
-      "prompt": "I received code review feedback on my PR that adds a caching layer to our API. The reviewer left these comments: (1) 'This cache invalidation logic has a race condition when two concurrent writes happen.' (2) 'Consider using Redis TTL instead of manual expiration tracking.' (3) 'The variable name `d` should be more descriptive.' (4) 'Why didn't you add integration tests for the cache miss path?' (5) 'Nice use of the decorator pattern here.' Help me categorize this feedback and plan my responses.",
-      "assertions": [
-        "categorizes the race condition comment as blocking/critical since it affects correctness",
-        "categorizes the variable naming comment as non-blocking/style since it does not affect behavior",
-        "recommends acknowledging the positive feedback about the decorator pattern",
-        "suggests writing integration tests for the cache miss path as the reviewer requested",
-        "provides a concrete response plan for addressing the race condition with specific technical approach"
-      ]
-    },
-    {
-      "prompt": "Two reviewers on my PR disagree. Alice says I should use an interface-based approach for the payment processor abstraction because it enables easier testing. Bob says I should use a concrete class with dependency injection because the interface adds unnecessary indirection for a single implementation. Both are senior engineers. How should I handle this?",
-      "assertions": [
-        "recommends surfacing the conflict explicitly rather than silently choosing one side",
-        "analyzes the trade-offs of both approaches with specific technical reasoning",
-        "suggests a resolution mechanism such as a brief discussion thread or synchronous conversation",
-        "considers the YAGNI principle regarding the single implementation concern",
-        "recommends documenting the decision rationale regardless of which approach is chosen"
-      ]
-    }
-  ]
-}

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/receiving-code-review/examples/01-responding-to-feedback.md

@@ -1,56 +0,0 @@
-# Example: Responding to Review Feedback on a Feature PR
-
-## Context
-
-A developer submitted a PR adding a user notification preferences API. The reviewer left 6 comments covering a range of feedback types. The developer needs to categorize, respond to, and address all feedback.
-
-## Reviewer Comments
-
-1. "The `updatePreferences` endpoint doesn't validate that the notification channels are valid enum values. A user could POST `channel: 'pigeon'` and it would be stored."
-2. "This SQL query in `getPreferences` is doing a SELECT * — we should only select the columns we need."
-3. "The error handling in the batch update doesn't roll back partial changes if one preference fails. This could leave the user in an inconsistent state."
-4. "Nit: `prefs` is used in some places and `preferences` in others. Pick one and be consistent."
-5. "Should we add rate limiting to the preferences endpoint? Users could hammer it."
-6. "The test coverage for the happy path is solid."
-
-## Skill Response
-
-### Feedback Categorization
-
-| # | Comment | Type | Priority | Action |
-|---|---------|------|----------|--------|
-| 1 | Missing enum validation | Blocking | High | Fix: add Zod enum validation |
-| 2 | SELECT * usage | Non-blocking | Medium | Fix: specify column list |
-| 3 | No rollback on partial failure | Blocking | High | Fix: wrap in transaction |
-| 4 | Inconsistent naming | Non-blocking | Low | Fix: standardize to `preferences` |
-| 5 | Rate limiting question | Discussion | Medium | Defer: create follow-up issue |
-| 6 | Positive feedback on tests | Acknowledgment | — | Thank reviewer |
-
-### Response Plan
-
-**Blocking fixes (do first):**
-- Comment 1: Add Zod schema with `z.enum(['email', 'sms', 'push', 'in-app'])` validation to the request body. Add test for invalid channel rejection.
-- Comment 3: Wrap the batch update in a database transaction with rollback on any individual failure. Add test for partial failure scenario.
-
-**Non-blocking fixes (batch together):**
-- Comment 2: Replace `SELECT *` with explicit column list. Minor performance improvement.
-- Comment 4: Rename all `prefs` occurrences to `preferences` for consistency.
-
-**Discussion items:**
-- Comment 5: Rate limiting is a good idea but out of scope for this PR. Create issue #247 to track it. Respond: "Great point — I've created #247 to add rate limiting. I'd rather not expand this PR's scope but agree it should be done soon."
-
-**Acknowledgment:**
-- Comment 6: "Thanks! I spent extra time on the happy path tests to make sure the preference merge logic was well-covered."
-
-### Re-Review Request
-
-After pushing all changes:
-
-> All feedback addressed in fixup commits:
-> - `fix: add enum validation for notification channels` (comment 1)
-> - `fix: wrap batch update in transaction` (comment 3)
-> - `fix: select specific columns in getPreferences` (comment 2)
-> - `fix: standardize naming to preferences` (comment 4)
->
-> Created follow-up issue #247 for rate limiting (comment 5).
-> Ready for re-review — the two blocking issues are fixed with tests.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/receiving-code-review/examples/02-handling-disagreement.md

@@ -1,67 +0,0 @@
-# Example: Handling Disagreement During Code Review
-
-## Context
-
-A developer submitted a PR refactoring the authentication middleware to use a chain-of-responsibility pattern. The reviewer suggests a different approach. The developer disagrees but needs to handle it constructively.
-
-## Reviewer Comment
-
-> "I think this chain-of-responsibility pattern is over-engineered for our use case. We only have 3 auth strategies (API key, JWT, session cookie) and they're unlikely to change often. A simple if/else chain would be more readable and easier to debug. The pattern adds 4 new classes and an interface for something that's currently 30 lines of straightforward code."
-
-## Developer's Assessment
-
-The developer chose the pattern because:
-- The auth strategies have different error handling needs
-- Each strategy needs independent testing
-- A new OAuth2 strategy is planned for Q2
-- The current if/else chain has grown hard to maintain
-
-But the reviewer's concerns are valid:
-- 4 new classes IS more code
-- The pattern does add indirection
-- The if/else chain works today
-
-## Skill Response
-
-### Step 1: Acknowledge the Valid Concern
-
-> You raise a fair point about the additional complexity — 4 new classes for 3 strategies is a legitimate concern. Let me share my reasoning and see if we can find the right balance.
-
-### Step 2: Present Trade-Off Analysis
-
-> **Why I chose this approach:**
-> 1. Each strategy needs different error semantics (API key returns 401 with `WWW-Authenticate`, JWT returns 401 with token expiry info, session returns 302 redirect). The if/else chain was mixing these concerns.
-> 2. We have a Q2 requirement for OAuth2 support (see JIRA-1234), which would make it 4 strategies.
-> 3. The current if/else chain had a bug last sprint (JIRA-1189) because the JWT branch was accidentally catching API key errors.
->
-> **Your concerns I agree with:**
-> - The 4-class structure is heavier than needed right now
-> - The interface adds a layer of indirection that makes debugging slightly harder
->
-> **Possible middle ground:** What if I simplified to a strategy map (dictionary of auth type → handler function) instead of the full chain-of-responsibility? That gives us:
-> - Independent handler functions (testable, isolated error handling) ✓
-> - No extra interface or abstract class ✓
-> - Easy to add OAuth2 in Q2 ✓
-> - Only ~50 lines vs the current 30 ✓
-
-### Step 3: Propose Resolution
-
-> I can refactor to the strategy map approach in this PR if you think that's the right balance. Or if you'd prefer to discuss synchronously, I'm free for 15 minutes this afternoon — sometimes these architectural decisions are faster to resolve in a quick call.
-
-### Step 4: Document Outcome
-
-After discussion, the reviewer agreed to the strategy map approach:
-
-> **Decision:** Use strategy map pattern (dictionary of auth type → handler function) instead of chain-of-responsibility or if/else chain.
->
-> **Rationale:** Provides independent testability and clean error handling per strategy without the overhead of the full GoF pattern. Scales to 4+ strategies (OAuth2 in Q2) without structural changes.
->
-> Updated PR description with this decision for future reference.
-
-### Key Principles Demonstrated
-
-1. **Acknowledged the valid part first** — "You raise a fair point" before defending
-2. **Used evidence, not opinion** — referenced JIRA tickets for the bug and Q2 requirement
-3. **Proposed a third option** — neither "my way" nor "your way" but a compromise
-4. **Offered synchronous discussion** — recognized that async threads can spiral
-5. **Documented the outcome** — captured the decision in the PR description

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/receiving-code-review/references/disagreement-resolution.md

@@ -1,122 +0,0 @@
-# Disagreement Resolution
-
-## Overview
-
-Disagreements during code review are normal and often productive. The goal is not to avoid disagreement but to resolve it efficiently while preserving relationships and making the best technical decision.
-
-## The Resolution Ladder
-
-Escalate through these levels only as needed:
-
-### Level 1: Async Discussion (Default)
-
-Reply to the comment with your reasoning. Most disagreements resolve here.
-
-**Template:**
-```
-"I see your point about [their concern]. I went with [your approach] because
-[specific reasoning]. [Alternative proposal if applicable]. What do you think?"
-```
-
-Time limit: 2 comment rounds. If unresolved, escalate.
-
-### Level 2: Synchronous Conversation
-
-Schedule a 15-minute call or huddle. Voice communication resolves misunderstandings faster than text.
-
-**Preparation:**
-- Write down your position and their position
-- Identify the specific technical trade-off
-- Come with a willingness to be wrong
-
-**After the call:** Summarize the decision in the PR comment thread so it's documented.
-
-### Level 3: Third-Party Opinion
-
-Bring in a third engineer for perspective. Choose someone with relevant domain expertise who isn't invested in either position.
-
-**When to use:**
-- Both positions are technically valid
-- The disagreement is about architecture, not style
-- The decision has long-term implications
-
-### Level 4: Team Lead/Tech Lead Decision
-
-If the team can't reach consensus, the tech lead makes the call.
-
-**When to use:**
-- Rarely. Most disagreements should resolve at Level 1-2.
-- Only for decisions with significant architectural impact
-- When the team is blocked and needs to move forward
-
-## Disagreement Categories
-
-### Style Disagreements
-
-Example: "Use `forEach` vs `for...of`"
-
-Resolution: Defer to the team's linter/style guide. If no guide exists, accept the reviewer's preference — style consistency matters more than personal preference.
-
-### Design Disagreements
-
-Example: "Use composition vs inheritance"
-
-Resolution: Discuss trade-offs. Consider YAGNI, testability, and the team's familiarity with the pattern. Document the decision.
-
-### Correctness Disagreements
-
-Example: "This will cause a race condition" / "No it won't"
-
-Resolution: Write a test that proves or disproves the claim. Code doesn't lie.
-
-### Scope Disagreements
-
-Example: "You should also handle the edge case where..." / "That's out of scope"
-
-Resolution: If the edge case is a real risk, create a follow-up issue. If it's speculative, explain why it's deferred.
-
-## Constructive Pushback Techniques
-
-### The Evidence-Based Pushback
-
-Present data, benchmarks, or references:
-```
-"I benchmarked both approaches. The current implementation handles
-10K requests/sec while the suggested approach peaks at 6K due to
-[specific bottleneck]. See benchmark results: [link]."
-```
-
-### The Trade-Off Acknowledgment
-
-Show you understand both sides:
-```
-"Your approach is cleaner. The trade-off is [specific cost]. Given our
-current requirements of [context], I think [your approach] is the better
-fit because [reasoning]. Happy to revisit if requirements change."
-```
-
-### The Compromise Proposal
-
-Offer a middle ground:
-```
-"What if we [alternative that addresses both concerns]? This gives us
-[benefit from their suggestion] while preserving [benefit from your approach]."
-```
-
-### The Deferral with Issue
-
-Accept the feedback but defer execution:
-```
-"That's a great improvement. It's a bigger change than I want to include
-in this PR though — I've created #N to track it. Can we merge this as-is
-and address it in the follow-up?"
-```
-
-## Red Lines: When NOT to Compromise
-
-- **Security vulnerabilities** — never compromise on known security issues
-- **Data integrity** — don't accept approaches that risk data loss or corruption
-- **Legal/compliance** — regulatory requirements are non-negotiable
-- **Team standards** — if the team decided on a standard, follow it
-
-For everything else, be flexible. The best code is shipped code, and perfect is the enemy of good.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/receiving-code-review/references/feedback-response-patterns.md

@@ -1,112 +0,0 @@
-# Feedback Response Patterns
-
-## Overview
-
-Different types of review feedback require different response strategies. Using the right pattern prevents misunderstandings, reduces review cycles, and maintains productive working relationships.
-
-## Response Templates by Feedback Type
-
-### Blocking Feedback (Must Fix)
-
-**Pattern:** Acknowledge → Fix → Verify
-
-```
-"Good catch — [restate the issue]. Fixed in [commit SHA]. I also added
-a test for [specific scenario] to prevent regression."
-```
-
-When to use: Bugs, security issues, correctness problems, missing error handling.
-
-Key principle: Never argue with blocking feedback about correctness. If the reviewer found a bug, fix it and thank them.
-
-### Suggestion Feedback (Could Improve)
-
-**Pattern:** Evaluate → Decide → Explain
-
-```
-"Thanks for the suggestion. I [adopted it / went with a variation / deferred it]
-because [specific reasoning]. [If deferred:] Created issue #N to track this."
-```
-
-When to use: Refactoring ideas, alternative approaches, performance optimizations.
-
-Key principle: You can decline suggestions with good reasoning. The key is explaining why, not just saying no.
-
-### Clarification Request
-
-**Pattern:** Answer → Show → Offer Context
-
-```
-"This [code/approach] works by [explanation]. I added an inline comment
-to make this clearer for future readers. See [file:line]."
-```
-
-When to use: "Why did you...?", "What does this do?", "Is this intentional?"
-
-Key principle: If a reviewer is confused, future readers will be too. Add a comment.
-
-### Nitpick/Style Feedback
-
-**Pattern:** Fix Quickly → Move On
-
-```
-"Done." or "Fixed — good eye."
-```
-
-When to use: Naming, formatting, import ordering, minor style issues.
-
-Key principle: Don't debate nitpicks. Fix them immediately and save energy for substantive discussions.
-
-### Positive Feedback
-
-**Pattern:** Thank → Elaborate (optional)
-
-```
-"Thanks! [Optional: brief context about why you chose this approach]."
-```
-
-When to use: Compliments, "nice!" comments, approval comments.
-
-Key principle: Acknowledge praise briefly. Don't over-explain.
-
-## Anti-Patterns to Avoid
-
-### The Defensive Response
-
-Bad: "It works fine on my machine." / "That's not what the ticket says."
-
-Why it fails: Signals that you're protecting ego rather than improving code. Reviewers stop giving honest feedback.
-
-Fix: Assume good intent. Restate the concern to confirm understanding before responding.
-
-### The Silent Fix
-
-Bad: Pushing changes without responding to comments.
-
-Why it fails: Reviewers can't tell if you understood their feedback or just made a random change. They'll re-review more skeptically.
-
-Fix: Always respond to the comment AND push the fix.
-
-### The Scope Expander
-
-Bad: "While I'm at it, I also refactored the entire module..."
-
-Why it fails: Expanding scope during review makes the PR harder to review and delays merge.
-
-Fix: Create follow-up issues for good ideas that are out of scope.
-
-### The Passive Resolver
-
-Bad: Marking comments as "resolved" without addressing them.
-
-Why it fails: Hides unfinished work and destroys reviewer trust.
-
-Fix: Only resolve after genuinely addressing the feedback.
-
-## Tone Guidelines
-
-- **Use "we" language** — "We should probably add a test" not "You're wrong"
-- **Assume good intent** — reviewers are trying to improve the code, not attack you
-- **Be specific** — "Fixed in abc123" not "Fixed"
-- **Stay professional** — avoid sarcasm, passive aggression, or dismissiveness
-- **Separate ego from code** — the review is about the code, not about you

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/receiving-code-review/references/review-iteration.md

@@ -1,139 +0,0 @@
-# Review Iteration
-
-## Overview
-
-Efficient review iteration minimizes the number of round trips between author and reviewer while ensuring all feedback is properly addressed. The goal is to merge a high-quality change in 1-2 review cycles rather than 4-5.
-
-## The Iteration Cycle
-
-```
-Review received
-  → Read ALL comments (don't react yet)
-  → Categorize: blocking / non-blocking / questions / praise
-  → Address all blocking items first
-  → Batch non-blocking fixes together
-  → Respond to every comment
-  → Push all changes in one update
-  → Re-request review with summary
-```
-
-## Batching Strategy
-
-### Why Batch
-
-Piecemeal updates cause problems:
-- Each push triggers notifications, fragmenting reviewer attention
-- Partial fixes can break the build or tests
-- Reviewers can't tell if you're done or still making changes
-- Comment threads become interleaved with code changes
-
-### How to Batch
-
-1. Read all feedback completely
-2. Plan all changes before making any
-3. Make all changes locally
-4. Run tests locally to verify nothing is broken
-5. Push everything in a single force-push or commit set
-6. Respond to all comments at once
-7. Re-request review as the final action
-
-### Exception: Quick Clarifications
-
-It's fine to respond to questions immediately (without code changes) to unblock the reviewer's understanding. Just don't push code until everything is ready.
-
-## Commit Strategies for Iterations
-
-### Fixup Commits (Recommended)
-
-Create separate commits for each piece of feedback:
-```
-fix: add enum validation for notification channels (review feedback)
-fix: wrap batch update in transaction (review feedback)
-fix: standardize naming to preferences (review feedback)
-```
-
-Benefits:
-- Reviewers can see exactly what changed per comment
-- Easy to verify each piece of feedback was addressed
-- Can be squashed before merge
-
-### Amend + Force Push
-
-Rewrite the original commits to incorporate feedback:
-
-Benefits:
-- Clean commit history
-- No "fix review feedback" commits in the log
-
-Drawbacks:
-- Reviewers must re-review the entire diff (can't see just the changes)
-- Use only when the reviewer requests it or when changes are extensive
-
-## Re-Review Request Template
-
-After addressing all feedback:
-
-```markdown
-## Changes in this iteration
-
-### Blocking fixes
-- [x] Added enum validation for channels (#comment-1) — abc1234
-- [x] Wrapped batch update in transaction (#comment-3) — def5678
-
-### Non-blocking fixes
-- [x] Replaced SELECT * with column list (#comment-2)
-- [x] Standardized naming to `preferences` (#comment-4)
-
-### Deferred
-- Rate limiting → tracked in #247 (#comment-5)
-
-### Tests
-- Added test for invalid channel rejection
-- Added test for partial batch failure rollback
-
-Ready for re-review. All blocking issues addressed with tests.
-```
-
-## Reducing Review Cycles
-
-### Cycle 1: First Review
-
-Goal: Address all blocking feedback. If possible, also fix non-blocking items.
-
-Typical outcome: 2-4 blocking items, 3-6 non-blocking items.
-
-### Cycle 2: Follow-Up Review
-
-Goal: Verify fixes and address any new issues that emerged from the changes.
-
-Typical outcome: 0-1 new blocking items, 1-2 clarifications.
-
-### Cycle 3+: Escalation Signal
-
-If you're in cycle 3 or beyond, something is wrong:
-- The PR scope is too large — consider splitting
-- There's a fundamental design disagreement — escalate to synchronous discussion
-- Requirements are unclear — pause the PR and clarify with stakeholders
-
-## Stale Review Recovery
-
-When a PR has been in review for more than 3 days:
-
-1. Rebase on the latest main branch
-2. Resolve any conflicts
-3. Re-run all tests
-4. Post a comment: "Rebased and resolved conflicts. All tests passing. Ready for re-review."
-5. If the reviewer is unresponsive, find an alternate reviewer
-
-## Metrics for Review Efficiency
-
-Track these to improve over time:
-
-| Metric | Target | How to Measure |
-|--------|--------|----------------|
-| Review cycles to merge | ≤ 2 | Count re-review requests per PR |
-| Time from review to response | < 4 hours | Timestamp between review and first response |
-| Blocking comments per PR | Trending down | Count blocking comments over time |
-| Repeated feedback themes | 0 repeats | Track if same feedback appears across PRs |
-
-If blocking comments per PR is trending down over months, you're learning from review feedback effectively.