chore: update PR knowledge base

[Galzi1]

Automated update of the PR knowledge base.

[qodo-code-review]

Review Summary by Qodo

Populate PR knowledge base with pricing helper insights and best practices

✨ Enhancement 📝 Documentation

Walkthroughs

Description

• Populated knowledge base with 16 documented insights from PR reviews
• Added architecture decisions on backward compatibility and discount consolidation
• Documented domain knowledge about discount and tax calculation semantics
• Captured code patterns and gotchas related to pricing helper functions

Diagram

flowchart LR
  KB["Knowledge Base"] --> MANIFEST["Manifest Index"]
  KB --> INDEX["INDEX.md"]
  MANIFEST --> AD["Architecture Decisions<br/>3 entries"]
  MANIFEST --> CP["Code Patterns<br/>2 entries"]
  MANIFEST --> DK["Domain Knowledge<br/>4 entries"]
  MANIFEST --> GT["Gotchas<br/>7 entries"]
  AD --> COMPAT["Backward Compatibility"]
  AD --> CONSOL["Discount Consolidation"]
  AD --> QUESTION["API Design Question"]
  CP --> HELPER["Discount Helper Pattern"]
  CP --> MULT["Multiplier Approach"]
  DK --> ABSVAL["Absolute Value Semantics"]
  DK --> TAXORDER["Tax Calculation Order"]
  DK --> TAXDOC["Tax Documentation"]
  DK --> PRICERULE["Pricing Rule"]
  GT --> VALIDATE["Validation Issues"]
  GT --> COMPAT2["Compatibility Breaking"]
  GT --> NEGATIVE["Negative Totals"]

Loading

File Changes

1. kb/.manifest.json ⚙️ Configuration changes +18/-1

Created manifest mapping comment IDs to knowledge base files

kb/.manifest.json

---

2. kb/INDEX.md 📝 Documentation +28/-0

Added comprehensive index organizing 16 knowledge base entries

kb/INDEX.md

---

3. kb/architecture_decision/chose-to-maintain-backward-compatibility-through-an-alias.md 📝 Documentation +36/-0

Documented backward compatibility strategy using parameter aliases

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

---

View more (15)

4. kb/architecture_decision/consolidating-percentage-and-absolute-discount-calculations.md 📝 Documentation +43/-0

Documented unified discount calculation normalization approach

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

---

5. kb/architecture_decision/question-about-whether-the-discount-api-should-support-both.md 📝 Documentation +39/-0

Documented API design question on discount type support

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

---

6. kb/code_pattern/adding-a-helper-function-for-discount-pricing-calculations.md 📝 Documentation +29/-0

Documented discount pricing helper function pattern

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

---

7. kb/code_pattern/the-discount-calculation-uses-a-multiplier-approach-1.md 📝 Documentation +25/-0

Documented multiplier approach for percentage discount calculations

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

---

8. kb/domain_knowledge/clarify-discount-rate-input-format-and-tax-application.md 📝 Documentation +45/-0

Documented discount rate format and tax application semantics

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

---

9. kb/domain_knowledge/discount-amount-represents-an-absolute-value-rather-than-a.md 📝 Documentation +42/-0

Documented absolute value semantics of discount amounts

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

---

10. kb/domain_knowledge/tax-calculation-order-relative-to-discounts-is-a-business.md 📝 Documentation +25/-0

Documented tax calculation order as business rule

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

---

11. kb/domain_knowledge/the-pricing-rule-applies-absolute-discounts-before-tax.md 📝 Documentation +25/-0

Documented pricing rule for discount-before-tax application

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

---

12. kb/gotcha/discount-amounts-are-not-validated-allowing-negative-totals.md 📝 Documentation +49/-0

Documented gotcha about unvalidated discount amounts

kb/gotcha/discount-amounts-are-not-validated-allowing-negative-totals.md

---

13. kb/gotcha/renaming-a-function-parameter-breaks-backward-compatibility.md 📝 Documentation +36/-0

Documented backward compatibility issue with parameter renaming

kb/gotcha/renaming-a-function-parameter-breaks-backward-compatibility.md

---

14. kb/gotcha/renaming-a-function-parameter-breaks-backward-compatibility-2.md 📝 Documentation +31/-0

Documented parameter renaming impact on keyword argument callers

kb/gotcha/renaming-a-function-parameter-breaks-backward-compatibility-2.md

---

15. kb/gotcha/the-function-now-prevents-negative-charges-and-taxes-by.md 📝 Documentation +41/-0

Documented negative value prevention in discount calculations

kb/gotcha/the-function-now-prevents-negative-charges-and-taxes-by.md

---

16. kb/gotcha/the-new-percentage-discount-function-lacks-input-validation.md 📝 Documentation +25/-0

Documented input validation gaps in percentage discount function

kb/gotcha/the-new-percentage-discount-function-lacks-input-validation.md

---

17. kb/gotcha/unbounded-discount-rate-parameter-can-produce-negative.md 📝 Documentation +43/-0

Documented unbounded discount rate parameter risks

