From 32fd4dbb7e983f2eabc91e1ff3ff4cf3253020d6 Mon Sep 17 00:00:00 2001 From: Srikanth Rao M Date: Sun, 24 May 2026 16:25:51 +0530 Subject: [PATCH] =?UTF-8?q?docs:=20plan=20audit=20=E2=80=94=20update=20sta?= =?UTF-8?q?le=20statuses,=20delete=20shipped/superseded=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - dispatch-learnings-curated-design.md: status → Shipped v4.11.0 (PRs #297, #299, #301) - effective-pattern-normalization.md: status → Feature 1 Complete / Feature 2 Deferred - gamification-shareable-badges.md: status → Phase 1+2 shipped (v4.2.0, v4.3.0), Phases 3-4 future - CURRENT_SPRINT.md: cleared (llama.cpp sprint shipped in v4.9.0) - Deleted: session-writeup-dispatch-ideation.md (superseded + underlying feature shipped) - Deleted: handover-llamacpp-provider.md (stale engineering handover, feature shipped) Co-Authored-By: Claude Sonnet 4.6 Entire-Checkpoint: 4c69ac669934 --- docs/implementation/CURRENT_SPRINT.md | 31 +--- .../handover-llamacpp-provider.md | 162 ----------------- ...026-03-08-gamification-shareable-badges.md | 2 +- ...6-03-09-effective-pattern-normalization.md | 2 +- ...05-09-session-writeup-dispatch-ideation.md | 165 ------------------ ...05-10-dispatch-learnings-curated-design.md | 2 +- 6 files changed, 5 insertions(+), 359 deletions(-) delete mode 100644 docs/implementation/handover-llamacpp-provider.md delete mode 100644 docs/plans/2026-05-09-session-writeup-dispatch-ideation.md diff --git a/docs/implementation/CURRENT_SPRINT.md b/docs/implementation/CURRENT_SPRINT.md index a6ad839c..56155530 100644 --- a/docs/implementation/CURRENT_SPRINT.md +++ b/docs/implementation/CURRENT_SPRINT.md @@ -1,30 +1,3 @@ -# Current Sprint: llama.cpp Provider Integration +# Current Sprint -**Started:** 2026-04-03 -**Goal:** Add llama.cpp as a local LLM provider so users can run fully-local, free session analysis via llama-server + GGUF models (Gemma 4 flagship). - -**GitHub Issue:** #267 — https://github.com/melagiri/code-insights/issues/267 -**Branch:** `claude/plan-gemma-ollama-integration-03V9H` - ---- - -## In Progress - -- [ ] Phase 1: Extend LLMProvider type union -- engineer -- S -- claude/plan-gemma-ollama-integration-03V9H -- [ ] Phase 2: Provider metadata + pricing constants -- engineer -- S -- [ ] Phase 3: Server provider implementation (llamacpp.ts NEW) -- engineer -- M -- [ ] Phase 4: CLI provider runner -- engineer -- M -- [ ] Phase 5: Config wizard -- engineer -- S -- [ ] Phase 6: Server routes (VALID_PROVIDERS + discovery endpoint) -- engineer -- S -- [ ] Phase 7: Dashboard UI (Settings, cost display, dropdown) -- engineer -- L -- [ ] Phase 8: LLM Expert required fixes (token limits, temperature, retry) -- engineer -- M - -## Done - -## Blocked - -## Next Up - -- [ ] Triple-layer review once PR is created -- TA + outsider -- S -- [ ] Follow-up issue: simplified prompts for 12B quantized models -- PM -- S -- [ ] Follow-up issue: SettingsPage duplicated provider types -- PM -- S +No active sprint. diff --git a/docs/implementation/handover-llamacpp-provider.md b/docs/implementation/handover-llamacpp-provider.md deleted file mode 100644 index 33f516aa..00000000 --- a/docs/implementation/handover-llamacpp-provider.md +++ /dev/null @@ -1,162 +0,0 @@ -# Engineer Handover: llama.cpp Provider Integration - -**GitHub Issue:** #267 — https://github.com/melagiri/code-insights/issues/267 -**Branch:** `claude/plan-gemma-ollama-integration-03V9H` -**Date:** 2026-04-03 -**Size:** XL (14 files, 3 new, cross-cutting across all three packages) - ---- - -## What You Are Building - -A new LLM provider called `llamacpp` that lets users run Code Insights' AI-powered session analysis against a locally running `llama-server` process (from the llama.cpp project). It uses the OpenAI-compatible HTTP API that llama-server exposes. No API key is required. The flagship local model is Gemma 4 12B (Q4_K_M GGUF). - -This follows the same provider abstraction pattern as Ollama. Anywhere Ollama gets special treatment (free tier, no API key, local provider checks), llamacpp must receive identical treatment. - ---- - -## File List and Changes - -### cli/src/types.ts -Extend the `LLMProvider` union type: -``` -'llamacpp' -``` - -### cli/src/constants/llm-providers.ts -- Add a llamacpp provider entry (display name, no API key required, base URL configurable) -- Add Gemma 4 model entries under the Ollama and Gemini sections - -### cli/src/analysis/provider-runner.ts -- Add `makeLlamaCppChat` function (OpenAI-compatible HTTP call to llama-server) -- Skip the API key requirement check when provider is `llamacpp` -- **Tests required** (see Testing Requirements below) - -### cli/src/commands/config.ts -- Add llamacpp to the interactive LLM provider wizard -- Prompt for base URL; default must be `http://localhost:8080` -- Do NOT prompt for an API key for llamacpp - -### server/src/llm/providers/llamacpp.ts (NEW FILE) -- OpenAI-compatible HTTP client targeting llama-server -- Model discovery via `GET /v1/models` on the configured base URL -- Handle connection errors gracefully (llama-server may not be running) - -### server/src/llm/client.ts -- Register llamacpp in the provider factory switch/map -- Include llamacpp in `isLLMConfigured` logic (it is configured if a base URL is set; no API key required) - -### server/src/llm/analysis.ts -- Make `MAX_INPUT_TOKENS` model-aware — **this is a blocking requirement** -- For llamacpp: cap at **24,576 tokens** (24K) -- All existing hosted-model defaults must remain unchanged - -### server/src/llm/analysis-pricing.ts -- Add `llamacpp: 0.00` - -### server/src/routes/config.ts -- Add `'llamacpp'` to `VALID_PROVIDERS` -- Add a model discovery endpoint that proxies to `llama-server /v1/models` - -### dashboard/src/lib/types.ts -- Add `'llamacpp'` to the provider union type (mirror of cli/src/types.ts) - -### dashboard/src/lib/api.ts -- Add `fetchLlamaCppModels()` — calls the discovery endpoint added to server/src/routes/config.ts - -### dashboard/src/lib/cost-utils.ts -- Add llamacpp to any free-provider check (alongside Ollama) - -### dashboard/src/pages/SettingsPage.tsx -- Add a llamacpp provider section containing: - - Model name text input (free-form, since models vary by user setup) - - Base URL text input (default `http://localhost:8080`) - - Model discovery button that calls `fetchLlamaCppModels` and populates the model input -- Note: this page has duplicated provider types — do not fix now, open a follow-up issue and leave a `// TODO` comment - -### dashboard/src/components/sessions/AnalysisCostLine.tsx -- Handle free provider display for llamacpp (show $0.00 or "local" label, same as Ollama) - -### dashboard/src/components/analysis/AnalyzeDropdown.tsx -- Include llamacpp in the local provider check (controls any "no API key needed" UI hints) - ---- - -## Critical Fixes from Expert Reviews - -These are not optional. The PR will not be approved without them. - -### 1. MAX_INPUT_TOKENS must be model-aware (BLOCKING — LLM Expert) - -File: `server/src/llm/analysis.ts` - -The current global token limit is sized for large hosted models. Sending that many tokens to a 12B quantized model running in llama-server will cause failures or severely degraded output. - -**Required:** convert `MAX_INPUT_TOKENS` from a constant to a function of provider + model. The llamacpp default is **24,576 (24K)**. All existing provider defaults must be unchanged. - -### 2. Temperature 0.3 for llamacpp (LLM Expert) - -File: `server/src/llm/providers/llamacpp.ts` - -Global default temperature (0.7) produces inconsistent structured JSON output from small quantized models. Use **0.3** when provider is llamacpp. - -### 3. Single retry on JSON parse failure for small-model providers (LLM Expert) - -File: `server/src/llm/providers/llamacpp.ts` or `server/src/llm/analysis.ts` - -Implement exactly **one** retry when a structural JSON parse failure occurs on a llamacpp call. Do not retry on every error type — only on parse failure. - -### 4. Audit all `=== 'ollama'` checks (Technical Architect) - -Before opening the PR, grep the entire codebase for `=== 'ollama'` (and `!== 'ollama'`, `includes('ollama')`, etc.). Every such check that controls free-tier, local, or no-API-key behavior must be updated to include `'llamacpp'`. This must be a complete audit — no half-updated provider checks. - -```bash -grep -r "ollama" cli/src server/src dashboard/src --include="*.ts" --include="*.tsx" -l -``` - ---- - -## Testing Requirements - -Vitest unit tests are required for `cli/src/analysis/provider-runner.ts`. Cover: - -1. **Happy path:** `makeLlamaCppChat` sends a well-formed request to the configured base URL and returns parsed content -2. **API key skip:** no API key error is thrown when provider is `llamacpp` -3. **Base URL configuration:** the function uses the configured base URL, not a hardcoded default - -Test file: `cli/src/analysis/__tests__/provider-runner.test.ts` (or alongside the existing test structure — check `docs/QA.md` for conventions). - ---- - -## Pre-PR Gate - -Before creating the PR, from the repo root: - -```bash -pnpm build -``` - -Zero errors required. If anything fails, fix it before opening the PR. - ---- - -## Tech Debt to Track Before Closing #267 - -Open a separate issue (can be done while the PR is in review) for: - -1. **Duplicated provider types in SettingsPage.tsx** — the page re-declares types that live in `dashboard/src/lib/types.ts` -2. **Simplified prompts for 12B quantized models** — the full facet extraction prompt is optimized for large models; a stripped-down version for small local models would improve output quality (LLM Expert recommendation, not required for this PR) - ---- - -## Definition of Done - -- [ ] `pnpm build` passes from repo root with zero errors -- [ ] All 14 files modified/created per the file list above -- [ ] All four expert-required fixes implemented -- [ ] `=== 'ollama'` audit complete, llamacpp co-located in every check -- [ ] Vitest tests for `makeLlamaCppChat` written and passing -- [ ] PR created against `claude/plan-gemma-ollama-integration-03V9H` -- [ ] PR body references issue #267 -- [ ] Follow-up tech debt issues opened -- [ ] Triple-layer review initiated (TA insider + outsider + synthesis) diff --git a/docs/plans/2026-03-08-gamification-shareable-badges.md b/docs/plans/2026-03-08-gamification-shareable-badges.md index c2eedba6..9865919e 100644 --- a/docs/plans/2026-03-08-gamification-shareable-badges.md +++ b/docs/plans/2026-03-08-gamification-shareable-badges.md @@ -1,7 +1,7 @@ # Gamification & Shareable Badges — Design Plan **Date:** 2026-03-08 -**Status:** Future feature (design phase — not yet approved for implementation) +**Status:** Phase 1 (Working Style Card) shipped v4.2.0 · Phase 2 (AI Fluency Score Card) shipped v4.3.0 · Phase 3 (Stats Card) and Phase 4 (Milestone Cards) future **Prerequisite:** Patterns Page Refinement (2026-03-08-patterns-page-refinement.md) **Depends on:** Working Style hero card, tagline, streak computation diff --git a/docs/plans/2026-03-09-effective-pattern-normalization.md b/docs/plans/2026-03-09-effective-pattern-normalization.md index 134effe3..fd9a09d7 100644 --- a/docs/plans/2026-03-09-effective-pattern-normalization.md +++ b/docs/plans/2026-03-09-effective-pattern-normalization.md @@ -1,6 +1,6 @@ # Reflect Feature Enhancement — Design Plan -> **Status:** In Progress — Gathering Requirements +> **Status:** Feature 1 Complete (PRs #125, #127, #129, #132, #136, #138) · Feature 2 (Progress Tracking) Deferred > **Date:** 2026-03-09 > **Scope:** Server (prompts, aggregation, normalization), Dashboard (PatternsPage, Insights), CLI (types) > **Features:** Pattern Normalization + Confidence Filtering + Outdated Format Detection + Progress Tracking (TBD) diff --git a/docs/plans/2026-05-09-session-writeup-dispatch-ideation.md b/docs/plans/2026-05-09-session-writeup-dispatch-ideation.md deleted file mode 100644 index eda48962..00000000 --- a/docs/plans/2026-05-09-session-writeup-dispatch-ideation.md +++ /dev/null @@ -1,165 +0,0 @@ -# Session Writeup / Dispatch — Feature Ideation - -> **Status:** Superseded — session-scoped approach abandoned -> **Date:** 2026-05-09 -> **Superseded by:** `2026-05-10-dispatch-learnings-curated-design.md` -> **Triggered by:** Entire.io "Dispatch" feature observation - ---- - -## The Spark - -Entire.io shipped a "Dispatch" feature: scope a repo + time window, choose a voice (Neutral / Marvin / Custom), get a newsletter-style narrative of what shipped that week — sourced from git commits. - -The observation: Code Insights can tell a *richer* story. Entire.io reads commits → produces a **what**. Code Insights reads AI sessions → can produce a **why** — the decisions made, the friction encountered, the collaboration patterns. That's structurally better and only Code Insights can tell it. - ---- - -## Founder's Vision (2026-05-09) - -A **"Dispatch" button on the session detail page** in the dashboard that generates an engineering blog post from that session's conversation and analysis data — ready to post on dev.to, Hashnode, or a personal engineering blog. - -Key intent: -- Session-scoped (one session → one story) -- Entry point: button on session detail in dashboard UI -- Output: blog post, not a data dump -- Released in phases - ---- - -## Strategic Critique (devtools-cofounder) - -### The Granularity Problem - -Single-session → publishable blog post has a structural mismatch. The session taxonomy proves it: - -- `bug_hunt` session → reads like a Stack Overflow answer, not a blog post -- `feature_build` → missing "why" context from earlier exploration sessions -- `learning` → potentially fits, but rare - -Most compelling engineering stories span multiple sessions. The interesting narrative is "how I shipped X" — and X almost never lives in one session. - -### Who Is This For? - -~5% of developers blog actively. The real question: does a 1-click generate button turn non-bloggers into bloggers? Probably not — Hashnode/dev.to are already saturated with low-effort AI posts. Adding another generation spigot doesn't differentiate Code Insights. - -**The 80% use case is personal retrospective, not publishing.** The feature should acknowledge this. - -### Quality Risk - -One click + session transcript + LLM = potential exposure of: -- Internal file paths and service names -- Half-formed reasoning from mid-session AI mistakes -- Technically incorrect conclusions the AI made before correcting itself - -Published under the developer's name, this is a brand risk *for them*. - -### Verdict - -Reframe the feature: - -- **Phase 1:** "Session Writeup" — a generated retrospective *for the developer*, presented as markdown the user can adapt for blogging. Sets honest expectations. -- **Phase 2:** Multi-session bundling — pick 2–5 related sessions, generate a real narrative blog post. This is the publishable artifact. This belongs on the Export page, not the session detail page. - -**Label matters:** "Write up this session" or "Generate writeup" sets the right expectation. "Dispatch" sounds like broadcasting; "Generate blog post" overpromises on Phase 1 quality. - ---- - -## LLM Architecture Critique (llm-expert) - -### Context Selection - -Skip the raw transcript. Use structured extractions already in SQLite: -- Session summary + character -- All facets: friction (with attribution + evidence), effective patterns (with driver) -- All insights: decisions, learnings, techniques (with reasoning + evidence) - -Estimated input: ~3–5K tokens — high signal, low cost. - -**What's lost without the transcript:** The texture of the conversation — failed attempts, the moment something clicked, the exact back-and-forth of a breakthrough. **Mitigation:** The `evidence` field on each insight and facet is a raw quote anchored to the conversation. If evidence fields are well-populated, most texture is recoverable without the full transcript. - -For sessions over 200 messages, if transcript access is needed: extract the first + last 10 messages plus any message flagged as a decision/learning anchor. Never sample randomly. - -### Pipeline: Two Steps, Not One - -| Step | Call | Temperature | Purpose | -|------|------|-------------|---------| -| 1 | Generate outline: section titles + one-sentence descriptions + story arc (problem → attempt → turning point → resolution) | 0.2 | Forces narrative structure, prevents listicle default | -| 2 | Expand each section | 0.7 | Voice, texture, readable prose | - -Thread session ID across both calls for prompt cache key. - -### Quality Gating (Gate Hard) - -| Session Character | Eligibility | -|-------------------|-------------| -| `feature_build` | ✅ Eligible | -| `bug_hunt` | ✅ Eligible | -| `exploration` | ✅ Eligible | -| `refactor` | ⚠ Soft gate — require ≥3 decisions extracted, confidence ≥ 0.7 avg | -| `deep_focus` | ⚠ Soft gate — same threshold | -| `learning` | ❌ Block | -| `quick_task` | ❌ Block | - -Additional minimum: session duration ≥ 20 minutes. Surface a clear message if session doesn't pass ("This session is too short for a meaningful writeup — try a feature build or bug hunt session"). - -### Output Format - -- Frontmatter: title, 3–5 tags (auto-generated), 2-sentence tldr, estimated read time -- Target length: **800–1200 words** regardless of session length (synthesize depth, don't pad or compress linearly) -- Format: Markdown, ready to paste into dev.to / Hashnode / Ghost - -### Prompt Guardrails - -Ban these words in system prompt: "leveraged", "utilized", "seamlessly", "delve", "straightforward". - -Persona instruction: *"You write like an engineer who built this and wants to share something genuinely useful with other engineers. You are not writing documentation."* - -Include a negative example inline: show what the output should NOT look like (a bullet summary of what happened — the thing every AI defaults to). - -### Model - -**Sonnet at temperature 0.7** for expansion. Opus is not justified — this is narrative generation, not reasoning. Two-step Sonnet matches single-shot Opus quality at ~1/5 the cost. Temperature 0.2 for frontmatter (deterministic metadata). - ---- - -## Phased Plan (Synthesized) - -### Phase 1 — "Session Writeup" (Personal Retrospective) - -**Entry point:** Button on session detail page in dashboard — "Write up this session" -**Output:** Markdown retrospective — what happened, why decisions were made, what was learned -**Framing:** For the developer themselves. Copy-to-clipboard. No publish infrastructure. -**Quality gate:** Block `quick_task` and `learning`; require ≥ 20 min duration -**LLM:** Sonnet, two-step pipeline, structured extractions only (no raw transcript) -**Privacy:** Same 3-layer scrubbing as `.code-insights.md` — pre-LLM, prompt instruction, post-LLM -**No:** Auto-publish, platform integrations, sharing infrastructure - -### Phase 2 — Multi-Session Blog Post (Publishable) - -**Entry point:** Export page (where users think "package this for elsewhere") -**Scope:** Select 2–5 related sessions (by branch, by date range, or manually) -**Output:** Full engineering blog post with frontmatter, narrative arc, 800–1200 words -**Framing:** Ready to publish. This is the "Dispatch" vision. -**Dependency:** Phase 1 usage data should justify Phase 2 before building - ---- - -## Open Questions (Unresolved — Founder to Decide) - -1. **What's the right label for Phase 1?** "Write up", "Session Writeup", "Generate Writeup"? -2. **Should Phase 1 output be stored in SQLite?** Or generated on demand each time? -3. **Does `.code-insights.md` Phase 1 need to ship before this, or can they be parallel?** -4. **Is the quality gate message shown inline on the session detail page** (disabled button with tooltip) or only after clicking? -5. **Phase 2 entry point:** Is the Export page the right home, or a dedicated "Create Post" flow? - ---- - -## Relationship to Other Features - -| Feature | Relationship | -|---------|-------------| -| `code-insights attach` (`.code-insights.md`) | Prerequisite for Phase 2 multi-session post — shares decision/pattern aggregation logic | -| `code-insights reflect` | Parallel feature — Reflect is for self, Writeup/Dispatch is shareable | -| Export page | Phase 2 lives here; Phase 1 lives on session detail page | -| Entire.io Dispatch | Inspiration only. Don't position against — position against the blank page. | diff --git a/docs/plans/2026-05-10-dispatch-learnings-curated-design.md b/docs/plans/2026-05-10-dispatch-learnings-curated-design.md index 80cb0e84..4ad03358 100644 --- a/docs/plans/2026-05-10-dispatch-learnings-curated-design.md +++ b/docs/plans/2026-05-10-dispatch-learnings-curated-design.md @@ -1,6 +1,6 @@ # Dispatch — Learnings-Curated Blog Post Generator -> **Status:** Design — Ready for implementation planning +> **Status:** Shipped — v4.11.0 (PRs #297, #299, #301) > **Date:** 2026-05-10 > **Supersedes:** `2026-05-09-session-writeup-dispatch-ideation.md` (session-scoped approach abandoned) > **Dependencies:** None — uses existing `insights` table and `/insights` dashboard page