chore: update PR knowledge base

kb/.manifest.json

@@ -1 +1,18 @@
-{}
+{
+  "3063857930": "gotcha/renaming-a-function-parameter-breaks-backward-compatibility.md",
+  "3063857933": "gotcha/discount-amounts-are-not-validated-allowing-negative-totals.md",
+  "3064005728": "architecture_decision/question-about-whether-the-discount-api-should-support-both.md",
+  "3064070142": "architecture_decision/chose-to-maintain-backward-compatibility-through-an-alias.md",
+  "3064070321": "gotcha/the-function-now-prevents-negative-charges-and-taxes-by.md",
+  "3064070542": "domain_knowledge/discount-amount-represents-an-absolute-value-rather-than-a.md",
+  "4223263760": "code_pattern/adding-a-helper-function-for-discount-pricing-calculations.md",
+  "4223264048": "gotcha/renaming-a-function-parameter-breaks-backward-compatibility-2.md",
+  "4223530384": "domain_knowledge/tax-calculation-order-relative-to-discounts-is-a-business.md",
+  "4223569372": "domain_knowledge/the-pricing-rule-applies-absolute-discounts-before-tax.md",
+  "3066877543": "gotcha/unbounded-discount-rate-parameter-can-produce-negative.md",
+  "3066907088": "gotcha/unvalidated-discount-rate-values-can-produce-incorrect.md",
+  "3066907115": "architecture_decision/consolidating-percentage-and-absolute-discount-calculations.md",
+  "3066907152": "domain_knowledge/clarify-discount-rate-input-format-and-tax-application.md",
+  "4226957527": "code_pattern/the-discount-calculation-uses-a-multiplier-approach-1.md",
+  "4226957619": "gotcha/the-new-percentage-discount-function-lacks-input-validation.md"
+}

kb/INDEX.md

@@ -1 +1,29 @@
 # Knowledge Base Index
+
+## Architecture Decision (3)
+
+- [Chose to maintain backward compatibility through an alias while explicitly rejecting dual parameter usage to enforce a clear migration path.](architecture_decision/chose-to-maintain-backward-compatibility-through-an-alias.md)
+- [Consolidating percentage and absolute discount calculations through a single normalization path reduces maintenance burden and prevents pricing logic divergence.](architecture_decision/consolidating-percentage-and-absolute-discount-calculations.md)
+- [Question about whether the discount API should support both absolute amounts and percentages, and the naming implications of choosing one representation.](architecture_decision/question-about-whether-the-discount-api-should-support-both.md)
+
+## Code Pattern (2)
+
+- [Adding a helper function for discount pricing calculations that applies discounts before tax computation.](code_pattern/adding-a-helper-function-for-discount-pricing-calculations.md)
+- [The discount calculation uses a multiplier approach (1 - discount_rate) rather than direct subtraction, which is a common pattern for composable percentage calculations.](code_pattern/the-discount-calculation-uses-a-multiplier-approach-1.md)
+
+## Domain Knowledge (4)
+
+- [Clarify discount_rate input format and tax application semantics in documentation since they directly affect invoice calculations.](domain_knowledge/clarify-discount-rate-input-format-and-tax-application.md)
+- [discount_amount represents an absolute value rather than a percentage, with tax calculated post-discount; percentage discounts would be handled separately.](domain_knowledge/discount-amount-represents-an-absolute-value-rather-than-a.md)
+- [Tax calculation order relative to discounts is a business rule that needs explicit documentation.](domain_knowledge/tax-calculation-order-relative-to-discounts-is-a-business.md)
+- [The pricing rule applies absolute discounts before tax calculation, with the business logic now documented in code and demonstrated in test cases.](domain_knowledge/the-pricing-rule-applies-absolute-discounts-before-tax.md)
+
+## Gotcha (7)
+
+- [Discount amounts are not validated, allowing negative totals and tax calculations to propagate invalid charges downstream.](gotcha/discount-amounts-are-not-validated-allowing-negative-totals.md)
+- [Renaming a function parameter breaks backward compatibility for callers using keyword arguments, with no migration path provided.](gotcha/renaming-a-function-parameter-breaks-backward-compatibility.md)
+- [Renaming a function parameter breaks backward compatibility for callers using keyword arguments without providing a deprecation path.](gotcha/renaming-a-function-parameter-breaks-backward-compatibility-2.md)
+- [The function now prevents negative charges and taxes by rejecting negative discounts and clamping subtotals to zero, addressing unexpected edge case behavior.](gotcha/the-function-now-prevents-negative-charges-and-taxes-by.md)
+- [The new percentage discount function lacks input validation, allowing negative discount rates to increase totals and rates above 1.0 to produce negative totals, unlike the existing absolute discount h](gotcha/the-new-percentage-discount-function-lacks-input-validation.md)
+- [Unbounded discount_rate parameter can produce negative totals or unintended surcharges due to missing input validation, unlike the similar absolute discount function that includes guards.](gotcha/unbounded-discount-rate-parameter-can-produce-negative.md)
+- [Unvalidated discount_rate values can produce incorrect pricing (surcharges or negative totals) while maintaining mathematical validity, making bugs hard to detect.](gotcha/unvalidated-discount-rate-values-can-produce-incorrect.md)

