memory-md-management

# Memory.md Management

Provides comprehensive project memory file management capabilities including auditing, quality assessment, and targeted improvements. This skill ensures the coding agent has optimal project context by maintaining high-quality documentation files such as `CLAUDE.md`.

## Overview

Project memory files such as `CLAUDE.md` are the primary mechanism for providing project-specific context to coding agent sessions. This skill manages their complete lifecycle: discovery, quality assessment, reporting, and improvement. It follows a 5-phase workflow that ensures documentation is current, actionable, and concise.

The skill evaluates CLAUDE.md files against standardized quality criteria across 6 dimensions: Commands/Workflows, Architecture Clarity, Non-Obvious Patterns, Conciseness, Currency, and Actionability. Each file receives a score (0-100) and letter grade (A-F) with specific improvement recommendations.

## When to Use

Use this skill when:

- User explicitly asks to "check", "audit", "update", "improve", "fix", or "maintain" CLAUDE.md
- User mentions "CLAUDE.md quality", "documentation review", or "project memory optimization"
- A project memory file needs to be created from scratch for a new project
- User asks about improving Claude's understanding of the codebase
- Documentation has become stale or outdated
- Starting work on a new codebase and need to understand existing documentation
- User presses `#` during a session to incorporate learnings into a memory file

**Trigger phrases:** "audit CLAUDE.md", "check documentation quality", "improve project context", "review CLAUDE.md", "validate documentation"

## Instructions

### Phase 1: Discovery

Find all CLAUDE.md files in the repository:

```bash
find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50
```

**File Types & Locations:**

| Type | Location | Purpose |
|------|----------|---------|
| Project root | `./CLAUDE.md` | Primary project context (checked into git, shared with team) |
| Local overrides | `./.claude.local.md` | Personal/local settings (gitignored, not shared) |
| Global defaults | `~/.claude/CLAUDE.md` | User-wide defaults across all projects |
| Package-specific | `./packages/*/CLAUDE.md` | Module-level context in monorepos |
| Subdirectory | Any nested location | Feature/domain-specific context |

### Phase 2: Quality Assessment

For each CLAUDE.md file, read [references/quality-criteria.md](references/quality-criteria.md) and evaluate against these criteria:

| Criterion | Weight | What to Check |
|-----------|--------|---------------|
| Commands/workflows | 20 pts | Are build/test/deploy commands present and working? |
| Architecture clarity | 20 pts | Can Claude understand the codebase structure? |
| Non-obvious patterns | 15 pts | Are gotchas and quirks documented? |
| Conciseness | 15 pts | Is content dense without filler? |
| Currency | 15 pts | Does it reflect current codebase state? |
| Actionability | 15 pts | Are instructions executable and copy-paste ready? |

**Quality Scores:** A (90-100), B (70-89), C (50-69), D (30-49), F (0-29)

### Phase 3: Quality Report Output

**CRITICAL: Always output the quality report BEFORE making any updates.**

Format:
```markdown
## CLAUDE.md Quality Report

### Summary
- Files found: X
- Average score: X/100
- Files needing update: X

### File-by-File Assessment
#### 1. ./CLAUDE.md (Project Root)
**Score: XX/100 (Grade: X)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | X/20 | ... |
| Architecture clarity | X/20 | ... |
| Non-obvious patterns | X/15 | ... |
| Conciseness | X/15 | ... |
| Currency | X/15 | ... |
| Actionability | X/15 | ... |

**Issues:**
- [List specific problems]

**Recommended additions:**
- [List what should be added]
```

### Phase 4: Targeted Updates

After report output, ask user for confirmation before updating.

**Read [references/update-guidelines.md](references/update-guidelines.md) for detailed update principles.**

Key principles:
1. **Propose targeted additions only** - commands, gotchas, patterns, configs
2. **Keep it minimal** - avoid obvious info, generic advice, one-off fixes
3. **Show diffs** - file, change (diff format), explanation

Diff format:
```markdown
### Update: ./CLAUDE.md
**Why:** [Brief explanation of why this helps]

```diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev
+ ```
```
```

### Phase 5: Apply Updates

After user approval, use Edit tool to apply changes. Preserve existing content structure.

## Examples

### Example 1: Quality Assessment

**User request:** "Check if my CLAUDE.md is good"

**Response:**
~~~markdown
## CLAUDE.md Quality Report

### Summary
- Files found: 1
- Average score: 65/100
- Files needing update: 1

### File-by-File Assessment

#### 1. ./CLAUDE.md
**Score: 65/100 (Grade: C)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | 10/20 | Only npm install documented |
| Architecture clarity | 15/20 | Basic tree, missing module relationships |
| Non-obvious patterns | 5/15 | No gotchas documented |
| Conciseness | 15/15 | Concise and dense |
| Currency | 10/15 | Some outdated paths |
| Actionability | 10/15 | Some vague instructions |

**Issues:**
- Missing test command
- Missing build command
- No documentation of auth flow complexity
- References to old src/structure

**Recommended additions:**
- Add Commands section with test/build
- Document auth module gotcha
- Update architecture paths
```

### Example 2: Creating from Scratch

**User request:** "Create a CLAUDE.md for this React project"

**Response:**
```markdown
I'll create a CLAUDE.md for your React project. Let me first analyze the codebase structure.

[Scans package.json, src/, and key config files]

## CLAUDE.md Quality Report

### Summary
- Files found: 0
- Creating new CLAUDE.md at project root

### Proposed CLAUDE.md Content:

# Project Name

## Commands

| Command | Description |
|---