Greg Gauthier
643b904db4
Update the feature description to include educational report details and prompt discovery mechanism. Add automatic prompt loading from project or global config paths, with error handling for missing prompts. Revise acceptance criteria, implementation plan, and add proposed CLI usage and flags. Include default prompt for Go and user-guide updates for custom prompts.
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.
|