ai-coding-rules

FORWARD view over rules/ — domain type design and architectural planning for Go code BEFORE it exists. Use when planning new features, designing self-validating types, preventing primitive obsession, or when refactoring reveals need for new types. Dispatches into the Design guidance sections of rules/R1-R8 and R10-R12.

META ORCHESTRATOR for any Go code change that should end in a commit (features, bug fixes, refactors). WHEN: User requests Go code work (implement, fix, add, refactor), mentions "@ldd"/"ldd", or runs a /go-ldd-* command in a Go project. Runs the five-phase workflow (PREPARE is an autonomous sub-phase, 1.5): DESIGN → PREPARE → IMPLEMENT (per-behavior TDD loop) → FULL LINT (lint-fixer agent) → REVIEW (per slice) → SHIP.

ADVISORY pre-commit review that orchestrates parallel single-obsession rule hunters and an over-abstraction skeptic against the diff. Spawns read-only agents (rule-hunter, overabstraction-skeptic); NEVER edits code. Invoked by @linter-driven-development (Phase 4), by @refactoring (after pattern application), or manually for standalone code review. Categorizes findings as Bugs, Design Debt, Readability Debt, or Polish Opportunities. Does NOT block commits.

BACKWARD view over rules/ — routes linter and review failures to the rule whose Fix pattern owns the repair. Use when linter fails with complexity issues (cyclomatic, cognitive, maintainability) or when code feels hard to read/maintain. Also runs PREPARATORY mode: reshape code an approved plan touches, before the first RED, so the feature lands add-only. Applies storifying, type extraction, function extraction, conditional-dispatch, and mutation-discipline patterns via rules/R1-R8 and R10-R12.

Component and type design for TypeScript + React code. Use when planning new features, designing components and custom hooks, preventing primitive obsession, or when refactoring reveals need for new abstractions. Supports layer-based and hybrid architecture patterns with type safety.

Linter-driven refactoring patterns to reduce complexity and improve code quality in React/TypeScript. Use when ESLint fails with SonarJS complexity issues (cognitive, cyclomatic, expression) or when code feels hard to read/maintain. Applies component extraction, hook extraction, and simplification patterns.

The repo-brain author/maintainer: writes behavior-focused documentation and wires it into the documentation network defined by rules/R9-repo-brain.md. FEATURE mode (default): after feature implementation or bug fixes — invoked by @linter-driven-development (Phase 5) — to document HOW THE PRODUCT BEHAVES and wire it into the network. BOOTSTRAP mode: on request ("set up docs", "create an index", "make this repo AI-navigable", /wire-repo-brain) or when FEATURE mode finds no doc root — discovers the doc root, builds index.md, wires CLAUDE.md, wires missing code→docs edges, reports gaps. NOT a changelog - documents current behavior, not change history.

Use when creating leaf types, after refactoring, during implementation, or when testing advice is needed. Automatically invoked to write tests for new types, or use as testing expert advisor. Covers the composition ladder from rung-0 unit tests to whole-system tests, with emphasis on real in-memory dependencies. Ensures 100% coverage on leaf types with public API testing.

ADVISORY validation of code against design principles, accessibility, and best practices that linters cannot fully enforce. Use after linter passes and tests pass to validate design quality. Categorizes findings as Design Debt, Readability Debt, or Polish Opportunities. Does NOT block commits.

Generate comprehensive feature documentation including Storybook stories, JSDoc comments, and feature guides. Use after completing a feature (may span multiple commits). Creates documentation for humans and AI to understand features, usage patterns, and design decisions.

META ORCHESTRATOR for complete implementation workflow - design, test, lint, refactor, review, commit. Use for any code change that should result in a commit (features, bug fixes, refactors). Ensures clean code with tests, linting passes, and design validation.

Principles and patterns for writing effective React tests with React Testing Library (Jest/Vitest). Use during implementation for test structure guidance, choosing test patterns, and deciding testing strategies. Emphasizes testing user behavior, not implementation details.