docs(analyze): refine grokkit analyze command spec

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.

todo/queued/analyze-command.md

@@ -1,35 +1,64 @@
 # 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.
+`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.
 
-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.
+**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**
-- [ ] Cobra command `analyze` in `cmd/analyze.go`
+- [ ] Command `analyze` in `cmd/analyze.go`
-- [ ] Supports `--dir`, `--output` (stdout / file), `--model`, `--yes` (skip confirmation)
+- [ ] Flags: `--dir`, `--output`, `--yes`, `--model` (no `--prompt`)
-- [ ] Uses existing `internal/linter` for language detection + file discovery
+- [ ] Automatic prompt discovery with the exact two-path order above
-- [ ] Uses `internal/grok` (StreamSilent + structured prompt) for the heavy lifting
+- [ ] Uses `internal/linter` for language detection + file discovery
-- [ ] Transactional: always shows preview of the generated report + `y/N` confirmation before writing to disk (unless `--yes`)
+- [ ] Transactional: preview of generated report + `y/N` confirmation before writing (unless `--yes`)
-- [ ] Full user-guide doc: `docs/user-guide/analyze.md` (usage, safety, best practices, example output)
+- [ ] Ships with a solid default prompt for Go (`docs/` or embedded)
-- [ ] Updates to `docs/user-guide/index.md`, main README, and `docs/index.md`
+- [ ] Full user-guide: `docs/user-guide/analyze.md` (includes how to add prompts for C90/Rexx/Perl/etc.)
-- [ ] Unit tests + integration test that runs on a temp test repo
+- [ ] Updates to `docs/user-guide/index.md`, main README, and top-level docs
-- [ ] Follows architecture: thin cmd layer, structured logging, Git safety, no new heavy deps
+- [ ] Tests (including prompt-not-found case and custom prompt case)
-- [ ] Report sections (enforced by system prompt):
+- [ ] Thin cmd layer, structured logging, Git safety
-  - 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`)
+1. Add command + flags (model after `review.go` / `pr-describe.go`)
-2. File discovery + language batching (reuse `internal/linter`)
+2. Extend or reuse linter for project-wide language detection (pick primary language or handle multi-lang)
-3. Build rich context prompt (project tree + key files + git metadata)
+3. Implement prompt loader (project `.grokkit/prompts/` → `~/.config/grokkit/prompts/`)
-4. Single Grok call (or smart multi-call if project is huge) → clean Markdown
+4. Build rich context + loaded system prompt → Grok call
-5. Diff-style preview + confirmation (even for stdout, show first ~50 lines)
+5. Preview + confirmation → write/print
-6. Write / print report
+6. Docs + error messaging for missing prompt
-7. Docs + tests
+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 — this is the exact “didactic training tool” the project has been missing.
+High — excellent didactic tool across any language with minimal friction.