kaizen-agentic/wiki/KaizenGuidance.md

KaizenGuidance

Codebase improvement programs

A curated, language-agnostic library of Code Quality Guides where each guide is:

• Readable for humans,
• Checkable by linters/static analyzers,
• Refactorable by codemods/agents,
• Measurable with before/after quality metrics.

Think “Clean Code + MISRA precision + Sonar/ESLint automation + AI codemods.”

See also: https://chatgpt.com/share/68d6b45b-17f8-8009-8d15-c174f53d2591

Guide anatomy (single source of truth)

• Each guide lives as a versioned folder containing:
• A manifest (machine-readable spec)
• A narrative (rationale, trade-offs, examples)
• Checks (lint/static analysis mappings)
• Refactors (codemods, recipes, prompts)
• Tests (fixtures + expected diffs)
• Metrics (what ‘better’ means)

Rule expression & execution pipeline

a) Parse → Check → Plan → Refactor → Test → Measure → Report

• Parse: build AST/index (libcst for Py, ts-morph/jscodeshift for TS/JS, OpenRewrite for Java, Clang-Tidy/LibTooling for C/C++).
• Check: run native linters + Semgrep queries from guide.yaml (unified output schema).
• Plan: produce a Change Plan (JSON) listing targets & suggested transforms.
• Refactor: deterministic codemods first; ambiguous edits delegated to an Agent with a strict prompt & test harness.
• Test: run unit tests + mutation tests (where available).
• Measure: compute deltas for maintainability index (MI), cyclomatic complexity, duplication, lint issues, “hotspot*rule” intersections (code churn × smells).
• Report: markdown/HTML summary + SARIF for code scanning.

Example guides (initial catalog)

1. API Design

• Avoid boolean “success” returns (above)
• Prefer narrow, explicit exceptions
• Make side effects explicit (naming & module boundaries)

2. Readability & Structure

• Function length & parameter count thresholds (with exceptions mechanism)
• Cohesion over convenience: one reason to change (SRP pragmatically)
• Replace “god module/class” with feature modules

3. Testing & Contracts

• Fast tests default; slow/flaky quarantined
• Golden tests for parsers/formatters
• Pre/postconditions via lightweight asserts or type contracts

4. Performance-safe Patterns

• Avoid N+1 queries (framework-specific codemods)
• Replace quadratic hot-loops with map/join or indexed lookups
• Lazy vs eager boundaries (measurable)

5. Security & Robustness

• Input validation at boundaries (web/cli)
• No raw SQL without parameterization
• Secrets/config separation; env-based wiring

Each guide ships checks + codemods + agent prompts + metrics.

xxx