Greg Gauthier
65f67ff7b1
- Add workon command to automate starting/completing todos/fixes - Generate AI-powered work plans and handle git branching - Update README and user docs with workon guide - Move workon todo item to completed
113 lines
4.2 KiB
Markdown
113 lines
4.2 KiB
Markdown
# 🔎 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
|
||
```
|