kb/architecture_decision/chose-to-maintain-backward-compatibility-through-an-alias.md

@@ -0,0 +1,36 @@
+---
+pr_url: https://github.com/Galzi1/github-pr-kb-demo/pull/1
+pr_title: "feat: add discount pricing helper for review demo"
+comment_url: https://github.com/Galzi1/github-pr-kb-demo/pull/1#discussion_r3064070142
+author: "Galzi1"
+date: 2026-04-10T11:55:31+00:00
+category: architecture_decision
+confidence: 0.82
+needs_review: false
+comment_id: 3064070142
+---
+
+# Chose to maintain backward compatibility through an alias while explicitly rejecting dual parameter usage to enforce a clear migration path.
+
+## Context
+
+Not stated in the source comment.
+
+## Decision
+
+The pricing helper was modified to establish a clear primary parameter name while maintaining backward compatibility. The parameter `sales_tax_rate` was designated as the primary name, with `tax_rate` added as a compatibility alias for existing callers using the older name. The implementation explicitly prevents simultaneous use of both parameter names to ensure the transition between naming conventions remains intentional and visible.
+
+## Consequences
+
+Callers using the older `tax_rate` parameter name will continue to function without modification. However, any code attempting to pass both `sales_tax_rate` and `tax_rate` simultaneously will be rejected by the helper, enforcing an explicit migration path for affected code.
+
+```
+@@ -5,5 +5,10 @@ def greet(name: str) -> str:
+     return f"Hello, {name}!"
+
+
+-def calculate_total(subtotal: float, tax_rate: float) -> float:
+-    return round(subtotal * (1 + tax_rate), 2)
++def calculate_total(subtotal: float, sales_tax_rate: float) -> float:
++    return round(subtotal * (1 + sales_tax_rate), 2)
+```

kb/architecture_decision/consolidating-percentage-and-absolute-discount-calculations.md

