Crosspoint/.claude/skills/control-flow-clarity/SKILL.md

---

name: control-flow-clarity description: Branching and state-modeling clarity in C/C++. Use when writing or refactoring logic that branches on discrete values: if/else-if ladders, status flags, mode or state ints, or anything that should be an enum plus an exhaustive switch. Covers enum class over magic ints, exhaustive switch over nested if, early-return guard clauses, table dispatch, and when each is the right call.

Control-Flow Clarity

The goal: a reviewer verifies correctness by reading, not by tracing. Branching that mirrors the problem's shape is self-evident; branching that encodes it in ad-hoc ints and nesting forces the reader to reconstruct intent.

Core moves

• Model a closed set of states/modes as an enum class, not ints or bools. A variable kept honest by a comment ("0 = hidden, 1 = showing, 2 = confirm") is a latent bug. Make it an enum and the comment becomes the type.
• Dispatch on an enum with an exhaustive switch, no default. This codebase relies on it: omitting default lets the compiler flag the unhandled case when someone adds an enum value. A default: that swallows the unknown case throws that safety away. Add default only when "every other value does nothing" is a deliberate, documented decision.
• Replace nested if/else-if ladders that branch on one discriminant with a switch. If each branch only maps input to a value, prefer a lookup table (static constexpr array) over both.
• Prefer early-return guard clauses over nested success bodies. Handle the error/empty/skip cases first and return; keep the main path at the left margin.

When NOT to switch

• Branches test unrelated conditions, not one discriminant: a guarded if sequence is honest; a switch would be forced.
• Two outcomes on a genuine boolean: keep the if.
• The discriminant is an open or unbounded set (arbitrary ints, strings): table or map, not a switch.

Enum hygiene

• enum class by default for type safety. Plain enum only when values must implicitly convert (e.g. a value that doubles as a UI dropdown index), and then give it a trailing _COUNT sentinel for safe bounds/iteration, matching the existing settings enums.
• Name the discriminant after what it selects, not its storage: Orientation orientation, not uint8_t mode.
• No magic numeric codes for states. If you write a comment mapping numbers to meanings, you owe an enum.

Self-review

• No int/bool standing in for a closed set of modes; it is an enum class.
• Enum dispatch is an exhaustive switch with no catch-all default (or the default is a documented deliberate choice).
• No nested if/else-if ladder on a single discriminant that should be a switch or a table.
• Error/skip cases are early-return guards; the happy path is not buried.
• No magic numbers where a named enum or constexpr would state the intent.