Skip to content

Commit b7a0913

Browse files
author
StackMemory Bot (CLI)
committed
feat(skills): add /update-docs and /recover context maintenance skills
- /update-docs: weekly audit of CLAUDE.md, MEMORY.md, agent_docs/ against git history and codebase drift - /recover: session post-mortem that analyzes traces, finds drift points, and converts them into durable guidance updates - Add auto-activate triggers in global CLAUDE.md - Add Context Maintenance section to project CLAUDE.md with usage guidelines
1 parent 59bb14e commit b7a0913

File tree

3 files changed

+218
-0
lines changed

3 files changed

+218
-0
lines changed

‎.claude/skills/recover.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Recover
2+
3+
Diagnose why a session went off the rails by analyzing traces, then update context docs to prevent recurrence.
4+
5+
## Usage
6+
7+
```
8+
/recover # Analyze current session drift
9+
/recover <session-id> # Analyze a specific conductor session
10+
/recover last # Analyze the most recent conductor run
11+
```
12+
13+
## Instructions
14+
15+
You are a session post-mortem analyst. The user feels the current session (or a past one) went off-target. Your job is to find where context drifted from intent and convert that into durable guidance updates.
16+
17+
### Step 1: Identify the drift
18+
19+
#### For current session drift:
20+
1. Ask the user: "What were you trying to accomplish, and where did it go wrong?"
21+
2. Review the conversation so far — identify the turn where behavior diverged from intent
22+
3. Classify the drift:
23+
- **Wrong scope**: Agent did more/less than asked
24+
- **Wrong approach**: Agent chose a suboptimal strategy
25+
- **Wrong assumptions**: Agent assumed something false about the codebase
26+
- **Missing context**: Agent didn't know something it should have
27+
- **Conflicting guidance**: Two instructions in CLAUDE.md/MEMORY.md contradicted
28+
29+
#### For conductor session analysis:
30+
1. Load trace data:
31+
```bash
32+
stackmemory conductor traces <issue-id>
33+
```
34+
2. If a session-id is given, replay it:
35+
```bash
36+
stackmemory conductor replay <session-id>
37+
```
38+
3. Identify the failure turn — look for:
39+
- Phase transitions that shouldn't have happened (e.g., jumping to "implementing" without "reading")
40+
- Tool calls that indicate confusion (repeated file reads, failed edits)
41+
- Token spikes (agent thrashing)
42+
- Error patterns in the last N turns
43+
44+
### Step 2: Root cause analysis
45+
46+
Map each drift to a root cause category:
47+
48+
| Category | Signal | Fix |
49+
|---|---|---|
50+
| **Missing CLAUDE.md guidance** | Agent didn't follow a project convention | Add the convention to CLAUDE.md |
51+
| **Stale memory** | Agent acted on outdated info from MEMORY.md | Update or remove the memory entry |
52+
| **Missing memory** | Agent lacked context it couldn't derive from code | Add a new memory entry |
53+
| **Ambiguous instruction** | Agent interpreted guidance differently than intended | Rewrite the instruction to be unambiguous |
54+
| **Missing skill** | Agent should have had a specialized workflow | Create a new skill |
55+
| **Wrong task delegation** | Task was AUTOMATE-tier but needed CAREFUL treatment | Update delegation model |
56+
| **Prompt template gap** | Conductor agent prompt didn't include needed context | Update prompt-template.md |
57+
58+
### Step 3: Prescribe fixes
59+
60+
For each root cause, draft the specific change:
61+
62+
```
63+
## Recovery Plan
64+
65+
### 1. {Category}: {Brief description}
66+
**Drift**: {What happened}
67+
**Root cause**: {Why it happened}
68+
**Fix**: {Exact change to make}
69+
**File**: {CLAUDE.md | MEMORY.md | memory/{file}.md | skills/{file}.md | prompt-template.md}
70+
71+
### 2. ...
72+
```
73+
74+
### Step 4: Apply and verify
75+
76+
After user confirms:
77+
78+
1. Apply each fix to the appropriate file
79+
2. For CLAUDE.md changes: verify the instruction is clear by re-reading the section in context
80+
3. For MEMORY.md changes: ensure the index stays under 200 lines
81+
4. For prompt template changes: note that the change takes effect on the next conductor run
82+
5. Commit with: `fix(docs): session recovery — {root causes addressed}`
83+
84+
### Step 5: Optionally resume work
85+
86+
Ask the user: "Context docs updated. Want to retry the original task with the improved guidance?"
87+
88+
If yes, re-read the updated docs and proceed with the original intent.
89+
90+
### Rules
91+
92+
- **Don't blame the model** — if the agent drifted, the context was insufficient. Fix the context.
93+
- **Be specific** — "add better guidance" is not a fix. "Add to CLAUDE.md Commands section: `npm run typecheck` for type-checking (not `npx tsc --noEmit` which OOMs)" is a fix.
94+
- **One fix per root cause** — don't shotgun changes. Each fix should be traceable to a specific drift.
95+
- **Test the fix mentally** — re-read the changed doc and ask "would this have prevented the drift?" If not, the fix is wrong.

