grokkit/todo/queued/analyze-command.md

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.