From b335453912a3ba6d0a1f7f2729f8eddc71edd8d1 Mon Sep 17 00:00:00 2001
From: Maksim Soltan <gonzih@gmail.com>
Date: Wed, 1 Apr 2026 08:38:07 -0700
Subject: [PATCH] fix: add LEARNINGS_SEARCH + LEARNINGS_LOG to /codex skill

The /codex skill runs OpenAI Codex as a second-opinion reviewer but
didn't surface prior project learnings before running or persist new
ones after completing.

In consult mode especially, prior learnings about project quirks and
architecture can significantly improve the quality of the Codex prompt.
In review mode, learnings about recurring issues in this codebase give
Codex useful context about what to focus on.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 codex/SKILL.md      | 63 +++++++++++++++++++++++++++++++++++++++++++++
 codex/SKILL.md.tmpl |  4 +++
 2 files changed, 67 insertions(+)

diff --git a/codex/SKILL.md b/codex/SKILL.md
index 77384bdc5..2da23810e 100644
--- a/codex/SKILL.md
+++ b/codex/SKILL.md
@@ -537,6 +537,44 @@ If `NOT_FOUND`: stop and tell the user:
 
 ---
 
+## Prior Learnings
+
+Search for relevant learnings from previous sessions:
+
+```bash
+_CROSS_PROJ=$(~/.claude/skills/gstack/bin/gstack-config get cross_project_learnings 2>/dev/null || echo "unset")
+echo "CROSS_PROJECT: $_CROSS_PROJ"
+if [ "$_CROSS_PROJ" = "true" ]; then
+  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 --cross-project 2>/dev/null || true
+else
+  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 2>/dev/null || true
+fi
+```
+
+If `CROSS_PROJECT` is `unset` (first time): Use AskUserQuestion:
+
+> gstack can search learnings from your other projects on this machine to find
+> patterns that might apply here. This stays local (no data leaves your machine).
+> Recommended for solo developers. Skip if you work on multiple client codebases
+> where cross-contamination would be a concern.
+
+Options:
+- A) Enable cross-project learnings (recommended)
+- B) Keep learnings project-scoped only
+
+If A: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings true`
+If B: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings false`
+
+Then re-run the search with the appropriate flag.
+
+If learnings are found, incorporate them into your analysis. When a review finding
+matches a past learning, display:
+
+**"Prior learning applied: [key] (confidence N/10, from [date])"**
+
+This makes the compounding visible. The user should see that gstack is getting
+smarter on their codebase over time.
+
 ## Step 1: Detect mode
 
 Parse the user's input to determine which mode to run:
@@ -978,6 +1016,31 @@ If token count is not available, display: `Tokens: unknown`
 
 ---
 
+## Capture Learnings
+
+If you discovered a non-obvious pattern, pitfall, or architectural insight during
+this session, log it for future sessions:
+
+```bash
+~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"codex","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'
+```
+
+**Types:** `pattern` (reusable approach), `pitfall` (what NOT to do), `preference`
+(user stated), `architecture` (structural decision), `tool` (library/framework insight),
+`operational` (project environment/CLI/workflow knowledge).
+
+**Sources:** `observed` (you found this in the code), `user-stated` (user told you),
+`inferred` (AI deduction), `cross-model` (both Claude and Codex agree).
+
+**Confidence:** 1-10. Be honest. An observed pattern you verified in the code is 8-9.
+An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.
+
+**files:** Include the specific file paths this learning references. This enables
+staleness detection: if those files are later deleted, the learning can be flagged.
+
+**Only log genuine discoveries.** Don't log obvious things. Don't log things the user
+already knows. A good test: would this insight save time in a future session? If yes, log it.
+
 ## Important Rules
 
 - **Never modify files.** This skill is read-only. Codex runs in read-only sandbox mode.
diff --git a/codex/SKILL.md.tmpl b/codex/SKILL.md.tmpl
index 86500003c..fc6417a35 100644
--- a/codex/SKILL.md.tmpl
+++ b/codex/SKILL.md.tmpl
@@ -43,6 +43,8 @@ If `NOT_FOUND`: stop and tell the user:
 
 ---
 
+{{LEARNINGS_SEARCH}}
+
 ## Step 1: Detect mode
 
 Parse the user's input to determine which mode to run:
@@ -419,6 +421,8 @@ If token count is not available, display: `Tokens: unknown`
 
 ---
 
+{{LEARNINGS_LOG}}
+
 ## Important Rules
 
 - **Never modify files.** This skill is read-only. Codex runs in read-only sandbox mode.