grokkit/todo/completed/analyze-command.md

Feature: grokkit analyze — Deep project investigation & didactic report

Description grokkit analyze analyzes a repository root and produces an educational Markdown report covering tech stack, function/method explanations (how + why), module relationships, and object ↔ DB mappings where applicable.

Prompt Discovery (new requirement) No --prompt flag. Instead, automatically locate a language-specific prompt:

• First: {PROJECT_ROOT}/.grokkit/prompts/{language}.md (preferred)
• Then: ~/.config/grokkit/prompts/{language}.md (global)

Language is detected via internal/linter. If no prompt is found → clear terminal error with creation instructions (do not proceed with analysis).

Acceptance Criteria

• Command analyze in cmd/analyze.go
• Flags: --dir, --output, --yes, --model (no --prompt)
• Automatic prompt discovery with the exact two-path order above
• Uses internal/linter for language detection + file discovery
• Transactional: preview of generated report + y/N confirmation before writing (unless --yes)
• Ships with a solid default prompt for Go (docs/ or embedded)
• Full user-guide: docs/user-guide/analyze.md (includes how to add prompts for C90/Rexx/Perl/etc.)
• Updates to docs/user-guide/index.md, main README, and top-level docs
• Tests (including prompt-not-found case and custom prompt case)
• Thin cmd layer, structured logging, Git safety

Implementation Plan

1. Add command + flags (model after review.go / pr-describe.go)
2. Extend or reuse linter for project-wide language detection (pick primary language or handle multi-lang)
3. Implement prompt loader (project .grokkit/prompts/ → ~/.config/grokkit/prompts/)
4. Build rich context + loaded system prompt → Grok call
5. Preview + confirmation → write/print
6. Docs + error messaging for missing prompt
7. Create .grokkit/prompts/go.md example (or embed)

Proposed CLI

# Default: analyze current repo, preview report, confirm before writing analyze.md
grokkit analyze

# To a specific directory
grokkit analyze --dir ./my-old-project

# Write to custom file (or stdout)
grokkit analyze --output project-analysis.md
grokkit analyze --output -          # force stdout

# Fast & silent
grokkit analyze --yes --model grok-4-mini

Flags

Flag,Description
--dir,Repository root to analyze (default: .)
--output,Write report to file (default: analyze.md); use - for stdout
--yes,Skip confirmation and write immediately
"--model, -m",Override model (default from config)

Priority High — excellent didactic tool across any language with minimal friction.