grokkit/todo/queued/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**

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

```csv
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.