grokkit/docs/user-guide/analyze.md

🔎 Analyze Guide

The analyze command performs a deep investigation of a codebase and produces a clean, educational Markdown report. It is designed as a didactic training tool for learning developers, hobbyists, and anyone onboarding to a new project.

Why use Analyze?

• Educational Focus: Explains not just what the code does, but how each function/method works and why it was included.
• Polyglot Support: Works for Go, Python, Java, C90, Rexx, Perl, JavaScript/TypeScript, and more via custom prompts.
• Project-Aware: Includes tech stack, module relationships, object ↔ data flow, and suggested learning paths.
• Transactional: Always shows a preview and requires explicit confirmation before writing (unless --yes).

Usage

# Analyze current directory (preview + confirmation)
grokkit analyze

# Analyze a specific directory
grokkit analyze --dir ./legacy-c90-project

# Write to custom file or stdout
grokkit analyze --output my-analysis.md
grokkit analyze --output -          # stdout only

# Skip confirmation (useful in scripts/CI)
grokkit analyze --yes

# Use a different model
grokkit analyze --model grok-4

Options

Flag	Short	Description	Default
--dir		Repository root to analyze	Current directory
--output	-o	Output file (- for stdout)	.grokkit/analysis.md
--yes	-y	Skip confirmation prompt	false
--model	-m	Override model	from config

Prompt Discovery (Automatic & Developer-First)

Grokkit automatically locates a language-specific system prompt using this exact order:

1. {PROJECT_ROOT}/.grokkit/prompts/{language}.md ← preferred (project-specific)
2. ~/.config/grokkit/prompts/{language}.md ← global fallback

Language is detected automatically via internal/linter.

If no prompt is found for the detected language, Grokkit prints a clear, actionable error message with exact paths where to create the file and exits without running analysis.

Supported languages (out of the box via the linter): go, python, javascript, typescript, java, c, cpp, rust, ruby, perl, shell, and others.

Adding Support for New Languages (C90, Rexx, Perl, etc.)

1. Create a new prompt file in .grokkit/prompts/ (or globally in ~/.config/grokkit/prompts/).
2. Name it after the language: c90.md, rexx.md, perl.md, etc.
3. Make it educational and specific to the language’s idioms.

Example starter for c90.md:

You are an expert C90 educator helping a hobbyist or learning developer understand legacy C code.

Generate a single, clean, educational Markdown report with these exact sections:

# Project Analysis: [Inferred Project Name]

## Tech Stack & Layout
...

## Function & Method Reference
For every function:
- What it does
- How it works (memory management, K&R vs ANSI style, etc.)
- Why it exists

## Learning Path & Gotchas
...
Be precise, encouraging, and focus on C90 constraints and common pitfalls.

Safety Features

• Preview: Shows the first ~60 lines of the generated report before writing.
• Confirmation: Requires explicit y/N unless --yes is used.
• No Auto-Write: Nothing is saved to disk without user approval.
• Git-Friendly: The generated analyze.md can be reviewed with git diff, reverted with git restore, or committed as documentation.

Best Practices

• Run grokkit analyze early when exploring a new codebase.
• Customize the prompt in .grokkit/prompts/ for your specific learning goals (e.g., focus on security for C, concurrency for Go, or monadic patterns for Rexx/Perl).
• Combine with other commands: use analyze for high-level understanding, then review for deeper logic critique, or lint for style issues.
• Commit the generated report if it helps team onboarding or personal reference.
• For very large projects, consider running with a faster model (--model grok-4-mini) or limiting scope with a project-specific prompt.

Example Workflow

# 1. Analyze the project
grokkit analyze

# 2. Review the generated report
less analyze.md

# 3. Commit as documentation (optional)
git add analyze.md
grokkit commit