Smart PR Documentation Generator

This skill automatically generates comprehensive PR documentation that tracks what changed, why it changed, and the ripple effects across your entire codebase.

Instructions

Step 0: Load Architecture Context (Elite Mode)

Before analyzing changes, check if the project has an architecture map.

1. Look for

   architecture-config.json

   in the root.
2. If found, use it to map modified files to their respective Systems.
3. Identify Business Rules and Consumers for those systems.

[!IMPORTANT] System-Aware PRs: This is the "God Mode" of documentation. Instead of "modified logic.ts", you say "modified P2P system (Critical business rule: No negative balance)".

Step 1: Analyze Active Branch Changes

First, scan all changes in the current branch:

# Get all changed files
git diff --name-only main...HEAD

# Get detailed changes
git diff main...HEAD

Why this approach: Git is the source of truth. It knows exactly what changed without guessing.

Step 2: Map Feature Ownership

For each changed file, determine which feature(s) it belongs to:

1. Look for existing

   claude.md

   files in the project
2. Read each

   claude.md

   to understand feature boundaries
3. Match changed files to their feature(s)

[!TIP] claude.md files act as feature handbooks that Claude automatically reads. They store context so you don't have to re-explain every time.

Step 3: Analyze Ripple Effects (CRITICAL)

For each changed file, identify what else is affected:

Check for:

• Functions/classes that import this file
• Components that use these functions
• API endpoints that depend on this code

# Find all files that import a specific file
grep -r "import.*from.*<file-path>" . --include="*.ts" --include="*.tsx"

Trade-off: This grep-based approach is fast but may miss dynamic imports. For 100% accuracy, use a static analysis tool like

ts-morph

.

[!IMPORTANT] The Blast Radius: This step reveals the domino effect of your changes. Most developers don't realize that changing one file affects 15+ others.

Step 4: Generate Mermaid Diagrams

A. Change Flow Diagram

graph TD
    A[Changed File: auth/login.ts] --> B[Direct Impact: auth/middleware.ts]
    A --> C[Direct Impact: api/routes.ts]
    B --> D[Ripple Effect: dashboard/protected.tsx]
    
    style A fill:#ff6b6b
    style B fill:#ffd93d
    style D fill:#6bcf7f

Color coding methodology:

• Red (#ff6b6b): Primary changes (what you modified)
• Yellow (#ffd93d): Direct dependencies (files that import your changes)
• Green (#6bcf7f): Ripple effects (indirect dependencies)

Why visual maps: Humans process visual information 60,000x faster than text. A diagram beats a text list for understanding complex dependencies.

Step 5: Update claude.md Files

For each affected feature, update its

claude.md

file:

Structure for each claude.md:

# [Feature Name] - Last Updated: [Date]

## Recent Changes
### [Date] - [Change Title]
**What Changed:**
- [file]: [description]

**Why:**
- [Business context and reasoning]

**Ripple Effects:**
- Affects: [Feature] - [Impact description]
- Breaking changes: [Yes/No - Details]

Edge case: If a

claude.md

doesn't exist for a feature, create one. This is an opportunity to establish context for future work.

Step 6: Generate PR Documentation

🏗️ Architectural Impact (if system-aware)

📦 [System Name]

Role: [Description from architecture-config.json] Changes: [Summary of changes in this system] ⚠️ Critical Rules:

• [Rule 1 from config]
• [Rule 2 from config]

🔗 Ripple Effect: This system is consumed by [Consumers list].

---

🎯 What Changed

[High-level summary]

📝 Detailed Changes

🔄 Ripple Effects & Dependencies

Dependency Map

[Full dependency diagram]

Direct Impact

• [Feature]: [Impact description]

Indirect Impact

• [Feature]: [Impact description]

⚠️ Breaking Changes

[Yes/No - Migration guide if yes]

🧪 Testing Checklist

• [Test case 1]
• [Test case 2]

📚 Documentation Updated

• file - [what was updated]

### Step 7: Validate Documentation

**Completeness Check:**
- All changed files documented?
- All ripple effects identified?
- Mermaid diagrams render correctly?

```bash
# Validate Markdown syntax
find . -name "claude.md" -exec markdown-lint {} \;

# Check for unfinished work
grep -r "TODO\|FIXME" */claude.md

Methodology: The Ripple Effect Analysis

The core philosophy is Contextual Certainty. Before documenting, build a complete mental model of the system.

Approach:

1. Bottom-up exploration: Start with git diff, move to dependency analysis
2. Layered impact: Direct → Indirect → System-wide
3. Visual synthesis: Convert data to diagrams for instant comprehension

Principles:

• Deep Context First: Never guess dependencies. Use grep/scripts to find actual imports.
• Self-Correction: If a diagram doesn't render, validate Mermaid syntax before proceeding.
• User-First Lens: Every PR doc should be readable by non-technical stakeholders (PMs, designers).

Advanced Technical Nuance

Memory vs. Speed Trade-off:

• Grep-based dependency search is fast (< 1 second) but may miss edge cases
• AST-based analysis (ts-morph, babel) is 100% accurate but slower (5-10 seconds)
• Recommendation: Use grep for most cases, AST for critical production changes

Edge Case: Monorepos

• In monorepos with 100+ packages, limit dependency search to relevant workspaces
• Use

  --include

  flags to filter by file type and avoid scanning node_modules

# Efficient monorepo search
grep -r "import.*auth" packages/web packages/api --include="*.ts*"

The 80/20 Rule:

• 80% of bugs come from 20% of dependencies
• Focus ripple effect analysis on high-traffic files (API routes, auth, payments)