traffic-light-findings git:20260927.2f2f40bA

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

---
name: traffic-light-findings
description: Convention for reporting findings with a traffic-light severity (🔴 blocking, 🟠 worth discussing, 🟡 minor) and stable IDs. Use it whenever you review, audit, challenge or verify anything and report what you found — code reviews, security reviews, devil's advocate passes, premortems, verification reports, browser test reports, triage lists — and whenever the user asks for a "semaphore", "traffic light", severity levels or a ranked list of issues. Also use it when you consolidate findings from several reviewers or subagents.
---

# Traffic-light findings

If AGENTS.md sets a different convention for this topic, follow AGENTS.md.

## Severity

| Light | Meaning | What happens next |
| --- | --- | --- |
| 🔴 | Blocking. It must be fixed before the work moves on (merge, release, next phase). | Fix it or get an explicit decision from the user. |
| 🟠 | Worth discussing. It is a real problem or a strong counter-argument, but it does not block. | Discuss, then fix or record the decision. |
| 🟡 | Minor. A warning without real risk, or a cosmetic issue. | Fix when convenient, or accept. |

Choose the light by impact and likelihood together. If a finding is blocking only in some contexts (for example, only behind a proxy), say so and give the light for each context.

## Finding format

Give every finding a stable ID. Use a prefix that shows its source and a number: `RT1` (red team), `B2` (browser test), `V3` (verification), `P4` (production readiness), `AC-17` (acceptance criterion). Do not renumber IDs after you share them. If you must renumber, show the old and new IDs.

Each finding has an ID and a one-line title, where (`file:line`, route, document section or command), evidence (a short quote, a reproduction or test output), impact (what goes wrong, for whom) and a concrete recommendation.

## Evidence rules

- Verify before you claim. Read the code or reproduce the behavior.
- Mark findings that you reproduced yourself with ✔.
- Separate evidence from speculation. Write "not verified" when you infer something.
- Do not report a finding that you cannot connect to the code, the docs or a reproduction.

## Consolidating several reports

When you merge reports from several reviewers or subagents:

1. Merge duplicates into one finding. List who found it ("Found by: security, architecture").
2. Keep the highest severity that the evidence supports. Say when you changed a reviewer's light and why.
3. Reproduce the 🔴 and the most important 🟠 findings yourself before you report them.
4. Add a section "Verified without findings" for checks that passed. It shows what was covered.

## Summary block

Start every report with the counts:

| | Count |
| --- | --- |
| 🔴 Blocking | n |
| 🟠 Worth discussing | n |
| 🟡 Minor | n |

## Asking the user to choose

When you ask the user which findings to act on, quote each one by ID **and** title. Check the IDs against the list before you send the question. A wrong number makes the user's answer ambiguous.