sion rounds.
- Ensures strict adherence to consolidation windows and billing triggers.
*/
class RevisionEngine {
private maxIncludedRounds: number;
private consolidationWindowDays: number;
private hourlyRate: number;
constructor(config: { maxRounds: number; windowDays: number; rate: number }) {
this.maxIncludedRounds = config.maxRounds;
this.consolidationWindowDays = config.windowDays;
this.hourlyRate = config.rate;
}
/**
- Initiates a new round upon milestone delivery.
- Sets the consolidation deadline based on business days.
*/
initiateRound(roundId: number, deliveryDate: Date): RevisionRound {
const deadline = this.calculateBusinessDays(deliveryDate, this.consolidationWindowDays);
return {
roundId,
status: 'PENDING',
deliveryDate,
consolidationDeadline: deadline,
feedbackPayload: [],
isConsolidated: false,
};
}
/**
- Submits feedback for a specific round.
- Validates consolidation and deadline constraints.
*/
submitFeedback(round: RevisionRound, items: FeedbackItem[]): void {
if (round.status !== 'PENDING') {
throw new Error(
Round ${round.roundId} is not open for feedback.);
}
if (new Date() > round.consolidationDeadline) {
throw new Error(`Consolidation window expired. Late feedback triggers billable round.`);
}
// Enforce consolidation: Reject partial updates
if (round.feedbackPayload.length > 0) {
throw new Error('Feedback must be submitted as a single consolidated list.');
}
round.feedbackPayload = items;
round.isConsolidated = true;
round.status = 'SUBMITTED';
}
/**
- Closes a round and determines billing status.
- Rounds beyond the included count are flagged as billable.
*/
closeRound(round: RevisionRound): { status: string; isBillable: boolean } {
round.status = 'APPROVED';
const isBillable = round.roundId > this.maxIncludedRounds;
return {
status: 'CLOSED',
isBillable,
};
}
private calculateBusinessDays(startDate: Date, days: number): Date {
// Implementation to add business days, skipping weekends
// ...
return new Date(); // Placeholder
}
}
#### Architecture Decisions and Rationale
1. **Immutable Round State:** Once a round is submitted, the `feedbackPayload` cannot be appended. This forces the client to perform internal consolidation before submission. If a client attempts to add feedback after submission, the engine rejects it, requiring a new round. This eliminates the "one more thing" pattern that extends timelines.
2. **Consolidation Window Enforcement:** The `consolidationDeadline` is calculated based on business days. This creates urgency for the client to gather stakeholder input while the delivery context is fresh. Without this window, projects often stall as clients delay feedback, leaving the project in a half-open state on your calendar.
3. **Explicit Billing Triggers:** The `closeRound` method automatically flags rounds exceeding `maxIncludedRounds` as billable. This removes ambiguity. The transition from included to billable is deterministic, not negotiable.
4. **Defect vs. Revision Categorization:** The `FeedbackItem` interface includes a `category` field. This is critical for distinguishing between genuine defects (covered under warranty) and scope changes (covered under revisions). This separation prevents clients from masking scope creep as bug reports.
### Pitfall Guide
Even with a robust protocol, implementation failures occur. The following pitfalls represent common deviations observed in production environments.
1. **The Drip Trap**
* *Explanation:* Allowing clients to send feedback via email or chat as they think of it, rather than requiring a consolidated document.
* *Impact:* Creates continuous context switching, extends project duration, and makes it impossible to track which round a change belongs to.
* *Fix:* Enforce a single submission channel. Reject partial feedback with a polite redirect: "Please consolidate all changes into the revision form so we can address them efficiently in Round 2."
2. **The Moving Goalpost**
* *Explanation:* Failing to define what constitutes a "round." Clients may interpret a round as a single change request rather than a batch.
* *Impact:* A client can exhaust included rounds by submitting one change at a time, claiming they used "one round" per email.
* *Fix:* Explicitly define a round as "one consolidated list of changes." The contract and protocol must align on this definition.
3. **The Post-Mortem Scope**
* *Explanation:* A client requests changes after the final delivery and final payment, assuming revisions are still available.
* *Impact:* Unbilled work on a closed project. Disputes arise when the developer refuses to continue without a new agreement.
* *Fix:* Include a clause stating that any request after final delivery constitutes a new Statement of Work (SOW). The `RevisionEngine` should lock rounds upon final approval.
4. **The Defect Confusion**
* *Explanation:* Treating bugs and missing requirements as revision items, consuming the client's included rounds.
* *Impact:* Client frustration and erosion of trust. The client feels they are paying for your mistakes.
* *Fix:* Separate defect tracking from revision rounds. Defects should be resolved immediately without consuming revision count. Use the `category: 'DEFECT'` flag to route these items correctly.
5. **The Soft Sell**
* *Explanation:* Presenting the revision limit as a restriction or penalty, causing client anxiety.
* *Impact:* Client pushback or refusal to sign. The client perceives the clause as a lack of confidence or willingness to help.
* *Fix:* Frame the protocol as a quality assurance measure. "We use structured rounds to ensure your feedback gets consolidated attention and faster turnaround, rather than getting lost in a drip of small requests."
6. **The Windowless Feedback**
* *Explanation:* Omitting the consolidation window deadline.
* *Impact:* Clients submit feedback weeks or months later, reopening context and delaying project closure. The project lingers indefinitely.
* *Fix:* Always include a business-day window (e.g., 5 days). This protects both parties by ensuring feedback is timely and contextually relevant.
7. **The Tiering Timing Error**
* *Explanation:* Offering additional rounds at a discount only after the final delivery, when the client realizes they need more changes.
* *Impact:* Loss of leverage. The client may refuse to pay, or the discount signals that the original scope was insufficient.
* *Fix:* For fixed-price projects, offer tiered options (e.g., Round 3 at 50% rate) only if contracted *before* final delivery. Once delivered, the project phase changes, and new work requires a new SOW.
### Production Bundle
#### Action Checklist
- [ ] **Define Parameters:** Set `X` (max rounds) and `Y` (consolidation window) based on project size. Standard: 2 rounds, 5 business days for projects under $5k.
- [ ] **Draft Clause:** Insert the revision protocol clause into the master services agreement or statement of work. Ensure it defines "round," "consolidation," and "billing triggers."
- [ ] **Configure Tracking:** Set up a project management tool or spreadsheet to track round status, deadlines, and feedback payloads. Use the `RevisionRound` structure as a template.
- [ ] **Prepare Framing Script:** Develop a client-facing explanation that positions the protocol as a process benefit. Practice the response to pushback regarding additional rounds.
- [ ] **Set Billing Triggers:** Configure your invoicing system to automatically flag rounds exceeding `X` as billable at the standard hourly rate.
- [ ] **Review Fixed-Price Variants:** For larger contracts, prepare a tiered revision option to offer upfront, ensuring the discount window closes before final delivery.
- [ ] **Audit Defect Policy:** Establish a clear definition of "defect" vs. "revision" to prevent scope creep disguised as bug fixes.
#### Decision Matrix
| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **Small Project (<$5k)** | 2 Rounds, 5-Day Window | Balances client needs with developer efficiency. Most projects resolve within two cycles. | Neutral. Prevents margin erosion. |
| **Large Fixed-Price** | Tiered Rounds (3 Included, 4th Billable) | Provides buffer for complexity while capping risk. Tiering manages expectations. | Protected. Excess rounds billed at premium. |
| **High-Uncertainty Scope** | Hourly with Round Caps | Scope ambiguity makes fixed rounds risky. Hourly billing with round structure controls feedback volume. | Stable. Revenue aligns with effort. |
| **Retainer Engagement** | Monthly Round Allocation | Revisions are part of ongoing maintenance. Allocate rounds monthly to prevent backlog accumulation. | Predictable. Retainer covers defined volume. |
#### Configuration Template
Copy and adapt the following clause for your contracts. This text is rewritten to enforce the protocol while maintaining professional tone.
> **Revision Cycle Terms.**
>
> 1. **Included Cycles.** The project includes [X] revision cycles per milestone delivery. A "cycle" is defined as one consolidated feedback document submitted within [Y] business days of the delivery date.
> 2. **Consolidation Requirement.** Feedback must be aggregated into a single submission per cycle. Partial or incremental feedback requests will not be processed until consolidated or will trigger a new cycle.
> 3. **Excess Cycles.** Any revision cycle beyond the included count is billable at [Hourly Rate] per hour. Billing for excess cycles commences upon submission of the feedback document for that cycle.
> 4. **Final Delivery.** Final payment is due upon completion of the final included cycle. Requests submitted after final delivery constitute a new scope of work and require a separate agreement.
> 5. **Defects.** Genuine defects in the delivered work are resolved outside of revision cycles at no additional cost. Defects are defined as functionality that does not match the agreed specifications.
#### Quick Start Guide
1. **Assess Project Size:** Determine if the project falls under the standard threshold (e.g., <$5k). If so, set parameters to 2 rounds and 5 business days.
2. **Insert Clause:** Add the Configuration Template to your contract. Replace `[X]`, `[Y]`, and `[Hourly Rate]` with your values.
3. **Communicate Process:** During the kickoff meeting, explain the revision protocol. Use the framing script: "We structure feedback in rounds to ensure your input gets focused attention and faster implementation."
4. **Initialize Tracking:** Create a revision tracker for the project. Set the first round deadline based on the delivery date plus [Y] business days.
5. **Enforce Discipline:** When feedback arrives, verify it meets consolidation and deadline criteria. If it does, process it. If not, politely redirect the client to the protocol requirements.
