bosskuai-business-logic-review git:20261012.17c6803A

Immutable. This exact content never changes and is served at /api/v1/blob/aa84890ac32120d6.

---
name: bosskuai-business-logic-review
description: "Use when reviewing workflow rules for hidden business logic flaws: state transitions, approval and assignment design, edge cases, and rule consistency in products or systems."
---

# BosskuAI Business Logic Review

Use this skill when the main risk is **incorrect workflow rules**, not syntax errors or UI polish.

## How this differs from nearby skills

- **`bosskuai-rigorous-code-review`**: catches implementation bugs and code quality issues; load alongside when a code diff may encode wrong rules.
- **`bosskuai-diagnose-loop`**: traces known failure paths and correlates business-rule failures with logs, DB rows, job traces, and real incident evidence; load when a specific defect is already suspected.
- **`bosskuai-product-strategy`**: defines what the rules should be; this skill audits what they actually are.
- **`bosskuai-cybersecurity-risk`**: checks whether rules can be exploited; load alongside when auth, permissions, or financial logic is involved.

## Concrete examples (hidden logic failures)

Use these as patterns to hunt for in any domain — they are not exhaustive.

1. **Fulfillment without payment verification** — Orders move to `SHIPPED` or digital entitlements activate when `payment_status` is still `PENDING` or when only a client-side “success” page is shown. Webhook delay or PSP failure leaves inventory or access granted without settled funds.

2. **Partial cancellation, full charge** — User removes line items from a subscription or cart after a billing job runs; the next invoice still uses stale quantities or proration is skipped because cancel and bill are separate cron paths with no shared invariant check.

3. **Concurrent inventory oversell** — Two checkouts pass “stock > 0” reads and both decrement; no transactional guard or idempotent reservation, so sellable quantity goes negative or orders are accepted when stock is zero.

## Mindset

- A business logic bug is often silent — it produces wrong outcomes without throwing errors.
- Rules are only as safe as their **invariants**: what must always or never be true.
- State machines are the right mental model for most workflow logic.
- Cross-module side effects are the most dangerous — a rule change in one place silently breaks another.

## Workflow

1. **Map entities and lifecycle states** — For each core entity (order, user, invoice, job, booking), list all possible states and the transitions between them. Ask: are there states the system can reach that it should not?

2. **Define invariants** — Ask what must always be true and what must never happen:
   - "An order can only be fulfilled if payment is confirmed."
   - "A user cannot approve their own request."
   - "A balance cannot go negative without explicit overdraft permission."
   List these explicitly; they become the test of the review.

3. **Trace the happy path and failure paths** — Follow the full flow from trigger to terminal state. Then ask: what happens at each step if the expected precondition is false?

4. **Check handoffs and ownership transitions** — Who holds responsibility at each state? What happens if the handoff is missed? Who can undo or override?

5. **Check approval, retry, and reversal logic**:
   - Can approvals be bypassed or skipped under any conditions?
   - Does retry produce duplicates or unintended side effects?
   - Is reversal (refund, cancel, undo) handled at every state where it is reachable?

6. **Check time-based and threshold rules** — Deadlines, expiry, rate limits, quota checks, SLA breaches. Ask: what happens exactly at the boundary?

7. **Check cross-module side effects** — When state changes in one module, what does it trigger elsewhere? Are all downstream consumers aware of every possible transition?

## Finding workflows nobody wrote down

- Scan for entry points that imply a workflow: routes, queue workers, cron jobs, migrations (each implies a lifecycle), webhooks and infra config. A workflow in code with no spec gets edited without anyone knowing its shape.
- For each step, branch it: what if it fails, times out, returns nothing, or is retried? Write what cleans up after a failure at step N and who owns it.
- Write each handoff between services as a contract: payload, success, failure, timeout.
- List every timing assumption (step 4 slower than expected) and every unwritten assumption as an open question, with the code line that depends on it.
- Check the spec against the code, not against memory of the code.

## Guardrails

- Do not confuse input validation with business rules — they are different concerns.
- Do not assume that because a rule is implemented it is the right rule.
- Do not skip edge states (empty, deleted, expired, locked) — most logic bugs live there.
- Prefer state machine diagrams over prose when mapping transitions.

## Output format

```
Entity map:
  [entity] — states: [list] — transitions: [list]

Invariants:
  [list of "must always / never" rules]

Violations found:
  [entity/state/rule] — [what the code does] — [what it should do]

Dangerous assumptions:
  [assumption] — [what breaks if false]

Edge cases:
  [case] — [behavior] — [risk]

Recommended rule changes:
  [change] — [reason] — [smallest safe fix]
```

## References

- `../../references/checklists/business-logic-checklist.md`
- `../../references/pitfalls/business-logic-pitfalls.md`

Adapted from specialized/specialized-workflow-architect.md (agency-agents, MIT).