From 6160ffa8e67b87922fec2aa555c0f81b16870473 Mon Sep 17 00:00:00 2001 From: Greg Gauthier Date: Sat, 28 Mar 2026 11:47:06 +0000 Subject: [PATCH] feat(analyze): add feature spec for grokkit analyze command 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. --- todo/queued/analyze-command.md | 35 ++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 todo/queued/analyze-command.md diff --git a/todo/queued/analyze-command.md b/todo/queued/analyze-command.md new file mode 100644 index 0000000..a803dbf --- /dev/null +++ b/todo/queued/analyze-command.md @@ -0,0 +1,35 @@ +# 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.