gmgauthier/grokkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 23 Wiki Activity
78379aa557
grokkit/todo/queued/analyze-command.md
Greg Gauthier 643b904db4
All checks were successful
CI / Test (push) Successful in 27s
Details
CI / Lint (push) Successful in 17s
Details
CI / Build (push) Successful in 12s
Details
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.
2026-03-28 12:14:33 +00:00

2.6 KiB
Raw Blame History

Feature: grokkit analyze — Deep project investigation & didactic report

Description 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.

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

  • 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 + 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)

Proposed CLI

# 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

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.