> ## Documentation Index > Fetch the complete documentation index at: https://docs.commenda.io/llms.txt > Use this file to discover all available pages before exploring further. # Assessment framework > Incident evaluation criteria and decision-making framework ## Overview This framework provides structured criteria for assessing incidents and determining appropriate response levels. Use these dimensions to classify incidents and guide decision-making. ## Assessment dimensions ### 1. Scope of impact Determines how many customers are affected and whether the issue is isolated or systemic. #### 1.1 Single-customer impact **Characteristics:** * Only one legal entity/customer affected * Often customer-specific configuration or integration issue * May be reproducible for other customers if triggered the same way **Examples:** * Bad address payload from specific customer * Customer-specific registration threshold configuration error * Customer-specific product mapping issue * Customer-specific exemption logic error **Response level:** Account manager handles with manager oversight **Key question:** Is this truly isolated or could it affect others? #### 1.2 Multi-customer partial impact **Characteristics:** * Subset of customers affected * Often tied to specific integration, jurisdiction, or feature * Most dangerous because it looks isolated but is systemic **Examples:** * Customers using specific integration (e.g., Shopify only) * Customers in specific jurisdiction (e.g., CA sourcing rule bug) * Customers using specific feature (MPU, marketplace logic, reverse charge) **Response level:** Manager involvement required; potential SWAT team **Key question:** What's the common factor? How many customers share it? #### 1.3 Global impact **Characteristics:** * All customers or all transactions affected * Platform-level issue * Immediate escalation required **Examples:** * Tax engine unavailable * Core ruleset regression * Address resolution failure * Rate service failure **Response level:** Immediate SWAT team activation; executive involvement **Key question:** How quickly can we contain and resolve? ### 2. Temporal nature Determines when the issue occurred and how long it persisted. #### 2.1 Hard downtime **Characteristics:** * Tax calculation endpoint unavailable * Timeouts/5xx errors * Explicit fail-closed behavior **Risk profile:** * Missed tax collection * Missing invoice fields * Customer operational blockage * Highly visible to customers **Response level:** Immediate; P0 incident **Key question:** How long was service unavailable? #### 2.2 Soft downtime **Characteristics:** * Calculations occur but are wrong * More dangerous than hard downtime * Often detected late **Examples:** * Zero tax applied incorrectly * Wrong jurisdiction sourced * Wrong rate applied * Exempt logic misfiring **Risk profile:** * Historical correction required * Compliance implications * Customer trust impact * May affect filed returns **Response level:** High priority; requires immediate investigation **Key question:** How long before we detected it? #### 2.3 Intermittent/partial failures **Characteristics:** * Only some transactions fail * Retry-dependent behavior * Time-window specific **Risk profile:** * Hardest to detect and explain * Difficult to reproduce * Customer confusion **Response level:** Moderate to high; requires detailed investigation **Key question:** Can we identify the pattern? ### 3. Financial exposure magnitude Determines the dollar value at risk. #### 3.1 De minimis exposure **Threshold:** \< \$1,000 total misreported tax **Characteristics:** * Low volume or test transactions * No filings impacted yet * Minimal customer impact **Response level:** Account manager handles; document and inform **Remedy approach:** Low-dollar, low-visibility (Scenario 1) #### 3.2 Material but contained exposure **Threshold:** $1,000 - $10,000 **Characteristics:** * One or two jurisdictions * May affect filed vs. unfiled boundary * Moderate customer impact **Response level:** Manager oversight required **Remedy approach:** Standard remediation (Scenarios 2-5) #### 3.3 Material and reportable exposure **Threshold:** $10,000 - $100,000 **Characteristics:** * Multiple jurisdictions * Potential customer restatement or amended filings * Significant customer impact **Response level:** Executive involvement required **Remedy approach:** Enhanced support; potential fee credits #### 3.4 Systemic financial risk **Threshold:** > \$100,000 or growing without cap **Characteristics:** * Exposure grows with every transaction * No natural cap * Time-sensitive to stop propagation **Response level:** SWAT team activation; executive leadership **Remedy approach:** All available resources; potential customer tax recovery services ### 4. Compliance lifecycle impact Determines where in the tax lifecycle the error occurred. #### 4.1 Pre-invoice **Characteristics:** * Checkout failures * Draft invoices * Quoting flows * No compliance filing impact yet **Risk profile:** * Customer operational impact * Revenue blocking * No regulatory exposure yet **Response level:** Moderate to high depending on customer impact **Remediation complexity:** Low - can be corrected before finalization #### 4.2 Post-invoice, pre-filing **Characteristics:** * Incorrect tax on issued invoices * Can be corrected via credit memos/re-invoicing * Not yet reported to jurisdictions **Risk profile:** * Customer relationship impact * Billing corrections needed * No regulatory exposure yet **Response level:** Moderate to high **Remediation complexity:** Moderate - requires customer coordination #### 4.3 Post-filing **Characteristics:** * Returns already filed with incorrect data * Triggers amendments, penalties, interest * High reputational risk **Risk profile:** * Regulatory visibility * Potential penalties and interest * Audit risk * Significant remediation effort **Response level:** High to critical **Remediation complexity:** High - requires amended returns and jurisdiction coordination ### 5. Direction of error Determines whether tax was over-collected, under-collected, or mis-sourced. #### 5.1 Under-collection **Characteristics:** * Tax not charged when it should have been * Customer absorbs liability or must recover from end customers * Higher customer urgency **Risk profile:** * Customer out-of-pocket * Customer relationship strain * Difficult recovery from end customers * Audit exposure **Response level:** High - customer will escalate quickly **Remedy approach:** Scenario 2 (Under-collection) #### 5.2 Over-collection **Characteristics:** * Excess tax charged * Refund obligations * Customer trust issue **Risk profile:** * Customer complaints * Refund processing required * Lower regulatory risk * Reputational impact **Response level:** High - customer complaints drive urgency **Remedy approach:** Scenario 3 (Over-collection) #### 5.3 Misclassification without immediate dollar impact **Characteristics:** * Wrong tax code * Wrong exemption tagging * Latent risk that materializes later **Risk profile:** * May not be immediately visible * Audit risk * Future compliance issues **Response level:** Moderate - depends on potential future impact **Remedy approach:** Varies based on specific misclassification ### 6. Detectability and observability Determines how the issue was discovered. #### 6.1 Customer-reported **Characteristics:** * Found via support ticket * Often already escalated emotionally * Customer may have already contacted their customers **Response level:** High - customer is already upset **Approach:** * Acknowledge immediately * Investigate urgently * Provide frequent updates * Escalate if needed #### 6.2 Internally detected (automated) **Characteristics:** * Monitoring/anomaly detection * Rate spikes, zero-tax anomalies, jurisdiction drift * Caught before customer notices **Response level:** Moderate to high depending on impact **Approach:** * Investigate thoroughly before notifying customer * Prepare complete analysis * Proactive notification * Demonstrate competence #### 6.3 Latent/discovered during filing **Characteristics:** * Found weeks later * Highest remediation cost * Customer may be surprised **Response level:** High - requires careful communication **Approach:** * Complete investigation first * Prepare comprehensive remediation plan * Emphasize that we caught it before audit * Provide full support ### 7. Blast radius expansion risk Determines whether the issue is growing or contained. #### 7.1 Static **Characteristics:** * Historical only * No new transactions affected * Issue is resolved **Response level:** Moderate - focus on remediation **Approach:** * Quantify total impact * Execute remediation plan * Document lessons learned #### 7.2 Growing **Characteristics:** * Every new transaction compounds exposure * Issue is ongoing * Urgent containment needed **Response level:** Critical - stop the bleeding first **Approach:** * Immediate containment * Halt affected processes if necessary * Fix before full remediation * Communicate status to customers #### 7.3 Cascading **Characteristics:** * Downstream systems affected * Reporting, filings, ledger exports impacted * Multiple systems need correction **Response level:** Critical - SWAT team activation **Approach:** * Map all affected systems * Coordinate cross-functional response * Prioritize containment * Systematic remediation ### 8. Customer operational dependence Determines how critical tax calculation is to customer's business flow. #### 8.1 Non-blocking **Characteristics:** * Back-office reconciliation only * Customer can continue operations * Lower urgency **Response level:** Moderate **Approach:** * Standard remediation timeline * Regular updates * Focus on accuracy over speed #### 8.2 Revenue-blocking **Characteristics:** * Checkout or invoicing blocked * Customer cannot process sales * High urgency **Response level:** Critical - P0 incident **Approach:** * Immediate response * Workaround if possible * Frequent updates (hourly if needed) * Executive involvement #### 8.3 Regulator-facing **Characteristics:** * Real-time e-invoicing * SAF-T reporting * Clearance models * Regulatory deadline risk **Response level:** Critical - regulatory implications **Approach:** * Immediate escalation * Regulatory expertise involved * Coordinate with customer's compliance team * Document everything ### 9. Regulatory sensitivity Determines jurisdiction-specific risk factors. #### High-sensitivity jurisdictions **Characteristics:** * Real-time reporting requirements (e.g., Brazil, Italy, Mexico) * High penalty severity * Aggressive audit practices * Short correction windows **Examples:** * Brazil (NF-e) * Italy (FatturaPA) * Mexico (CFDI) * California (aggressive audits) **Response level:** Elevated for these jurisdictions **Approach:** * Involve jurisdiction specialists * Prioritize these jurisdictions in remediation * Extra documentation * Consider local counsel #### Moderate-sensitivity jurisdictions **Characteristics:** * Standard audit practices * Reasonable correction windows * Moderate penalties **Examples:** * Most U.S. states * Canada * UK **Response level:** Standard **Approach:** * Follow standard remediation procedures * Document thoroughly * Timely corrections #### Low-sensitivity jurisdictions **Characteristics:** * Infrequent audits * Low penalties * Flexible correction processes **Response level:** Standard to low **Approach:** * Standard remediation * May prioritize other jurisdictions first ### 10. Internal responsibility classification Determines accountability and response approach. #### Platform bug **Characteristics:** * Core tax engine issue * Affects multiple customers * Commenda's responsibility **Response approach:** * Full ownership * Proactive notification * Enhanced support * Consider fee credits #### Content/rules bug **Characteristics:** * Tax rate or rule error * Often jurisdiction-specific * Commenda's responsibility **Response approach:** * Full ownership * Verify with jurisdiction * Proactive notification * Standard support #### Integration bug **Characteristics:** * Connector or API issue * May be Commenda or third-party * Shared responsibility **Response approach:** * Determine root cause * Coordinate with third party if needed * Proactive notification * Standard support #### Customer misconfiguration **Characteristics:** * Customer setup error * Customer's responsibility * Commenda provides guidance **Response approach:** * Educate customer * Help correct configuration * May charge for extensive support * Document proper setup #### Third-party dependency failure **Characteristics:** * External service issue * Outside Commenda's control * Shared impact **Response approach:** * Coordinate with third party * Keep customer informed * Provide workarounds if possible * Document for SLA purposes ## Decision matrix Use this matrix to determine response level based on key factors: | Exposure | Customers | Filings | Response level | Approval needed | | ---------- | ---------------- | ------- | -------------- | --------------- | | \< \$1K | Single | None | Low | Account manager | | \< \$5K | Single | None | Moderate | Manager | | \< \$5K | Multiple | None | High | Manager | | $5K-$10K | Single | None | High | Manager | | $5K-$10K | Multiple | None | Critical | Executive | | $10K-$100K | Any | None | Critical | Executive | | > \$100K | Any | Any | SWAT team | Executive | | Any | Any | Filed | +1 level | +1 level | | Any | Revenue-blocking | Any | Critical | Executive | ## Assessment checklist Use this checklist when assessing any incident: ### Initial assessment (within 1 hour) * [ ] How was issue detected? * [ ] Is issue ongoing or resolved? * [ ] How many customers affected? * [ ] Estimated financial exposure? * [ ] Are customers blocked from operations? * [ ] Have any returns been filed? ### Detailed assessment (within 4 hours) * [ ] Exact customer list identified? * [ ] Precise financial exposure calculated? * [ ] Root cause identified? * [ ] Fix verified? * [ ] Compliance lifecycle impact determined? * [ ] Direction of error confirmed? * [ ] Blast radius assessed? * [ ] Regulatory sensitivity evaluated? * [ ] Responsibility determined? ### Remediation planning (within 8 hours) * [ ] Scenario classification determined? * [ ] Remediation approach selected? * [ ] Customer communications drafted? * [ ] Approval obtained? * [ ] Resources allocated? * [ ] Timeline established? ### Execution tracking (ongoing) * [ ] Customers notified? * [ ] Remediation actions in progress? * [ ] Customer responses tracked? * [ ] Technical corrections completed? * [ ] Documentation maintained? * [ ] Lessons learned captured? ## Escalation triggers Escalate immediately if any of these conditions are met: ### To manager * Exposure > \$5,000 * Multiple customers affected * Customer is upset or threatening * Unclear how to proceed * Issue is growing ### To executive team * Exposure > \$10,000 * Filed returns impacted * Customer threatens legal action * Media attention * Regulatory inquiry * Platform-wide issue ### To SWAT team * Exposure > \$100,000 * Real-time reporting jurisdictions affected * Cascading downstream effects * Reputational risk * Multiple executives involved ## Common assessment mistakes ### Underestimating scope **Mistake:** Assuming issue is isolated when it's actually systemic **Prevention:** * Always ask: "Could this affect other customers?" * Check for common factors (integration, jurisdiction, feature) * Review recent changes that could have broader impact ### Overestimating urgency **Mistake:** Treating every issue as critical **Prevention:** * Use decision matrix objectively * Consider actual customer impact, not just dollar amount * Distinguish between urgent and important ### Delayed escalation **Mistake:** Trying to handle beyond your authority level **Prevention:** * Escalate early when in doubt * Use escalation triggers as guide * Better to escalate unnecessarily than too late ### Incomplete assessment **Mistake:** Starting remediation before full assessment **Prevention:** * Complete assessment checklist * Gather all facts first * Don't rush to solutions ### Poor documentation **Mistake:** Not documenting assessment and decisions **Prevention:** * Document as you go * Record key decisions and rationale * Maintain audit trail ## Assessment tools ### Exposure calculator ``` Total Exposure = Σ (Transaction Amount × Tax Rate Difference) Where: - Transaction Amount = Taxable amount per transaction - Tax Rate Difference = |Correct Rate - Applied Rate| - Σ = Sum across all affected transactions ``` ### Customer impact score ``` Impact Score = (Exposure × Urgency × Relationship Value) / 1000 Where: - Exposure = Dollar amount - Urgency = 1 (low) to 5 (critical) - Relationship Value = 1 (small) to 5 (strategic) Score > 50 = Executive involvement Score 20-50 = Manager involvement Score < 20 = Account manager handles ``` ### Remediation complexity score ``` Complexity = (Customers × Jurisdictions × Filing Status × Direction) Where: - Customers = Number affected - Jurisdictions = Number affected - Filing Status = 1 (pre-filing) or 3 (post-filing) - Direction = 1 (over) or 2 (under) or 3 (wrong jurisdiction) Score > 50 = High complexity (SWAT team) Score 20-50 = Moderate complexity (Manager + team) Score < 20 = Low complexity (Account manager) ``` Use these tools as guides, not absolute rules. Apply judgment based on specific circumstances.