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`
-- [ ] 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
+- [ ] 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 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
+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)
 
-**Priority**  
-High — this is the exact “didactic training tool” the project has been missing.
+
+**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.