docs(compensation): deduct bug hours from monthly retainer payout#5
Merged
Conversation
Contributor
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the 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 have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. WalkthroughSTANDARD_TERMS.md adds a Quality Adjustment clause for Retainer engagements that alters monthly payout based on bug-hours attribution and documents dispute/attribution via Wizard commands. Taxes and Finality of Payment clauses are renumbered; dispute timing and tax responsibilities remain unchanged. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
STANDARD_TERMS.md (1)
148-154:⚠️ Potential issue | 🔴 CriticalReconcile Wizard “dispute” with the 14-day “written dispute” waiver in Finality of Payment.
You introduce disputes at the attribution level via the Wizard commands, but the Finality clause waives “any right to dispute” if no “written dispute is raised within 14 days after receipt.” It’s unclear:
- whether a Wizard dispute counts as “written dispute” under this clause,
- whether disputing AQPT prevents the payment from becoming “full and final” for that month, and
- whether reductions are provisional/suspended until the dispute outcome.
This is the kind of drafting gap that can make a contractor’s dispute procedurally invalid.
Suggested clarifying language (example)
10. **Finality of Payment.** Any payment made by the Company for approved hours, completed projects, or accepted milestones constitutes full and final settlement of all claims relating to the Services covered by that payment. The Contractor - waives any right to dispute or make further claims in respect of that payment - if no written dispute is raised within 14 days after receipt. + waives any right to dispute or make further claims in respect of that payment + if no written dispute is raised within 14 days after receipt. A dispute raised + via the Wizard dispute command (as referenced in the Quality Adjustment clause) + within that 14-day window shall qualify as a written dispute for this purpose, + and any AQPT adjustment shall be applied in accordance with the outcome of that + dispute.</!-- review_comment_end -->
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@STANDARD_TERMS.md` around lines 148 - 154, The Finality of Payment clause conflicts with the Reconcile Wizard's attribution-level "dispute" flow: clarify whether a Wizard "dispute" counts as a "written dispute" for the 14-day waiver in the "Finality of Payment" section, whether raising a dispute via the Wizard suspends or preserves payment status (i.e., prevents the payment from becoming "full and final"), and whether any reductions (AQPT adjustments) are provisional pending dispute resolution; update STANDARD_TERMS.md by adding explicit language to the "Finality of Payment" paragraph that (1) defines "written dispute" to include disputes submitted through the Reconcile Wizard (or excludes them, if intended), (2) states whether a properly filed Wizard dispute tolls the 14-day period and suspends finality of payment for that invoice/month, and (3) explains treatment of provisional reductions/withholdings during dispute resolution (e.g., suspended, held, or final), referencing the terms "Reconcile Wizard", "dispute", "AQPT", and the "14 days" waiver so readers can locate and reconcile both mechanisms.
🧹 Nitpick comments (1)
STANDARD_TERMS.md (1)
139-146: Optional: make the dispute timeline/cut-off explicit (which bugs count “for that month”).
The clause says AQPT is for “that month” but doesn’t specify the attribution cut-off (e.g., bugs blamed during the month, or effective as of the invoice processing date). That can cause off-by-one-month payment adjustments.Consider adding one line like: “Only bug attributions effective in that calendar month are included (cut-off: end of month, per Wizard processing time).”
Also consider adding a small worked example (1–2 lines) to reduce ambiguity.
</!-- review_comment_end -->
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@STANDARD_TERMS.md` around lines 139 - 146, Clarify the monthly AQPT cutoff by adding a sentence after the AQPT calculation (referencing "Absolute Quality Percentile (AQPT)" and the "Wizard bug blame command"/"Wizard dispute command") that only bug attributions effective within the calendar month count toward that month's AQPT (cut-off: end of month as processed by Wizard), and add a one-line worked example using the payout formula `payout = (AQPT / 100) × base_salary` showing a sample AQPT and resulting payout to illustrate the timing (e.g., bugs blamed on or before 2026-04-30 affect April's AQPT; disputes resolved after cut-off apply to the next month).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@STANDARD_TERMS.md`:
- Around line 139-145: Add explicit boundaries and initial value for AQPT: state
that AQPT defaults to 100 at month start, specify how bug attributions map to
reductions (for example, define a per-attribution reduction unit or refer to a
severity-to-percentage table used by the Wizard bug blame command), and require
clamping after all adjustments so AQPT is constrained to the closed interval [0,
100]; update the payout formula paragraph (the line with "payout = (AQPT / 100)
× base_salary") to reference this clamping rule and the starting value and the
dispute process via the Wizard dispute command so negative or >100 payouts
cannot occur.
- Around line 139-145: The payout formula uses an undefined term `base_salary`,
causing ambiguity for Retainer engagements; update the text to explicitly define
the retainer calculation (e.g., replace `base_salary` with a defined term such
as `monthly_retainer = hourly_rate × approved_hours` or `approved_PR_hours ×
hourly_rate` and clarify whether caps/withholdings apply) and then use that term
in the formula (e.g., `payout = (AQPT / 100) × monthly_retainer`); ensure the
section referencing AQPT and the Wizard commands (Wizard bug blame and dispute)
remains unchanged but add a short parenthetical pointing to the “hourly rate in
the Special Terms” mapping so readers know which hourly_rate to use.
---
Outside diff comments:
In `@STANDARD_TERMS.md`:
- Around line 148-154: The Finality of Payment clause conflicts with the
Reconcile Wizard's attribution-level "dispute" flow: clarify whether a Wizard
"dispute" counts as a "written dispute" for the 14-day waiver in the "Finality
of Payment" section, whether raising a dispute via the Wizard suspends or
preserves payment status (i.e., prevents the payment from becoming "full and
final"), and whether any reductions (AQPT adjustments) are provisional pending
dispute resolution; update STANDARD_TERMS.md by adding explicit language to the
"Finality of Payment" paragraph that (1) defines "written dispute" to include
disputes submitted through the Reconcile Wizard (or excludes them, if intended),
(2) states whether a properly filed Wizard dispute tolls the 14-day period and
suspends finality of payment for that invoice/month, and (3) explains treatment
of provisional reductions/withholdings during dispute resolution (e.g.,
suspended, held, or final), referencing the terms "Reconcile Wizard", "dispute",
"AQPT", and the "14 days" waiver so readers can locate and reconcile both
mechanisms.
---
Nitpick comments:
In `@STANDARD_TERMS.md`:
- Around line 139-146: Clarify the monthly AQPT cutoff by adding a sentence
after the AQPT calculation (referencing "Absolute Quality Percentile (AQPT)" and
the "Wizard bug blame command"/"Wizard dispute command") that only bug
attributions effective within the calendar month count toward that month's AQPT
(cut-off: end of month as processed by Wizard), and add a one-line worked
example using the payout formula `payout = (AQPT / 100) × base_salary` showing a
sample AQPT and resulting payout to illustrate the timing (e.g., bugs blamed on
or before 2026-04-30 affect April's AQPT; disputes resolved after cut-off apply
to the next month).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Time Submission Status
You can submit time with the command. Example: See available commands to help comply with our Guidelines. |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
STANDARD_TERMS.md (2)
141-141:⚠️ Potential issue | 🟠 MajorDefine
base_salary(or replace with a defined retainer base).Line 141 uses
base_salary, but the document’s retainer model is hourly-rate × approved hours. This leaves payout basis ambiguous in disputes.Proposed wording
- `payout = (1 - bugHours / totalHours) × base_salary`. + `payout = (1 - bugHours / totalHours) × base_pay`, where `base_pay` + is the monthly Retainer amount otherwise payable under this section + (approved hours × hourly rate from the Special Terms, subject to any Monthly Hours Cap).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@STANDARD_TERMS.md` at line 141, The formula uses an undefined term base_salary in "payout = (1 - bugHours / totalHours) × base_salary"; either add a clear definition for base_salary in the terms (e.g., "base_salary: the agreed retainer amount, equal to hourly_rate × approved_hours") or replace base_salary in the formula with the existing retainer expression (hourly_rate × approved_hours) and update any related glossary/definitions to reference the chosen symbol (e.g., retainer_base or hourly_rate and approved_hours) so the payout basis is unambiguous.
140-142:⚠️ Potential issue | 🟠 MajorAdd bounds and zero-hours handling to prevent invalid payout math.
As written,
totalHourscan be0andbugHourscan exceedtotalHours, which makes the multiplier undefined or negative. Define constraints/clamping in the clause.Proposed wording
- adjusted based on bug hours attributed to the Contractor that month: - `payout = (1 - bugHours / totalHours) × base_salary`. + adjusted based on bug hours attributed to the Contractor that month. + For this calculation, `totalHours` is approved Retainer hours for that month and must be > 0; + `bugHours` is clamped to `[0, totalHours]`. + `payout = max(0, (1 - bugHours / totalHours)) × base_pay`.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@STANDARD_TERMS.md` around lines 140 - 142, Summary: The payout formula can produce undefined or negative values when totalHours is 0 or bugHours > totalHours; clamp and handle zero to keep the multiplier valid. Fix: update the clause around the payout = (1 - bugHours / totalHours) × base_salary language to (1) define that if totalHours = 0 the multiplier defaults to 1 (no reduction), (2) clamp bugHours to the range [0, totalHours] prior to computing bugHours/totalHours, and (3) state the resulting multiplier is bounded to [0,1] (i.e., payout = max(0, min(1, 1 - (clampedBugHours / totalHoursOrOne))) × base_salary) so the payout cannot be negative or undefined; refer to the terms bugHours, totalHours, payout, and base_salary when making these edits.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@STANDARD_TERMS.md`:
- Around line 143-145: The paragraph that currently states "counted in the month
the blame is recorded..." lacks a cutoff window; update the sentence after "Bug
attribution is made via the Wizard bug blame command; the Contractor may dispute
an attribution using the Wizard dispute command." to add a clear attribution
deadline — for example: "Attribution must be recorded by the end of the calendar
month in which the PR was merged plus 30 days; attributions submitted after this
window will not be counted." Edit the sentence in STANDARD_TERMS.md (the
paragraph containing "Bug attribution is made via the Wizard bug blame command"
and "Contractor may dispute an attribution using the Wizard dispute command") to
include this cutoff or replace 30 with your chosen N-day window.
---
Duplicate comments:
In `@STANDARD_TERMS.md`:
- Line 141: The formula uses an undefined term base_salary in "payout = (1 -
bugHours / totalHours) × base_salary"; either add a clear definition for
base_salary in the terms (e.g., "base_salary: the agreed retainer amount, equal
to hourly_rate × approved_hours") or replace base_salary in the formula with the
existing retainer expression (hourly_rate × approved_hours) and update any
related glossary/definitions to reference the chosen symbol (e.g., retainer_base
or hourly_rate and approved_hours) so the payout basis is unambiguous.
- Around line 140-142: Summary: The payout formula can produce undefined or
negative values when totalHours is 0 or bugHours > totalHours; clamp and handle
zero to keep the multiplier valid. Fix: update the clause around the payout = (1
- bugHours / totalHours) × base_salary language to (1) define that if totalHours
= 0 the multiplier defaults to 1 (no reduction), (2) clamp bugHours to the range
[0, totalHours] prior to computing bugHours/totalHours, and (3) state the
resulting multiplier is bounded to [0,1] (i.e., payout = max(0, min(1, 1 -
(clampedBugHours / totalHoursOrOne))) × base_salary) so the payout cannot be
negative or undefined; refer to the terms bugHours, totalHours, payout, and
base_salary when making these edits.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
zolotokrylin
changed the title
Member
Author
|
@coderabbitai review |
Contributor
✅ Actions performedReview triggered.
|
Member
Author
|
@holdex pr submit-time 2h 15m |
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (2)
STANDARD_TERMS.md (2)
150-156:⚠️ Potential issue | 🟠 MajorPrevent negative payout by defining a floor at 0.
If
bugHours > totalHours, payout becomes negative. Add an explicit floor rule (and whether any excess bug hours carry forward).Suggested edit
-`payout = (totalHours - bugHours) × hourlyRate` +`payout = max(0, totalHours - bugHours) × hourlyRate`+- If `bugHours` exceeds `totalHours` in a month, payout is floored at 0 for that month. +- Excess `bugHours` do not carry forward unless expressly agreed in writing.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@STANDARD_TERMS.md` around lines 150 - 156, Define that payout = max(0, (totalHours - bugHours) × hourlyRate) and explicitly state whether excess bugHours carry forward; update the definitions around `payout`, `totalHours`, `bugHours`, and `hourlyRate` to include a non-negative floor (i.e., payouts cannot be negative) and add a sentence clarifying the treatment of any excess `bugHours` (e.g., "excess bugHours do not carry forward" or "excess bugHours may be carried forward to the next month") so the contract behavior is unambiguous.
162-165:⚠️ Potential issue | 🟠 MajorAdd an attribution cutoff window.
Attribution timing is defined by record month, but there is no deadline for how late attribution can be raised. Add a cutoff (e.g., merge month + 30 days) to avoid open-ended retroactive deductions.
Suggested edit
Attributions are recorded in writing in the Holdex GitHub organisation. The Contractor may dispute any attribution in writing within 14 days of receiving notification of that attribution. A successfully disputed attribution is excluded from the bug hours calculation. +Attribution must be recorded no later than 30 days after the end of the +calendar month in which the relevant PR was merged; later attributions do not +count toward bug hours.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@STANDARD_TERMS.md` around lines 162 - 165, Update the "Attributions are recorded in writing in the Holdex GitHub organisation..." clause to add a firm cutoff for raising attributions: specify that attributions must be raised within a fixed window (for example, "within 30 days after the merge month") or similar (e.g., "merge month + 30 days"); ensure the sentence that begins "The Contractor may dispute any attribution in writing within 14 days..." is amended to reference this cutoff window (so late attributions beyond the cutoff are not accepted) and add a short clarifying sentence that attributions submitted after the cutoff will be ineligible for adjustments to the bug hours calculation.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@STANDARD_TERMS.md`:
- Around line 150-156: Define that payout = max(0, (totalHours - bugHours) ×
hourlyRate) and explicitly state whether excess bugHours carry forward; update
the definitions around `payout`, `totalHours`, `bugHours`, and `hourlyRate` to
include a non-negative floor (i.e., payouts cannot be negative) and add a
sentence clarifying the treatment of any excess `bugHours` (e.g., "excess
bugHours do not carry forward" or "excess bugHours may be carried forward to the
next month") so the contract behavior is unambiguous.
- Around line 162-165: Update the "Attributions are recorded in writing in the
Holdex GitHub organisation..." clause to add a firm cutoff for raising
attributions: specify that attributions must be raised within a fixed window
(for example, "within 30 days after the merge month") or similar (e.g., "merge
month + 30 days"); ensure the sentence that begins "The Contractor may dispute
any attribution in writing within 14 days..." is amended to reference this
cutoff window (so late attributions beyond the cutoff are not accepted) and add
a short clarifying sentence that attributions submitted after the cutoff will be
ineligible for adjustments to the bug hours calculation.
markholdex
approved these changes
May 4, 2026
|
@holdex pr submit-time 30m |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a Quality Adjustment clause to the Compensation section.
Payout =
(totalHours - bugHours) × hourlyRate. Bug hours are counted in the month the attribution is recorded, not when the original PR was merged. Attribution and dispute are handled in writing in the Holdex GitHub organisation.Summary by CodeRabbit