65 lines
2.6 KiB
Markdown
65 lines
2.6 KiB
Markdown
# 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.
|