@@ -0,0 +1,43 @@
+---
+pr_url: https://github.com/Galzi1/github-pr-kb-demo/pull/3
+pr_title: "feat: add percentage discount helper for demo review"
+comment_url: https://github.com/Galzi1/github-pr-kb-demo/pull/3#discussion_r3066907115
+author: "Galzi1"
+date: 2026-04-10T21:53:42+00:00
+category: architecture_decision
+confidence: 0.92
+needs_review: false
+comment_id: 3066907115
+---
+
+# Consolidating percentage and absolute discount calculations through a single normalization path reduces maintenance burden and prevents pricing logic divergence.
+
+## Context
+
+A percentage discount helper was needed for demo review purposes. The implementation required a decision about how to handle the calculation flow for percentage-based discounts in relation to existing discount processing.
+
+## Decision
+
+Percentage discounts are routed through the same normalization pathway as the existing absolute-discount helper rather than creating a separate calculation flow. This approach consolidates discount processing into a single shared path for handling validation, tax calculations, and rounding operations.
+
+## Consequences
+
+Maintaining a unified processing path for all discount types reduces the risk of pricing logic diverging between different discount calculation methods during future modifications. Centralized processing makes it easier to apply consistent rules and changes across all discount scenarios.
+
+```
+@@ -28,3 +28,14 @@ def calculate_total_with_discount(subtotal: float, sales_tax_rate: float, discou
+
+     discounted_subtotal = max(subtotal - discount_amount, 0.0)
+     return calculate_total(discounted_subtotal, sales_tax_rate=sales_tax_rate)
++
++
++def calculate_total_with_percentage_discount(
++    subtotal: float,
++    sales_tax_rate: float,
++    discount_rate: float,
++) -> float:
++    """Apply a percentage discount before tax."""
++
++    discounted_subtotal = subtotal * (1 - discount_rate)
++    return calculate_total(discounted_subtotal, sales_tax_rate=sales_tax_rate)
+```

kb/architecture_decision/question-about-whether-the-discount-api-should-support-both.md

@@ -0,0 +1,39 @@
+---
+pr_url: https://github.com/Galzi1/github-pr-kb-demo/pull/1
+pr_title: "feat: add discount pricing helper for review demo"
+comment_url: https://github.com/Galzi1/github-pr-kb-demo/pull/1#discussion_r3064005728
+author: "Galzi1"
+date: 2026-04-10T11:48:16+00:00
+category: architecture_decision
+confidence: 0.92
+needs_review: false
+comment_id: 3064005728
+---
+
+# Question about whether the discount API should support both absolute amounts and percentages, and the naming implications of choosing one representation.
+
+## Context
+
+A discount pricing helper was introduced to support the review demo feature. The implementation required deciding how to model discount values in the API, specifically whether to support only absolute currency amounts or to extend the model to include percentage-based discounts as well.
+
+## Decision
+
+Not stated in the source comment.
+
+## Consequences
+
+Not stated in the source comment.
+
+```
+@@ -5,5 +5,10 @@ def greet(name: str) -> str:
+     return f"Hello, {name}!"
+
+
+-def calculate_total(subtotal: float, tax_rate: float) -> float:
+-    return round(subtotal * (1 + tax_rate), 2)
++def calculate_total(subtotal: float, sales_tax_rate: float) -> float:
++    return round(subtotal * (1 + sales_tax_rate), 2)
++
++
++def calculate_total_with_discount(subtotal: float, sales_tax_rate: float, discount_amount: float) -> float:
+```

kb/code_pattern/adding-a-helper-function-for-discount-pricing-calculations.md

@@ -0,0 +1,29 @@
+---
+pr_url: https://github.com/Galzi1/github-pr-kb-demo/pull/1
+pr_title: "feat: add discount pricing helper for review demo"
+comment_url: https://github.com/Galzi1/github-pr-kb-demo/pull/1#issuecomment-4223263760
+author: "qodo-code-review[bot]"
+date: 2026-04-10T11:12:48+00:00
+category: code_pattern
+confidence: 0.75
+needs_review: false
+comment_id: 4223263760
+---
+
+# Adding a helper function for discount pricing calculations that applies discounts before tax computation.
+
+## Pattern
+
+This pattern implements pricing calculation helpers that support both standard and discounted pricing scenarios. The implementation involves a parameter rename for clarity and the addition of a new function to handle discount applications.
+
+The existing calculation function uses a sales tax rate parameter (renamed from the previous `tax_rate` designation) to compute totals with tax applied. A new complementary function extends this capability by accepting a discount amount that is subtracted from the subtotal before tax calculation is performed.
+
+The two functions work together, with the discount-aware function leveraging the tax calculation logic of the original function to produce the final discounted total with tax included.
+
+## When to Use
+
+Not stated in the source comment.
+
+## Example
+
+Not stated in the source comment.