kb/gotcha/unbounded-discount-rate-parameter-can-produce-negative.md

---

18. kb/gotcha/unvalidated-discount-rate-values-can-produce-incorrect.md 📝 Documentation +42/-0

Documented unvalidated discount rate pricing errors

kb/gotcha/unvalidated-discount-rate-values-can-produce-incorrect.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (4)   📘 Rule violations (0)   📎 Requirement gaps (0)   🎨 UX Issues (0)

🐞\ ≡ Correctness (2) ⚙ Maintainability (2)

1. Truncated KB title 🐞 ⚙

Description

The KB article and its INDEX entry contain an H1/title that is truncated mid-word (ends with
"absolute discount h"), degrading KB readability and making titles/search results unreliable.

Code

kb/gotcha/the-new-percentage-discount-function-lacks-input-validation.md[13]

+# 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

Evidence

The article’s H1 is cut off mid-word, and the INDEX repeats that same truncated text, so the KB will
display an incomplete title in both the article and the index.

kb/gotcha/the-new-percentage-discount-function-lacks-input-validation.md[13-13]
kb/INDEX.md[21-29]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The KB article title is truncated mid-word, and the INDEX entry reproduces the truncated title.

### Issue Context
This appears to be a generation/truncation artifact; fixing it requires updating both the article H1 and the corresponding INDEX link text so they match and are complete.

### Fix Focus Areas
- kb/gotcha/the-new-percentage-discount-function-lacks-input-validation.md[13-13]
- kb/INDEX.md[26-28]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. KB title/body mismatch 🐞 ≡

Description

The KB entry titled as a parameter-rename backward-compatibility issue actually describes discount
validation/negative totals in its Symptom/Root Cause sections, making the entry misleading.

Code

kb/gotcha/renaming-a-function-parameter-breaks-backward-compatibility-2.md[R13-22]

+# Renaming a function parameter breaks backward compatibility for callers using keyword arguments without providing a deprecation path.
+
+## Symptom
+
+The `calculate_total_with_discount` function allows discount amounts to exceed the subtotal, resulting in negative discounted subtotals. This causes the function to return negative totals (including negative tax amounts), which can propagate invalid charge amounts downstream if callers assume the returned values are non-negative.
+
+## Root Cause
+
+The function performs subtraction of the discount amount from the subtotal without any validation or bounds checking. When the discount amount is greater than the subtotal, the intermediate `discounted_subtotal` value becomes negative, and this negative value is passed directly to `calculate_total`, which applies the tax calculation and rounding to the invalid intermediate result.
+

Evidence

Within the same document, the H1 claims the topic is renaming a function parameter, but the body
discusses discount amounts exceeding subtotal and producing negative totals—an unrelated problem
statement.

kb/gotcha/renaming-a-function-parameter-breaks-backward-compatibility-2.md[13-22]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The KB article title and its Symptom/Root Cause content do not describe the same issue, which makes the KB entry misleading.

### Issue Context
This looks like a content assembly/copy error in the generated KB: either the title is wrong for the body, or the body is wrong for the title.

### Fix Focus Areas
- kb/gotcha/renaming-a-function-parameter-breaks-backward-compatibility-2.md[13-31]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Contradictory KB entry 🐞 ≡

Description

A KB entry claims the function "now" rejects negative discounts and clamps subtotals, but the
embedded diff snippet shown in the same entry demonstrates an implementation without that
validation/clamping.

Code

kb/gotcha/the-function-now-prevents-negative-charges-and-taxes-by.md[R25-41]

+The `calculate_total_with_discount` function now includes validation to reject negative discounts and ensures the discounted subtotal cannot fall below zero. This prevents the generation of negative charges or tax amounts during discount calculations.
+
+```
+@@ -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:
++    discounted_subtotal = subtotal - discount_amount
++    return calculate_total(discounted_subtotal, sales_tax_rate)
+```

Evidence

The narrative states validation/clamping was added, while the included code block shows only a raw
subtraction and a return call, with no checks or max(..., 0.0) clamp. This internal inconsistency
makes the KB guidance unreliable.

kb/gotcha/the-function-now-prevents-negative-charges-and-taxes-by.md[23-41]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The KB entry’s description of the fix and the embedded code snippet contradict each other.

### Issue Context
Either the prose should be updated to match the snippet, or the snippet should be updated to reflect the described validation/clamping behavior.

### Fix Focus Areas
- kb/gotcha/the-function-now-prevents-negative-charges-and-taxes-by.md[21-41]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Manifest missing newline 🐞 ⚙

Description

kb/.manifest.json is committed without a trailing newline, which can trigger linting/pre-commit
failures and causes noisy diffs on future edits.

Code

kb/.manifest.json[18]

+}

Evidence

The PR diff explicitly marks this file as having no newline at end-of-file; adding it aligns with
common formatting conventions and avoids tooling complaints.

kb/.manifest.json[1-18]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`kb/.manifest.json` lacks a trailing newline.

### Issue Context
Some linters and formatting tools require POSIX-style trailing newlines.

### Fix Focus Areas
- kb/.manifest.json[18-18]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more