Skip to main content

Documentation Index

Fetch the complete documentation index at: https://kode-f177b001.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

kode explain is your first stop when a verification gate keeps blocking a patch. You pass it the name of the failing gate, and it prints a structured Markdown report: what the gate checks, why it commonly fails, how to fix the underlying issue, and — if your audit log contains relevant entries — the most recent real examples from your own codebase. Use it alongside kode stats to move from “this gate is failing a lot” to “here is why and what to do about it.”

​
Synopsis

kode explain <check>
<check> is the name of the gate you want to diagnose. Check names are case-insensitive.

​
Available checks

NameGateDescription
syntaxSyntax GateCode parse errors and structurally invalid syntax
importsImports GateUnresolvable, hallucinated, or forbidden imports
callsCalls GateHallucinated function names or incorrect call signatures
architectureArchitecture GateModule boundary violations and circular dependency introduction
diff_applierDiff ApplierPatch context mismatch — the hunk could not be applied

​
Flags

FlagTypeDefaultDescription
--log-dirstring<cwd>/logsDirectory containing kode.log for pulling recent examples

​
Examples

kode explain imports

​
Output format

kode explain writes Markdown to stdout. The output has four sections: 1. Title and description — the gate’s full name and a one-paragraph summary of what it validates. 2. Common causes — a bullet list of the most frequent reasons this gate fires, ordered by how often they appear in practice. 3. How to fix — a bullet list of concrete remediation steps you can take immediately. 4. Recent examples from your audit log (when available) — up to five recent failures from logs/kode.log that match this gate, formatted as: 
- `path/to/file.go` at 2025-07-15T10:34:02Z: imports: unresolvable path github.com/example/fake
This section only appears when Kode can read your log file and finds matching entries. If the log does not exist or contains no matches, the first three sections are printed without it.

​
Gate reference

​
syntax

The Syntax Gate parses every generated file using the language compiler’s AST parser. It fires when the output is structurally invalid — missing brackets, incorrect indentation (Python/YAML), wrong language syntax, or truncated generation output. Common causes:
  • LLM generated incomplete or malformed code
  • Missing closing brackets, parentheses, or quotes
  • Incorrect indentation in Python or YAML files
  • Wrong language syntax used (for example, Python syntax in a Go file)
Fixes: Regenerate with a more targeted prompt, break the change into smaller hunks, or manually correct the syntax around the reported line number.

​
imports

The Imports Gate resolves every import path in the generated code against the project’s dependency manifest and internal package graph. It fires when a package does not exist, is not in scope, or violates internal visibility rules. Common causes:
  • LLM hallucinated a package name that does not exist
  • Import path is misspelled or references the wrong module version
  • Internal package imported from outside its allowed scope
  • Dependency is missing from go.mod, package.json, or equivalent
Fixes: Verify the import exists in the dependency manifest, run go get <package> (or the equivalent), or provide the correct import path in the prompt context.

​
calls

The Calls Gate cross-references every function and method call in the generated code against the known API surface of the imported packages. It fires when a function does not exist, the argument count is wrong, or the receiver type is incompatible. Common causes:
  • LLM hallucinated a function or method name
  • Wrong number or type of arguments
  • Calling a method on an incompatible or nil receiver
  • Using an unexported function from another package
Fixes: Provide the correct function signature in the prompt context, check the package’s actual API documentation, or regenerate with more context about the target API.

​
architecture

The Architecture Gate enforces the import rules defined in your kode.json. It fires when the generated code introduces an import that crosses a forbidden layer boundary or creates a new circular dependency. Common causes:
  • Code in a handler layer importing directly from a data layer
  • Circular dependency introduced between packages
  • Internal package exposed to an external consumer
  • Violation of project-specific architecture constraints in kode.json
Fixes: Restructure the code to respect layer boundaries, move the functionality to the correct package, define an interface in the allowed layer and implement it elsewhere, or update architecture rules in kode.json if the change is intentional.

​
diff_applier

The Diff Applier fires before any other gate — if a generated patch cannot be applied cleanly to the current file content, the hunk is rejected before verification even begins. This typically means the context lines in the diff do not match what is on disk. Common causes:
  • Context lines in the diff do not match the current file content
  • File was modified between context-assembly and patch application
  • Incorrect diff encoding or line ending mismatch
Fixes: Re-read the current file content and regenerate, ensure no concurrent edits are in progress, or use a simpler patch format.
Run kode stats first to find out which gate is failing most often in your project, then run kode explain <gate> on the top offender. The combination of aggregate stats and per-gate examples usually pinpoints the root cause within minutes.
  • kode stats — aggregate pass/fail rates and failure breakdowns by gate
  • kode loop — the pipeline that runs the verification gates