‎.claude/skills/update-docs.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Update Docs
2+
3+
Systematic review and update of context markdowns (CLAUDE.md, MEMORY.md, agent_docs/) based on session traces, git history, and codebase drift. Run weekly.
4+
5+
## Usage
6+
7+
```
8+
/update-docs # Full review: CLAUDE.md + MEMORY.md + agent_docs/
9+
/update-docs memory # Only review MEMORY.md entries
10+
/update-docs claude # Only review CLAUDE.md
11+
/update-docs agents # Only review agent_docs/
12+
```
13+
14+
## Instructions
15+
16+
You are a context gardener. Your job is to audit the project's guidance documents and ensure they accurately reflect the current codebase, workflows, and learned patterns. Stale context is worse than no context — it actively misleads future sessions.
17+
18+
### Step 1: Gather evidence
19+
20+
Run these in parallel to build a picture of what's changed since the docs were last updated:
21+
22+
1. **Recent git history** (last 2 weeks):
23+
```bash
24+
git log --oneline --since="2 weeks ago" --no-merges
25+
```
26+
27+
2. **Files changed recently** (detect structural shifts):
28+
```bash
29+
git diff --stat HEAD~50 HEAD | tail -20
30+
```
31+
32+
3. **Current CLAUDE.md** — read it fully
33+
4. **Current MEMORY.md** — read it fully
34+
5. **All memory files** — `ls ~/.claude/projects/*/memory/` and read each
35+
6. **Agent docs index** — `ls agent_docs/` if it exists
36+
7. **Conductor traces** (if available):
37+
```bash
38+
stackmemory conductor trace-stats 2>/dev/null
39+
```
40+
8. **Recent test results** — check if test counts or patterns have shifted:
41+
```bash
42+
node -e "require('child_process').execSync('npx vitest run --reporter=json 2>/dev/null', {timeout:300000, encoding:'utf8'})" 2>/dev/null | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));console.log('Tests:',d.numPassedTests,'passed,',d.numFailedTests,'failed,',d.numTotalTestSuites,'suites')"
43+
```
44+
45+
### Step 2: Audit each document
46+
47+
For each document, evaluate every section against the evidence:
48+
49+
#### CLAUDE.md audit checklist:
50+
- [ ] **Commands section**: Do all listed commands still work? Any new important ones missing?
51+
- [ ] **Project structure**: Does the tree match actual `src/` layout? New directories?
52+
- [ ] **Key files**: Are file paths still correct? Any important new files?
53+
- [ ] **Validation steps**: Still accurate? Test counts roughly right?
54+
- [ ] **Deploy section**: Still accurate? Any new steps?
55+
- [ ] **Conductor section**: Data files, learning loop, template variables all current?
56+
- [ ] **Task delegation model**: Categories still make sense given recent work?
57+
58+
#### MEMORY.md audit checklist:
59+
- [ ] **Each memory entry**: Is it still true? Has the codebase changed underneath it?
60+
- [ ] **Missing knowledge**: Are there patterns from recent commits that should be captured?
61+
- [ ] **Stale entries**: Any memories about removed features, old APIs, or resolved issues?
62+
- [ ] **Duplicates**: Any memories that overlap or contradict each other?
63+
64+
#### Agent docs audit:
65+
- [ ] **Each doc**: Does it reference current APIs, file paths, patterns?
66+
- [ ] **Coverage**: Any major subsystem lacking documentation?
67+
68+
### Step 3: Propose changes
69+
70+
Present findings as a structured report:
71+
72+
```
73+
## Context Audit Report — {date}
74+
75+
### Stale (remove or update)
76+
- MEMORY.md line X: "{entry}" — reason it's stale
77+
- CLAUDE.md section Y: outdated because Z
78+
79+
### Missing (should add)
80+
- New pattern learned: {description} — evidence: {commit/file}
81+
- New gotcha discovered: {description}
82+
83+
### Accurate (no change needed)
84+
- {section}: still valid ✓
85+
```
86+
87+
### Step 4: Apply changes
88+
89+
After presenting the report, ask: "Apply these changes?" If confirmed:
90+
91+
1. **Update MEMORY.md** — edit stale entries, add missing ones, remove obsolete
92+
2. **Update individual memory files** — create/update/delete as needed
93+
3. **Update CLAUDE.md** — fix outdated sections (commands, paths, structure)
94+
4. **Update agent_docs/** — fix stale references
95+
96+
### Rules
97+
98+
- **Never delete memories about rejected integrations** — those prevent re-evaluation
99+
- **Never delete gotchas** — they prevent repeat mistakes
100+
- **Preserve dates** on memory entries so staleness is visible
101+
- **Add dates** to any new entries: `(2026-MM-DD)`
102+
- **Keep MEMORY.md under 200 lines** — it's loaded into every conversation
103+
- **Progressive disclosure**: If a topic needs >5 lines, put it in a dedicated memory file and link from MEMORY.md
104+
- **Don't rewrite CLAUDE.md from scratch** — make surgical updates. The structure is intentional.
105+
- **Commit changes** with message: `chore(docs): weekly context audit — {summary}`

‎CLAUDE.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,24 @@ Quality gates scale with tier — don't over-engineer AUTOMATE tasks, don't unde
213213
- Plan-execute sessions (low interaction, high edits) are most efficient
214214
- Avoid exploratory marathons with topic-switching — burns 30-40% extra tokens
215215

216+
## Context Maintenance
217+
218+
**`/update-docs`** — Run weekly or when context feels stale:
219+
- Audits CLAUDE.md, MEMORY.md, agent_docs/ against git history and codebase
220+
- Detects stale entries, missing patterns, outdated paths
221+
- Trigger: start of week, after major refactors, or when sessions feel slow/confused
222+
223+
**`/recover`** — Run when a session goes off the rails:
224+
- Analyzes traces to find where context drifted from intent
225+
- Maps drift to specific doc fixes (missing guidance, stale memory, ambiguous instruction)
226+
- Trigger: user says "this is wrong", "not what I wanted", "off the rails", repeated corrections
227+
228+
**When to use which:**
229+
- Session producing wrong results → `/recover` (diagnose + fix now)
230+
- Routine maintenance, nothing broken → `/update-docs` (proactive gardening)
231+
- After publishing a new version → `/update-docs` (catch version/path drift)
232+
- After conductor failures → `/recover last` (learn from agent traces)
233+
216234
## Workflow
217235

218236
- Check .env for API keys before asking

0 commit comments

Comments
 (0)