kb/code_pattern/the-discount-calculation-uses-a-multiplier-approach-1.md

@@ -0,0 +1,25 @@
+---
+pr_url: https://github.com/Galzi1/github-pr-kb-demo/pull/3
+pr_title: "feat: add percentage discount helper for demo review"
+comment_url: https://github.com/Galzi1/github-pr-kb-demo/pull/3#issuecomment-4226957527
+author: "qodo-code-review[bot]"
+date: 2026-04-10T21:42:21+00:00
+category: code_pattern
+confidence: 0.78
+needs_review: false
+comment_id: 4226957527
+---
+
+# The discount calculation uses a multiplier approach (1 - discount_rate) rather than direct subtraction, which is a common pattern for composable percentage calculations.
+
+## Pattern
+
+A percentage discount helper function applies discounts to a subtotal before tax calculation. The function accepts three parameters: the subtotal amount, a sales tax rate, and a discount rate. It calculates the discounted subtotal using a multiplier approach by multiplying the subtotal by (1 - discount_rate). The resulting discounted subtotal is then passed to an existing total calculation function that applies the sales tax rate to produce the final total.
+
+## When to Use
+
+This pattern is useful in pricing calculation workflows where percentage-based discounts need to be applied before tax computation. It provides a dedicated helper function that separates discount logic from tax calculation, making the pricing computation more modular and easier to review.
+
+## Example
+
+Not stated in the source comment.

kb/domain_knowledge/clarify-discount-rate-input-format-and-tax-application.md

@@ -0,0 +1,45 @@
+---
+pr_url: https://github.com/Galzi1/github-pr-kb-demo/pull/3
+pr_title: "feat: add percentage discount helper for demo review"
+comment_url: https://github.com/Galzi1/github-pr-kb-demo/pull/3#discussion_r3066907152
+author: "Galzi1"
+date: 2026-04-10T21:53:43+00:00
+category: domain_knowledge
+confidence: 0.92
+needs_review: false
+comment_id: 3066907152
+---
+
+# Clarify discount_rate input format and tax application semantics in documentation since they directly affect invoice calculations.
+
+## Context
+
+A percentage discount helper function has been added as part of demo review functionality. This helper complements an existing absolute-discount helper with similar capabilities.
+
+## Key Insight
+
+The percentage discount helper requires explicit documentation of two critical business rules that are essential for correct invoice calculation:
+
+1. The expected format of the discount rate parameter—specifically whether values should be provided in the range of 0 to 1 (decimal format) or another convention
+2. The timing of tax application relative to the discount—whether the percentage discount is applied before or after tax calculations, consistent with how the absolute-discount helper operates
+
+These specifications must be clearly stated in the function's docstring rather than left implicit in the implementation logic.
+
+## Implications
+
+The discount semantics directly impact invoice behavior and calculation results. Without explicit documentation of the discount rate format and tax application order, implementation details could be misinterpreted or applied inconsistently, leading to incorrect financial calculations in generated invoices.
+
+```
+@@ -28,3 +28,14 @@ def calculate_total_with_discount(subtotal: float, sales_tax_rate: float, discou
+
+     discounted_subtotal = max(subtotal - discount_amount, 0.0)
+     return calculate_total(discounted_subtotal, sales_tax_rate=sales_tax_rate)
++
++
++def calculate_total_with_percentage_discount(
++    subtotal: float,
++    sales_tax_rate: float,
++    discount_rate: float,
++) -> float:
++    """Apply a percentage discount before tax."""
+```

kb/domain_knowledge/discount-amount-represents-an-absolute-value-rather-than-a.md

