Engineering Judgment Architect for AI Coding Agents

=== ENGINEERING JUDGMENT REPORT ===

Original request
Create an engineering-minded implementation plan and Cursor prompt for adding discount logic to a checkout page.

Interpreted engineering goal
Add discount behavior to checkout in a way that preserves pricing correctness, payment integrity, maintainability, and testability.

Task type
Feature implementation, payment-adjacent business logic

Project maturity
Unknown. Because checkout and payment behavior are involved, treat this as production-sensitive unless confirmed otherwise.

Confirmed facts

• The feature involves a checkout page.
• Discount logic affects pricing.
• The agent must decide where the logic belongs.
• The agent must avoid overengineering and UI-only business rules.
• Payment behavior must be protected.
• Tests are expected.

Assumptions

• The app has a frontend checkout page.
• The app has backend order or payment logic.
• The backend should be authoritative for final totals.
• Discount rules may include valid, invalid, expired, or missing discount codes.

Unknowns

• current pricing architecture
• payment provider integration
• existing order creation flow
• existing validation rules
• database schema
• whether discounts already exist
• test framework

Proper layer decision
Authoritative discount validation and calculation should live in the backend domain/service layer or existing pricing/order service. The UI layer may collect a discount code and display the calculated result, but it should not be the only source of pricing truth.

Why this layer owns it
Discounts affect business rules, payment totals, and order integrity. These rules must remain consistent even if the UI is bypassed, refreshed, or changed.

Why not UI only
UI-only discount logic can be bypassed, duplicated, or become inconsistent with backend payment/order creation.

Complexity budget
7/10. Checkout pricing is high-risk, but a full promotion engine may be unnecessary.

Overengineering risks

• building a generic promotion engine for one simple discount rule
• introducing a new pricing framework without evidence
• changing database schema before confirming requirements
• refactoring the entire checkout flow while adding one feature

Underengineering risks

• hardcoding discount math in the checkout component
• trusting frontend-calculated totals
• duplicating discount rules in frontend and backend
• failing to test invalid or expired discounts
• breaking payment amount integrity

Recommended approach
Implement the smallest backend-authoritative discount calculation that satisfies the current requirement. Keep UI changes focused on input, display, loading, error, and success states. Add tests around pricing rules and payment amount consistency.

Alternatives considered

1. UI-only discount calculation
   Rejected because it is unsafe and can create inconsistent totals.

2. Full promotion engine
   Rejected unless the product already needs multiple discount types, campaigns, stacking rules, user targeting, or admin management.

3. Backend pricing/domain service
   Recommended because it is authoritative, testable, and proportionate.

Implementation plan

1. Inspect checkout UI, order creation, pricing calculation, payment integration, and existing validation.
2. Identify the authoritative pricing layer.
3. Add discount validation and calculation in the backend/domain/service layer.
4. Expose discount result to UI through existing API or state pattern.
5. Preserve payment amount integrity.
6. Add UI states for valid, invalid, expired, and missing discount code.
7. Add tests.
8. Avoid unrelated checkout refactors.

Testing strategy

• valid discount applies correctly
• invalid discount is rejected
• expired discount is rejected
• discount cannot make total negative
• backend total matches payment amount
• UI displays backend result correctly
• existing checkout flow still works
• payment behavior remains unchanged

Refactor triggers
Refactor only if pricing logic is already duplicated, checkout totals are calculated in multiple places, or tests cannot be written without extracting pricing logic.

Framework-change assessment
No framework change is justified for this feature.

AI coding agent prompt
Inspect the checkout page, order creation flow, pricing calculation, discount-related code, payment integration, and tests before editing. Decide the proper layer for discount logic before implementation. Do not implement discount business rules only in the UI. The UI may collect and display the discount, but the backend pricing/domain/service layer must remain authoritative for final totals. Preserve existing payment behavior and do not change database schema unless explicitly required and explained first. Avoid building a full promotion engine unless existing requirements prove it is needed. Implement the smallest safe discount flow. Add tests for valid, invalid, expired, no-discount, and total-integrity cases. Avoid unrelated checkout refactors. Return the layer decision, rationale, files inspected, files changed, tests added or run, and remaining risks.

Verification checklist

• discount logic is not UI-only
• payment totals remain authoritative
• valid discounts work
• invalid discounts fail safely
• expired discounts fail safely
• tests cover pricing behavior
• checkout flow still works
• no broad rewrite was performed

Risks and follow-up triggers
If multiple discount types, stacking rules, admin campaigns, or user targeting are needed later, revisit whether a fuller promotion module is justified.