Pm Memory

PM Memory (MANDATORY)

The Iron Law

EVERY WORKFLOW MUST:
1. LOAD memory at START (and before key decisions)
2. UPDATE memory at END (and after learnings/decisions)

Brevity Rule: Memory is an index, not a document. Be brief -- one line per item.

What "Memory" Actually Is

cc-p4p memory is a small, stable, permission-free Markdown database used for:

• Continuity: survive compaction/session resets
• Consistency: avoid contradicting prior decisions
• Compounding: promote insights into reusable knowledge
• Resumability: recover where a workflow stopped

Memory Surfaces (Types)

1. Working Memory: .claude/cc-p4p/activeContext.md
   • "What matters right now": focus, recent work, decisions, open questions
   • Links to durable artifacts (specs/research/roadmaps)
2. Insights Memory: .claude/cc-p4p/insights.md
   • User research insights, competitive intelligence, customer feedback themes, personas
3. Roadmap Memory: .claude/cc-p4p/roadmap-state.md
   • Now/Next/Later priorities, shipped items, dependencies, capacity
4. Artifact Memory (Durable): docs/specs/*, docs/research/*, docs/roadmap/*
   • The details. Memory files are the index.
5. Tasks (Execution State): Claude Code Tasks
   • Great for orchestration, survives across sessions.

Promotion Ladder

Information "graduates" to more durable layers:

• One-off observation -> activeContext.md (Recent Work / Decisions)
• Research finding -> insights.md (User Research / Competitive / Themes)
• Priority decision -> roadmap-state.md (Current Priorities)
• Needs detail -> docs/specs/* or docs/research/* + link from activeContext

Permission-Free Operations (CRITICAL)

ALL memory operations are PERMISSION-FREE using the correct tools.

CRITICAL: Write vs Edit

RULE: Use Write for NEW files, Edit for UPDATES.

CRITICAL: Use Read Tool, NOT Bash(cat)

NEVER use Bash compound commands -- they ASK PERMISSION. ALWAYS use Read tool for reading files -- it's PERMISSION-FREE.

Memory Structure

.claude/
  cc-p4p/
    activeContext.md   # Current focus + decisions + open questions (MOST IMPORTANT)
    insights.md        # Research insights, competitive intel, customer themes
    roadmap-state.md   # Now/Next/Later priorities, shipped items, dependencies

Who Reads/Writes Memory (Ownership)

Read

• Router (always): loads all 3 files before workflow selection.
• WRITE agents (spec-writer, research-synthesizer, roadmap-planner): load memory at task start.
• READ-ONLY agents (comms-drafter): receive memory summary in prompt, do NOT load this skill.

Write

• WRITE agents: update memory directly at task end using Edit(...) + Read(...) verify.
• READ-ONLY agents: output ### Memory Notes section. Router persists via task-enforced Memory Update.

Pre-Compaction Memory Safety

Update memory IMMEDIATELY when you notice:

• Extended brainstorming (5+ rounds)
• Long spec discussions
• Multi-topic research synthesis
• 30+ tool calls in session

Checkpoint Pattern:

Edit(file_path=".claude/cc-p4p/activeContext.md",
     old_string="## Current Focus",
     new_string="## Current Focus\n\n[Updated focus + key decisions]")
Read(file_path=".claude/cc-p4p/activeContext.md")  # Verify

Memory File Templates

activeContext.md (Read/Write EVERY session)

# PM Active Context
<!-- CC-P4P: Do not rename headings. Used as Edit anchors. -->

## Current Focus
[Active work -- what PM task is in progress]

## Recent Work
- [Date] [What was done] - [artifact reference]

## Decisions
- [Decision]: [Choice] - [Why]

## Open Questions
- [Question] - [Who should answer] - [Blocking/Non-blocking]

## References
- Spec: `docs/specs/...` (or N/A)
- Research: `docs/research/...` (or N/A)
- Roadmap: `docs/roadmap/...` (or N/A)

## Last Updated
[timestamp]

insights.md (Accumulates research findings)

# PM Insights
<!-- CC-P4P: Do not rename headings. Used as Edit anchors. -->

## User Research Insights
- [Insight]: [Evidence] - [Source: interview/survey/analytics]

## Competitive Intelligence
- [Competitor]: [Finding] - [Implication for us]

## Customer Feedback Themes
- [Theme]: [Frequency] - [Severity] - [Example quote]

## Personas
- [Persona name]: [Brief description] - [Key need]

## Last Updated
[timestamp]

roadmap-state.md (Tracks priorities)

# PM Roadmap State
<!-- CC-P4P: Do not rename headings. Used as Edit anchors. -->

## Current Priorities

### Now (In Progress)
- [Item]: [Owner] - [Status]

### Next (Planned)
- [Item]: [Priority score] - [Dependencies]

### Later (Future)
- [Item]: [Strategic rationale]

## Shipped
- [Date] [Item] - [Impact/metrics]

## Dependencies
- [Dependency]: [Owner] - [Need-by date] - [Status]

## Capacity Notes
- [Team/resource considerations]

## Last Updated
[timestamp]

Stable Anchors (ONLY use these)

NEVER use as anchors:

• Table headers (| Col | Col |)
• List item text (- specific text)
• Optional sections that may not exist

Read-Edit-Verify (MANDATORY)

Every memory edit MUST follow this exact sequence:

Step 1: READ

Read(file_path=".claude/cc-p4p/activeContext.md")

Step 2: VERIFY ANCHOR

# Check if intended anchor exists in the content you just read
# If anchor not found -> use "## Last Updated" as fallback

Step 3: EDIT

Edit(file_path=".claude/cc-p4p/activeContext.md",
     old_string="## Recent Work",
     new_string="## Recent Work\n- [New entry]\n")

Step 4: VERIFY

Read(file_path=".claude/cc-p4p/activeContext.md")
# Confirm your change appears. If not -> STOP and retry.

Memory File Contract (Never Break)

Hard rules:

• Do not rename the top-level headers (# PM Active Context, # PM Insights, # PM Roadmap State).
• Do not rename section headers (e.g., ## Current Focus, ## Last Updated).
• Only add content inside existing sections (append lists/rows).
• After every Edit(...), Read back the file and confirm the intended change exists.

If an Edit does not apply cleanly:

• STOP (do not guess).
• Re-read the file and re-apply using a correct, exact old_string anchor.

Mandatory Operations

At Workflow START (REQUIRED)

# Step 1: Create directory
Bash(command="mkdir -p .claude/cc-p4p")

# Step 2: Load ALL 3 memory files
Read(file_path=".claude/cc-p4p/activeContext.md")
Read(file_path=".claude/cc-p4p/insights.md")
Read(file_path=".claude/cc-p4p/roadmap-state.md")

If file doesn't exist: Read tool returns an error -- that's fine, means starting fresh.

At Workflow END (REQUIRED)

# Read existing content
Read(file_path=".claude/cc-p4p/activeContext.md")

# Add entry to Recent Work
Edit(file_path=".claude/cc-p4p/activeContext.md",
     old_string="## Recent Work",
     new_string="## Recent Work\n- [YYYY-MM-DD] [What was done] - [artifact path]\n")

# VERIFY
Read(file_path=".claude/cc-p4p/activeContext.md")

Integration with Agents

ALL agents MUST:

1. START: Load memory files before any work
2. DURING: Note decisions and insights
3. END: Update memory files with new context

If an agent cannot safely update memory (e.g., no Edit tool -- comms-drafter):

• Include notes in ### Memory Notes section
• Router persists those notes via task-enforced Memory Update

Failure to update memory = incomplete work.

Red Flags -- STOP IMMEDIATELY

If you catch yourself:

• Starting work WITHOUT loading memory
• Making decisions WITHOUT checking Decisions section
• Completing work WITHOUT updating memory
• Saying "I'll remember" instead of writing to memory

STOP. Load/update memory FIRST.

Rationalization Prevention