# 🔎 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

```bash
# 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
```