mindbox-cloud/agent-skills / plugins/mindbox/skills/whypromo
whypromo
VerifiedExplain in plain language why a Mindbox promotion did not apply to an order, why its benefit came out zero or why the discount is smaller than expected: one reason and who to go to. Use when a cashier, a salesperson, a store manager or first-line support asks why a promotion did not work, or sends the explanation link from the admin panel (https://<project>.mindbox.ru/processing-orders/debugger?calculationId=...&promotionId=...) or a promotion link (https://<project>.mindbox.ru/promotions/<number>) together with an order number. Russian triggers: "почему не применилась акция", "не сработала скидка", "клиент жалуется на акцию", "промокод не сработал", "почему не списались баллы", "whypromo". English triggers: "why didn't the promotion apply", "the discount didn't work", "promo code didn't work", "why were no points redeemed". Don't use when: a technical breakdown with codes and stages is needed — ask for it separately; promotion settings, the promotion tree or the change history are asked for — the explanation does not contain them.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.6 KB |
| references/DECISION_FIELDS.md | markdown | 9.6 KB |
| references/ESCALATION.md | markdown | 7.3 KB |
| references/EXAMPLE_HUMAN.md | markdown | 4.6 KB |
| references/GATEWAY.md | markdown | 5.9 KB |
| references/HUMAN_STYLE.md | markdown | 8.9 KB |
| references/MCP_CONTRACT.md | markdown | 15.3 KB |
| references/PITFALLS.md | markdown | 13.8 KB |
| references/RECORDS.md | markdown | 13.4 KB |
| references/VERDICTS.md | markdown | 14.7 KB |
references/EXAMPLE_HUMAN.md
View on GitHub# Example explanation for a human
One end-to-end pass: what the user wrote, what came back from the tools, what they got as the answer.
## The user's input
> `https://demo-shop.mindbox.ru/promotions/40124947 8813322`
A promotion link and an order number. The project `demo-shop` and the promotion `40124947` come from the link; the order `8813322` is next to it. `tenant` is `demo-shop`.
`loyalty_find_order_calculations` with `orderExternalId: "8813322"` answers `FOUND`: one order, with one
history entry carrying a `calculationId`. Nothing to choose from, so no questions to the user; go straight to
`loyalty_explain_promotions` with that `calculationId` and the promotion `"40124947"`.
## Tool response (trimmed to what matters)
```json
{
"status": "EXPLAINED",
"explanation": {
"operation": "Website.CreateOrder",
"candidateCount": 14,
"inputs": { "isCustomerAuthorized": true, "limitsDataUnavailable": false },
"promotions": [{
"promotionId": "40124947",
"details": "AVAILABLE",
"promotion": { "kind": "MindboxPromotion", "name": "500 ₽ for every 5000 ₽", "state": "Execution" },
"verdict": { "kind": "BenefitConditionsNotMetVerdict",
"reason": { "code": "BenefitThresholdNotReached", "failureKind": "PreconditionSumBelowStep",
"params": { "thresholdAmount": 5000, "achievedAmount": 3200 },
"explanation": "The purchase amount for these products is less than the amount set in the benefit" },
"benefits": [{ "benefitId": "42400915", "blockType": "PRODUCT",
"status": { "kind": "BenefitConditionsNotMet",
"reason": { "code": "BenefitThresholdNotReached", "failureKind": "PreconditionSumBelowStep",
"params": { "thresholdAmount": 5000, "achievedAmount": 3200 },
"explanation": "The purchase amount for these products is less than the amount set in the benefit" } } }] },
"decisions": [
{ "seq": 118, "code": "BenefitThresholdNotReached", "stage": "Benefit", "outcome": "Fail",
"scope": "Promotion", "isTerminal": true, "promotionIds": ["40124947"],
"benefitId": "42400915", "benefitKind": "SegmentDiscountForOrderSumBenefitSettingDetail",
"blockOrdinal": 0, "lineKey": 0, "criterionName": "", "failureKind": "PreconditionSumBelowStep",
"payload": { "thresholdAmount": 5000, "achievedAmount": 3200 } }
]
}]
}
}
```
## Short answer: the default mode
> The promotion "500 ₽ for every 5000 ₽" did not apply: the purchase of the promotion's products is below the
> amount set in its conditions. It needs 5000 rubles, and the order reached 3200. The customer's card is fine.
> Add to the order, or ask the marketer who set up the promotion whether the threshold can be lowered. I can
> explain in more detail.
Three sentences, one reason, one pair of numbers, who to send the user to. The wording is a translation of
`explanation`, the numbers come from `params`. No record name, no word "benefit", no promotion number. The
closing offer does not say "show the numbers": the amount is the reason, and it is already named.
## The same case when the user asked for more detail
> The promotion "500 ₽ for every 5000 ₽" did not apply: it kicks in from 5000 rubles of purchases of its own
> products, and the order reached 3200, so 1800 was missing. The customer was identified, and the promotion
> itself took part in the calculation: it was rejected only at the amount condition, so that is the only thing in
> the way. If the threshold should be different, that is for the marketer who set up the promotion.
Added: the missing amount and the suspicions ruled out, each backed by data: the customer by
`isCustomerAuthorized`, the promotion's participation by the threshold record sitting at the benefit stage, which
means the promotion passed selection. Still no codes and no stages.
## What would be a mistake
- "The promotion was rejected at the Benefit stage by the BenefitThresholdNotReached record": the user knows
neither stages nor record names.
- "1800 kopecks were missing" or "18 rubles were missing": dividing by 100. Amounts come in the project's
currency (rubles for Russian projects), not in minor units.
- "The limit is exhausted": the response has `limitsDataUnavailable: false` and no record about exhaustion;
that is a different reason, and it was not here.
- Answering with the English `explanation` phrase as is when the user asked in Russian: answer in the user's
language.
- "The promotion is active now, so the dates are not the problem": `state` is about today, not about the purchase.
- Retelling all fourteen candidates: the question was about one promotion.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |