Greg Gauthier
6160ffa8e6
Queues a new Markdown spec in todo/queued for the `grokkit analyze` command, including description, acceptance criteria, implementation plan, and priority. This feature enables deep project analysis and generates educational Markdown reports on tech stack, functions, and more.
36 lines
2.0 KiB
Markdown
36 lines
2.0 KiB
Markdown
# Feature: grokkit analyze — Deep project investigation & didactic report
|
|
|
|
**Description**
|
|
New command `grokkit analyze` that takes a repository root (default: `.`), performs a full static + semantic analysis, and outputs a single, readable Markdown report.
|
|
|
|
The report is educational: it explains the tech stack, how every public function/method works, why it exists, module inter-relationships, and (when relevant) object ↔ DB schema mappings.
|
|
|
|
**Acceptance Criteria**
|
|
- [ ] Cobra command `analyze` in `cmd/analyze.go`
|
|
- [ ] Supports `--dir`, `--output` (stdout / file), `--model`, `--yes` (skip confirmation)
|
|
- [ ] Uses existing `internal/linter` for language detection + file discovery
|
|
- [ ] Uses `internal/grok` (StreamSilent + structured prompt) for the heavy lifting
|
|
- [ ] Transactional: always shows preview of the generated report + `y/N` confirmation before writing to disk (unless `--yes`)
|
|
- [ ] Full user-guide doc: `docs/user-guide/analyze.md` (usage, safety, best practices, example output)
|
|
- [ ] Updates to `docs/user-guide/index.md`, main README, and `docs/index.md`
|
|
- [ ] Unit tests + integration test that runs on a temp test repo
|
|
- [ ] Follows architecture: thin cmd layer, structured logging, Git safety, no new heavy deps
|
|
- [ ] Report sections (enforced by system prompt):
|
|
- Tech Stack & Project Layout
|
|
- Module / Package Overview + inter-relationships
|
|
- Function/Method Reference (how it works + why it was included)
|
|
- Object ↔ DB Schema Mappings (if applicable)
|
|
- Suggested Learning Path / Gotchas
|
|
|
|
**Implementation Plan**
|
|
1. Add command skeleton + flags (model after `review.go` + `pr-describe.go`)
|
|
2. File discovery + language batching (reuse `internal/linter`)
|
|
3. Build rich context prompt (project tree + key files + git metadata)
|
|
4. Single Grok call (or smart multi-call if project is huge) → clean Markdown
|
|
5. Diff-style preview + confirmation (even for stdout, show first ~50 lines)
|
|
6. Write / print report
|
|
7. Docs + tests
|
|
|
|
**Priority**
|
|
High — this is the exact “didactic training tool” the project has been missing.
|