references/quality-criteria.md
# Memory File Quality Criteria
## Scoring Rubric
### 1. Commands/Workflows (20 points)
**20 points**: All essential commands documented with context
- Build, test, lint, deploy commands present
- Development workflow clear
- Common operations documented
**15 points**: Most commands present, some missing context
**10 points**: Basic commands only, no workflow
**5 points**: Few commands, many missing
**0 points**: No commands documented
### 2. Architecture Clarity (20 points)
**20 points**: Clear codebase map
- Key directories explained
- Module relationships documented
- Entry points identified
- Data flow described where relevant
**15 points**: Good structure overview, minor gaps
**10 points**: Basic directory listing only
**5 points**: Vague or incomplete
**0 points**: No architecture info
### 3. Non-Obvious Patterns (15 points)
**15 points**: Gotchas and quirks captured
- Known issues documented
- Workarounds explained
- Edge cases noted
- "Why we do it this way" for unusual patterns
**10 points**: Some patterns documented
**5 points**: Minimal pattern documentation
**0 points**: No patterns or gotchas
### 4. Conciseness (15 points)
**15 points**: Dense, valuable content
- No filler or obvious info
- Each line adds value
- No redundancy with code comments
**10 points**: Mostly concise, some padding
**5 points**: Verbose in places
**0 points**: Mostly filler or restates obvious code
### 5. Currency (15 points)
**15 points**: Reflects current codebase
- Commands work as documented
- File references accurate
- Tech stack current
**10 points**: Mostly current, minor staleness
**5 points**: Several outdated references
**0 points**: Severely outdated
### 6. Actionability (15 points)
**15 points**: Instructions are executable
- Commands can be copy-pasted
- Steps are concrete
- Paths are real
**10 points**: Mostly actionable
**5 points**: Some vague instructions
**0 points**: Vague or theoretical
## Assessment Process
1. Read the memory file completely
2. Cross-reference with actual codebase:
- Run documented commands (mentally or actually)
- Check if referenced files exist
- Verify architecture descriptions
3. Score each criterion
4. Calculate total and assign grade
5. List specific issues found
6. Propose concrete improvements
## Red Flags
- Commands that would fail (wrong paths, missing deps)
- References to deleted files/folders
- Outdated tech versions
- Copy-paste from templates without customization
- Generic advice not specific to the project
- "TODO" items never completed
- Duplicate info across multiple memory files
references/update-guidelines.md
# Memory File Update Guidelines
## Core Principle
Only add information that will genuinely help future Claude sessions. The context window is precious - every line must earn its place.
## What TO Add
### 1. Commands/Workflows Discovered
```markdown
## Build
`npm run build:prod` - Full production build with optimization
`npm run build:dev` - Fast dev build (no minification)
```
**Why:** Saves future sessions from discovering these again.
### 2. Gotchas and Non-Obvious Patterns
```markdown
## Gotchas
- Tests must run sequentially (`--runInBand`) due to shared DB state
- `yarn.lock` is authoritative; delete `node_modules` if deps mismatch
```
**Why:** Prevents repeating debugging sessions.
### 3. Package Relationships
```markdown
## Dependencies
The `auth` module depends on `crypto` being initialized first.
Import order matters in `src/bootstrap.ts`.
```
**Why:** Architecture knowledge that isn't obvious from code.
### 4. Testing Approaches That Worked
```markdown
## Testing
For API endpoints: Use `supertest` with the test helper in `tests/setup.ts`
Mocking: Factory functions in `tests/factories/` (not inline mocks)
```
**Why:** Establishes patterns that work.
### 5. Configuration Quirks
```markdown
## Config
- `NEXT_PUBLIC_*` vars must be set at build time, not runtime
- Redis connection requires `?family=0` suffix for IPv6
```
**Why:** Environment-specific knowledge.
## What NOT to Add
### 1. Obvious Code Info
**Bad:**
```markdown
The `UserService` class handles user operations.
```
The class name already tells us this.
### 2. Generic Best Practices
**Bad:**
```markdown
Always write tests for new features.
Use meaningful variable names.
```
This is universal advice, not project-specific.
### 3. One-Off Fixes
**Bad:**
```markdown
We fixed a bug in commit abc123 where the login button didn't work.
```
Won't recur; clutters the file.
### 4. Verbose Explanations
**Bad:**
```markdown
The authentication system uses JWT tokens. JWT (JSON Web Tokens) are
an open standard (RFC 7519) that defines a compact and self-contained
way for securely transmitting information between parties as a JSON
object. In our implementation, we use the HS256 algorithm which...
```
**Good:**
```markdown
Auth: JWT with HS256, tokens in `Authorization: Bearer <token>` header.
```
## Diff Format for Updates
For each suggested change:
### 1. Identify the File
```markdown
File: ./CLAUDE.md
Section: Commands (new section after ## Architecture)
```
### 2. Show the Change
```diff
## Architecture
...
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Dev server with HMR |
+| `npm run build` | Production build |
+| `npm test` | Run test suite |
```
### 3. Explain Why
```markdown
> **Why this helps:** The build commands weren't documented, causing
> confusion about how to run the project. This saves future sessions
> from needing to inspect `package.json`.
```
## Validation Checklist
Before finalizing an update, verify:
- [ ] Each addition is project-specific
- [ ] No generic advice or obvious info
- [ ] Commands are tested and work
- [ ] File paths are accurate
- [ ] Would a new Claude session find this helpful?
- [ ] Is this the most concise way to express the info?
SKILL.md
---
name: memory-md-management
description: Provides comprehensive memory file management capabilities including auditing, quality assessment, and targeted improvements for files such as CLAUDE.md. Use when user asks to check, audit, update, improve, fix, maintain, or validate project memory files. Also triggers for "project memory optimization", "CLAUDE.md quality check", "documentation review", or when a project memory file needs to be created from scratch. This skill scans memory files, evaluates quality against standardized criteria, outputs detailed quality reports with scores and recommendations, then makes targeted updates with user approval.
allowed-tools: Read, Glob, Grep, Bash, Edit
---
# 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 |
|---------|-------------|
| `npm install` | Install dependencies |
| `npm run dev` | Start dev server (Vite on port 5173) |
| `npm run build` | Production build |
| `npm run test` | Run Vitest tests |
| `npm run lint` | ESLint check |
## Architecture
```
src/
├── components/ # Reusable UI components
├── pages/ # Route pages
├── hooks/ # Custom React hooks
├── lib/ # Utilities and API clients
└── main.tsx # Entry point
```
## Gotchas
- Vite requires files in `public/` for static assets
- State updates in `useEffect` need proper dependency arrays
```
Shall I create this file?
```
### Example 3: Update Proposal
**User request:** "Update my CLAUDE.md with what you learned"
**Response:**
```markdown
### Update: ./CLAUDE.md
**Why:** Discovered that tests require database setup which wasn't documented.
```diff
## Testing
+ **Prerequisites:** Start test database first with `docker-compose up -d test-db`
+ `npm run test` - Run all tests
+ `npm run test:unit` - Unit tests only (no DB required)
```
Also found issue with API_BASE_URL:
```diff
## Environment
- `API_BASE_URL` - API endpoint (default: localhost:3000)
+ `API_BASE_URL` - API endpoint (required for production, defaults to http://localhost:3000 in dev)
```
Apply these changes?
~~~
## Best Practices
1. **Always read references before acting**: Quality criteria, templates, and update guidelines contain essential details
2. **Report before editing**: Never modify CLAUDE.md without first presenting a quality report
3. **Preserve existing structure**: When updating, maintain the existing organization and style
4. **Be project-specific**: Only add information specific to this codebase, not generic advice
5. **Verify commands work**: Before suggesting commands, mentally or actually verify they execute correctly
6. **Use progressive disclosure**: Keep SKILL.md lean, reference detailed rubrics in separate files
7. **Score consistently**: Apply the same scoring standards across all files for fair comparison
## Constraints and Warnings
1. **Never modify without approval**: Always get user confirmation before editing CLAUDE.md files
2. **Don't remove content without asking**: If suggesting deletions, explicitly mark them and get approval
3. **Respect `.claude.local.md`**: These are personal settings; never suggest modifying them in shared docs
4. **Avoid generic advice**: Do not add "write good code" type content - focus on project-specific patterns
5. **Keep diffs concise**: Show only the actual changes, not entire file contents
6. **Verify file paths**: Ensure all referenced files exist before documenting them
7. **Score objectively**: Use the rubric consistently; don't inflate scores for incomplete documentation