kelp/plugins/tiger-style/skills/tiger-patterns

Tiger Style -- Quick Reference

This project follows TigerBeetle's Tiger Style. For full rationale and worked examples, read ${CLAUDE_PLUGIN_ROOT}/docs/TIGER_STYLE_REFERENCE.md.

Safety

Assertions -- minimum two per function on average. Assert arguments, return values, pre/postconditions, invariants. Pair assertions across code paths. Assert positive space (what you expect) AND negative space (what you don't). Split compound asserts:

// WRONG
assert(a and b);
// RIGHT
assert(a);
assert(b);

Bounded loops, no recursion -- every loop has an upper bound; convert recursive algorithms to iterative. For genuinely non-terminating loops, assert:

while (true) {
    assert(self.running);
    // ...
}

Static memory -- allocate everything at init from a sized arena. After init, the allocator is read-only.

Errors -- handle every one. catch {} requires a comment explaining why dropping is safe. Brace multi-line if bodies.

Naming

• snake_case for fn / var / file. PascalCase for types.
• No abbreviations (except i, j, k for sort/matrix indices).
• Acronyms keep caps: VSRState, not VsrState.
• Units as suffixes, descending significance: latency_ms_max, bytes_per_sector.
• Helper called by one fn: prefix with caller name: read_sector_callback().
• Callbacks go last in parameter lists.
• Use options: struct when args could be mixed up:

pub fn open(path: []const u8, options: struct {
    read: bool = true,
    write: bool = false,
}) !File { ... }

Function Shape

• Hard limit: 70 lines per function.
• Inverse hourglass: few params, simple return, meaty middle.
• Centralize control flow -- don't duplicate branching in helpers.
• Push ifs up, push fors down.

Variables and Aliasing

• Smallest possible scope.
• Minimize variables in scope.
• Don't take aliases to variables.
• Args > 16 bytes that shouldn't copy: pass *const T.
• Group alloc + defer with surrounding newlines.

Comments

• Sentences: space after //, capital letter, period.
• Always say why, not what.
• For tests, describe goal AND methodology.

Formatting (Zig)

• zig fmt.
• 4-space indent.
• 100 columns hard, no exceptions.
• Trailing comma + zig fmt to wrap signatures.

Types and Division

• Sized types: u32, not usize (unless required by API).
• Show intent for division: @divExact, @divFloor, @divTrunc, or div_ceil -- never bare / on integers.
• Use explicitly-sized types like u32 for everything you control.

Performance Mindset

• Sketch back-of-envelope numbers in design phase.
• Optimize slowest resource first: network > disk > memory > CPU.
• Amortize by batching.
• Extract hot loops into standalone fns (no self).

Audit

Run /tiger-style:tiger-check to catch mechanical violations: oversized functions, long lines, usize, recursion, compound asserts, unbounded while (true).