Propose Project Learning

Retrospect on the current session and propose learnings for the project's CLAUDE.md.

Purpose

After working on a project, identify patterns, conventions, preferences, and rules that should be documented in the project's CLAUDE.md to improve future sessions.

Usage

/propose-project-learning        # Analyze and propose learnings
/propose-project-learning --save # Save proposal to ~/.claude/learnings/

What This Captures

Category	Examples
Code conventions	Naming patterns, file organization, import ordering
Architecture decisions	Preferred patterns, avoided anti-patterns
Tool preferences	Test frameworks, linters, formatters
Project-specific rules	Business logic constraints, domain terminology
Workflow preferences	Commit style, PR conventions, review process

Execution Instructions

When the user runs this command:

1. Analyze Current Session

Review the conversation history for:

• Corrections made - When the user corrected Claude's approach
• Explicit preferences - "Always use X", "Never do Y", "Prefer Z"
• Repeated patterns - Consistent choices across multiple files
• Project conventions - Naming, structure, organization patterns
• Tool/framework specifics - Project-specific configurations or usage

2. Check Existing CLAUDE.md

Read the project's CLAUDE.md (if exists) to avoid duplicates:

cat CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found"

Also check for CLAUDE.local.md:

cat CLAUDE.local.md 2>/dev/null

3. Generate Proposal

Format the proposal as:

# Proposed Learnings for CLAUDE.md

Based on this session, consider adding these to your project's CLAUDE.md:

## Code Conventions

- Use `snake_case` for all Python function names
- Prefer dataclasses over plain dicts for structured data

## Architecture

- All API endpoints go through the service layer, never direct DB access
- Use repository pattern for database operations

## Testing

- Use pytest fixtures, not setUp/tearDown methods
- Mock external services at the client level, not individual methods

## Project-Specific

- The `core` module should have no dependencies on other app modules
- All dates are stored as UTC, converted to local time only in templates

---

To add these to your CLAUDE.md:
1. Review each suggestion
2. Copy relevant items to CLAUDE.md
3. Adjust wording to match your style

4. Handle --save Flag

If --save is provided:

1. Ensure directory exists:

   mkdir -p ~/.claude/learnings/projects/{project-slug}/proposals/
   

2. Save proposal with timestamp:

   # File: ~/.claude/learnings/projects/{project-slug}/proposals/learning-{timestamp}.md
   

3. Confirm:

   Proposal saved to ~/.claude/learnings/projects/{project-slug}/proposals/learning-2026-01-09.md
   
   Review later with: cat ~/.claude/learnings/projects/{project-slug}/proposals/
   

5. Offer Next Steps

Next steps:
  [1] Add to CLAUDE.md now (I'll help edit)
  [2] Save for later (/propose-project-learning --save)
  [3] Dismiss

Select option:

Quality Criteria

Only propose learnings that are:

Criterion	Description
Specific	Concrete rules, not vague guidelines
Actionable	Claude can follow them in future sessions
Project-relevant	Not general best practices already known
Validated	Based on actual session behavior, not assumptions

Examples

Good Learnings

- API responses use `{"data": ..., "error": null}` wrapper format
- All Django models inherit from `BaseModel` in `core.models`
- Use `ruff` for linting, not `flake8`

Poor Learnings (Too Generic)

- Write clean code
- Follow PEP 8
- Use meaningful variable names

Notes

• This command analyzes the current session context
• Works best after substantial implementation work
• Complements /propose-forge-improvement which targets Product Forge itself
• Learnings are project-specific, not global