Style Review

Style Review

Review naming, coding patterns, and style consistency against the codebase's existing conventions.

Scope

1. Naming and shape consistency

• naming consistency across types, constants, functions, and files
• renamed concepts stay aligned across code, tests, docs, and exported identifiers
• constructor and factory naming follows a single project convention
• module and file layout follows the established project structure
• import/export patterns are consistent across the codebase

2. Control flow and state modeling

• exhaustive handling of state variants where applicable
• consistent assertion and error patterns
• prefer explicit status/state fields over boolean flags for state transitions
• prefer guard clauses and early returns over deep nesting
• prefer data-driven lookups over long control-flow chains

3. Pattern consistency

Check where the codebase already has a clear local pattern:

• structural patterns (table-driven, rule-driven) where nearby code uses them
• error classification follows the project's established convention
• repeated argument groups that want one named type
• raw strings or magic values that should become typed constants
• sibling concepts with different intent should not collapse into one ambiguous shape or name

4. Readability and hygiene

• no banner or separator comments
• no unused params, dead branches, or ad-hoc fallbacks
• keep style aligned with nearby code
• abstractions must earn their complexity — if a wrapper adds no value, inline it
• avoid nested ternaries for branching logic; use explicit conditionals, maps, or helpers when multiple cases affect readability
• prefer clarity over cleverness: dense one-liners that require a mental pause should be simplified

Evidence threshold

Sections 1 and 3 require evidence of a local convention — cite the nearby code that establishes it. Sections 2 and 4 are default checks that apply without repo evidence, but cap them at Consider unless a documented convention elevates them. Never report a default check as must-fix.

Workflow

1. Identify local style conventions from nearby code.
2. Compare against repo-wide documented conventions.
3. Find concrete deviations with evidence. For large diffs (more than 3 files), fan out fast-tier readers — one per file or logical area — to surface candidate findings. Verify each before reporting.
4. Report findings ordered by severity.

Output

For each finding: label (Critical / Fix / Consider / Nit — see review), file, violated convention, evidence (cite both the offending line and the code that establishes the convention), fix direction.

• Bad: "getUserData — inconsistent, should be fetchUserData." (no evidence)
• Good: Fix — src/api/user.ts:12 getUserData breaks the fetch-prefix convention (9 of 10 siblings in src/api/ use fetch*). Rename to fetchUserData.

Order Critical → Fix → Consider → Nit. If nothing clears the threshold, report "No style findings" — don't pad.

Red flags

• Enforcing generic style dogma over local conventions
• Broad rewrites instead of minimal fixes
• Speculative abstractions
• Nitpicking formatting not tied to repo conventions

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cniska
• Source: cniska/skills
• License: MIT

Install and usage instructions live in the source repository linked above.