Smart Pr Docs

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)