@@ -0,0 +1,42 @@
+---
+pr_url: https://github.com/Galzi1/github-pr-kb-demo/pull/1
+pr_title: "feat: add discount pricing helper for review demo"
+comment_url: https://github.com/Galzi1/github-pr-kb-demo/pull/1#discussion_r3064070542
+author: "Galzi1"
+date: 2026-04-10T11:55:34+00:00
+category: domain_knowledge
+confidence: 0.92
+needs_review: false
+comment_id: 3064070542
+---
+
+# discount_amount represents an absolute value rather than a percentage, with tax calculated post-discount; percentage discounts would be handled separately.
+
+## Context
+
+A discount pricing helper has been added to support review demo functionality. This helper is designed to handle discount calculations in a specific way.
+
+## Key Insight
+
+The discount pricing helper operates with two critical characteristics:
+
+1. The discount amount parameter represents an absolute value in currency units, not a percentage of the original price
+2. Tax calculation occurs after the discount is applied, meaning the tax is computed on the discounted price rather than the original price
+
+## Implications
+
+If percentage-based discounts are needed in the future, a separate helper function should be created rather than extending the existing helper to support both absolute and percentage discount types.
+
+```
+@@ -5,5 +5,10 @@ def greet(name: str) -> str:
+     return f"Hello, {name}!"
+
+
+-def calculate_total(subtotal: float, tax_rate: float) -> float:
+-    return round(subtotal * (1 + tax_rate), 2)
++def calculate_total(subtotal: float, sales_tax_rate: float) -> float:
++    return round(subtotal * (1 + sales_tax_rate), 2)
++
++
++def calculate_total_with_discount(subtotal: float, sales_tax_rate: float, discount_amount: float) -> float:
+```

kb/domain_knowledge/tax-calculation-order-relative-to-discounts-is-a-business.md

@@ -0,0 +1,25 @@
+---
+pr_url: https://github.com/Galzi1/github-pr-kb-demo/pull/1
+pr_title: "feat: add discount pricing helper for review demo"
+comment_url: https://github.com/Galzi1/github-pr-kb-demo/pull/1#issuecomment-4223530384
+author: "Galzi1"
+date: 2026-04-10T11:48:28+00:00
+category: domain_knowledge
+confidence: 0.92
+needs_review: false
+comment_id: 4223530384
+---
+
+# Tax calculation order relative to discounts is a business rule that needs explicit documentation.
+
+## Context
+
+A discount pricing helper has been added to support review demonstrations. This helper processes pricing calculations that involve both discounts and taxes.
+
+## Key Insight
+
+The current implementation applies tax calculations to the subtotal after discounts have been applied. This approach treats the discount as reducing the taxable base amount.
+
+## Implications
+
+This tax-after-discount sequencing should be documented explicitly as a business rule to ensure clarity around how pricing is calculated when both discounts and taxes are involved in transactions.

kb/domain_knowledge/the-pricing-rule-applies-absolute-discounts-before-tax.md

@@ -0,0 +1,25 @@
+---
+pr_url: https://github.com/Galzi1/github-pr-kb-demo/pull/1
+pr_title: "feat: add discount pricing helper for review demo"
+comment_url: https://github.com/Galzi1/github-pr-kb-demo/pull/1#issuecomment-4223569372
+author: "Galzi1"
+date: 2026-04-10T11:55:35+00:00
+category: domain_knowledge
+confidence: 0.92
+needs_review: false
+comment_id: 4223569372
+---
+
+# The pricing rule applies absolute discounts before tax calculation, with the business logic now documented in code and demonstrated in test cases.
+
+## Context
+
+A discount pricing helper was added to support a review demonstration. This implementation follows up on a previous discussion regarding pricing rules and makes the business logic explicit within the code documentation.
+
+## Key Insight
+
+The discount pricing helper applies discounts in a specific sequence: an absolute discount is applied to the original subtotal first, and then tax is calculated on the discounted amount rather than the original price. This ordering ensures the demonstration accurately reflects the intended pricing behavior.
+
+## Implications
+
+Not stated in the source comment.