references/finding-taxonomy.md
Finding types
Severities
| Severity | Badge | Meaning | | -------- | ----- | --------------------------------------------------------------------------------- | | CRITICAL | 🔴 | Blocks correctness — experiment results may be invalid or flag behavior is broken | | WARNING | 🟡 | Needs attention — not broken yet but risks exist or best practices are violated | | INFO | 🔵 | Suggestion — hygiene improvement, safe to defer |
Finding categories
| Category | Description | Max severity | | ----------- | -------------------------------------------------------------------------------------------------- | ------------ | | Correctness | Integrity issues that affect experiment results or flag evaluation | CRITICAL | | Waste | Active resources not serving a purpose (running experiments going nowhere, flags nobody evaluates) | WARNING | | Process | Methodology and practice issues (missing hypothesis, no metrics) | WARNING | | Complexity | Fragility and maintainability concerns (too many toggles, high churn) | WARNING | | Cleanup | Hygiene items — stale drafts, orphaned flags, safe to defer | INFO | | Security | PII or access concerns in flag/experiment configuration | WARNING |
Severity caps
Never assign a severity higher than the category's max:
- A Cleanup finding is always INFO, never WARNING or CRITICAL.
- A Correctness finding can be CRITICAL, WARNING, or INFO depending on impact.
- A Waste or Process finding caps at WARNING.
Finding format
When reporting a finding, always include:
- Severity — one of CRITICAL, WARNING, INFO
- Category — one of the categories above
- Check name — which check produced this (e.g., "Metric setup", "Flag integration")
- Entity — which experiment or flag, as a markdown link
- Description — one sentence explaining what's wrong
- Action — one sentence explaining what to do (reference remediation actions)
Ordering
When listing multiple findings:
- Sort by severity: CRITICAL first, then WARNING, then INFO.
- Within the same severity, group by entity.
- Within the same entity, list by category: Correctness → Waste → Process → Complexity → Cleanup → Security.