BMAD-METHOD/expansion-packs/bmad-javascript-fullstack/data/context-loading-guide.md

Context Loading Guide

Decision trees and strategies for Just-in-Time context retrieval. This guide helps agents load the minimal necessary context at the right time.

Core Principle

Load context when making decisions, not before.

Every piece of context loaded costs tokens. Load only what you need, when you need it, for the specific decision you're making RIGHT NOW.

Universal Loading Rules

Always Load (Every Task Start)

• ✅ Agent role definition
• ✅ core-principles.md
• ✅ Current task description and requirements
• ✅ Explicitly referenced artifacts (checkpoints, PRDs, specs)

Never Load (Unless Specific Decision)

• ❌ Technology-specific implementation guides
• ❌ Best practices documentation
• ❌ Pattern libraries
• ❌ Other agents' domain-specific guides

Ask Before Loading

Before loading ANY additional file, ask these 4 questions:

1. Am I making THIS decision RIGHT NOW? (Not later, not "might need")
2. Is this MY role's responsibility? (Not another agent's domain)
3. Is this already in checkpoint/requirements? (Don't duplicate)
4. Can I use role knowledge instead? (Load only for complex/unfamiliar decisions)

If answer to #1 or #2 is NO → Don't load it

Decision Tree by Task Type

Task: Greenfield Project Architecture

Start: Load requirements + core-principles.md
│
├─ Technology Stack Decision?
│  └─ YES → Load technology-stack-guide.md
│  └─ NO → Skip (already decided)
│
├─ Deployment Strategy Decision?
│  └─ YES → Load deployment-strategies.md
│  └─ NO → Skip (decide later)
│
├─ Security Requirements Present?
│  └─ YES (auth/PII/payments) → Load security-guidelines.md
│  └─ NO → Skip
│
├─ Architecture Pattern Decision?
│  └─ YES → Load architecture-patterns.md
│  └─ NO → Use standard monolith, skip
│
└─ Implementation Details?
   └─ SKIP ALL (delegate to implementation agents)

Token Budget: ~2,000-4,000 tokens

• Base: ~500 tokens (role + requirements)
• Stack guide: ~1,000 tokens
• Deployment: ~500 tokens
• Security (if needed): ~1,000 tokens

Task: Feature Development (Existing Project)

Start: Load checkpoint + feature requirements
│
├─ New Components Needed?
│  ├─ Simple component → Use role knowledge (skip guides)
│  └─ Complex reusable component → Load component-design-guidelines.md
│
├─ State Management Decision?
│  ├─ Already defined in architecture → Use existing pattern (skip guide)
│  └─ New state solution needed → Load state-management-guide.md
│
├─ New API Endpoints?
│  ├─ Standard CRUD → Use role knowledge (skip guides)
│  └─ Complex/new API type → Load api-implementation-patterns.md (specific section only)
│
├─ Authentication/Authorization Changes?
│  └─ YES → Load security-guidelines.md
│  └─ NO → Skip
│
└─ Performance Requirements?
   └─ YES → Load performance-checklist.md
   └─ NO → Skip

Token Budget: ~1,000-2,000 tokens

• Base: ~700 tokens (checkpoint + requirements)
• Add ~300-500 per guide loaded
• Target: Load max 1-2 guides per feature

Task: API Design

Start: Load requirements + data models
│
├─ What API Type?
│  ├─ REST → Load REST section of api-implementation-patterns.md (~200 tokens)
│  ├─ GraphQL → Load GraphQL section of api-implementation-patterns.md (~300 tokens)
│  └─ tRPC → Load tRPC section of api-implementation-patterns.md (~200 tokens)
│
├─ Authentication Endpoints?
│  └─ YES → Load security-guidelines.md
│  └─ NO → Skip
│
└─ Existing API Standards?
   ├─ YES → Follow existing patterns (skip guide)
   └─ NO → Load api-best-practices.md

Token Budget: ~1,000-1,500 tokens

• Base: ~500 tokens
• API pattern section: ~200-300 tokens
• Security (if auth): ~1,000 tokens

Task: Code Review

Start: Load code being reviewed + task context
│
├─ Check Architecture Alignment?
│  └─ Load architecture-review-checklist.md
│
├─ Security-Critical Code (auth/validation)?
│  └─ Load security-guidelines.md
│
├─ Performance-Critical Code?
│  └─ Load performance-checklist.md
│
└─ General Code Quality?
   └─ Load development-guidelines.md

Token Budget: ~800-1,500 tokens

• Code: ~500 tokens
• Checklist: ~300-500 tokens
• Add specific guides as needed

Task: Database Schema Design

Start: Load requirements + data relationships
│
├─ Database Type Decision?
│  ├─ Choosing SQL vs NoSQL → Load database-design-patterns.md (comparison section)
│  └─ Already chosen → Skip, use existing
│
├─ Complex Relationships?
│  └─ Load database-design-patterns.md (schema design section)
│
└─ Simple CRUD Schema?
   └─ Use role knowledge (skip guides)

Token Budget: ~800-1,200 tokens

Task: TypeScript Migration

Start: Load existing JavaScript code + migration requirements
│
├─ Project Setup?
│  └─ Load development-guidelines.md (tsconfig section)
│
├─ Complex Type Scenarios?
│  └─ Load TypeScript advanced patterns
│
└─ Gradual Migration Strategy?
   └─ Load migration guide

Token Budget: ~1,000-2,000 tokens

Decision Trees by Agent Role

React Developer

Task Received
│
├─ Component Implementation (Simple)
│  └─ Load: NOTHING (use role knowledge)
│
├─ Component Implementation (Complex/Reusable)
│  └─ Load: component-design-guidelines.md
│
├─ State Management Decision
│  └─ Load: state-management-guide.md
│
├─ Performance Optimization
│  └─ Load: performance-checklist.md
│
├─ Form Implementation
│  └─ Load: form validation patterns
│
└─ Testing Complex Component
   └─ Load: testing-strategy.md

Node Backend Developer

Task Received
│
├─ CRUD Endpoints (Standard)
│  └─ Load: NOTHING (use role knowledge)
│
├─ Authentication/Authorization
│  └─ Load: security-guidelines.md
│
├─ Framework Selection
│  └─ Load: backend-patterns.md (framework comparison)
│
├─ Complex Queries / Performance Issues
│  └─ Load: database-optimization.md
│
└─ Background Jobs
   └─ Load: job queue patterns

Solution Architect

Task Received
│
├─ Requirements Analysis
│  └─ Load: NOTHING except requirements
│
├─ Technology Stack Decision
│  └─ Load: technology-stack-guide.md
│
├─ Architecture Pattern Selection
│  └─ Load: architecture-patterns.md
│
├─ Deployment Strategy
│  └─ Load: deployment-strategies.md
│
├─ Security/Compliance Requirements
│  └─ Load: security-guidelines.md
│
└─ Implementation Details
   └─ SKIP (delegate to implementation agents)

API Developer

Task Received
│
├─ REST API Design
│  └─ Load: api-implementation-patterns.md (REST section ONLY)
│
├─ GraphQL API Design
│  └─ Load: api-implementation-patterns.md (GraphQL section ONLY)
│
├─ tRPC API Design
│  └─ Load: api-implementation-patterns.md (tRPC section ONLY)
│
├─ Auth Endpoints
│  └─ Load: security-guidelines.md
│
└─ Standard CRUD
   └─ Load: NOTHING (use OpenAPI spec template)

TypeScript Expert

Task Received
│
├─ Project Setup / tsconfig
│  └─ Load: development-guidelines.md (TS section)
│
├─ Standard Type Definitions
│  └─ Load: NOTHING (use role knowledge)
│
├─ Complex Generics / Advanced Types
│  └─ Load: TypeScript advanced patterns
│
└─ JS to TS Migration
   └─ Load: migration guide

Context Loading Patterns

Pattern 1: Minimal Start

When: Every task Load: Role + core-principles.md + task requirements only Skip: Everything else until decision point Tokens: ~500-700

Pattern 2: Checkpoint-Based

When: Continuing multi-phase workflow Load: Most recent checkpoint + current task Skip: Full phase history, archived discussions Tokens: ~800-1,200

Pattern 3: Decision-Triggered

When: Making specific technology/pattern choice Load: Single guide for that decision Skip: All other guides Tokens: +300-1,000 (per decision)

Pattern 4: Section-Only Loading

When: Loading large reference file Load: Only relevant section (e.g., "REST API" from api-implementation-patterns.md) Skip: Other sections Tokens: ~200-500 vs ~1,500-3,000 (full file)

Pattern 5: Progressive Expansion

When: Complex task with multiple decision points Load: Stage 1 (minimal) → Stage 2 (decision guides) → Stage 3 (implementation patterns) Skip: Future stage context until needed Tokens: Spread across stages, create checkpoints between

Red Flags: When You're Over-Loading

🚩 Red Flag Signals:

• Loading >3 data files for single task
• Loading files "just in case"
• Loading before knowing what decision you're making
• Loading other agents' domain-specific guides
• Loading implementation details during architecture phase
• Loading optimization guides before having performance issue

Token Budget Guidelines

By Task Complexity

Simple Task (component, CRUD endpoint, type definition):

• Budget: <1,000 tokens total
• Load: Role + task only

Medium Task (feature, API design, review):

• Budget: 1,000-2,000 tokens
• Load: Role + task + 1-2 specific guides

Complex Task (architecture, migration, system design):

• Budget: 2,000-4,000 tokens
• Load: Role + task + multiple guides
• Strategy: Use checkpoints to compress

Multi-Phase Workflow:

• Budget: <10,000 tokens cumulative
• Strategy: Checkpoint after each phase (compress to ~1,000 tokens)

Budget Triggers

Create Checkpoint When:

• Phase context exceeds 3,000 tokens
• Transitioning between workflow phases
• Completed major decision point
• 5+ agent interactions in sequence

Archive Context When:

• Discussion exceeds 1,000 tokens
• Implementation details complete
• Decision finalized (keep conclusion only)

Validation Checklist

Before loading any file, verify:

• I am making a specific decision RIGHT NOW (not "might need later")
• This decision is my role's responsibility
• This information is NOT in checkpoint/requirements already
• I cannot use my role knowledge for this decision
• I am loading ONLY the relevant section, not entire file
• I have not already loaded >2 guides for this task
• This will help me complete THIS task, not future tasks

If any checkbox is unchecked → Don't load it

Examples

✅ Good: JIT Loading

Task: Build user authentication system

Sequence:

1. Start: Load role + core-principles.md + requirements (~500 tokens)
2. Decision: Auth approach → Load security-guidelines.md (~1,000 tokens)
3. Decision: API design → Load api-implementation-patterns.md (REST section ~200 tokens)
4. Implementation: Use loaded context, skip additional guides
5. Total: ~1,700 tokens

❌ Bad: Upfront Loading

Task: Build user authentication system

Sequence:

1. Start: Load role + security-guidelines.md + api-implementation-patterns.md + database-optimization.md + deployment-strategies.md + best-practices.md (~6,000 tokens)
2. Use: Only security-guidelines.md and partial API patterns
3. Waste: ~4,000 tokens of unused context

Problem: Loaded everything upfront, used <40% of it

✅ Good: Section-Only Loading

Task: Design REST API for user service

Sequence:

1. Load: Role + task (~500 tokens)
2. Load: REST section from api-implementation-patterns.md (~200 tokens)
3. Skip: GraphQL, tRPC, WebSocket sections
4. Total: ~700 tokens vs ~1,500 if loaded full file

❌ Bad: Full File Loading

Task: Design REST API for user service

Sequence:

1. Load: Full api-implementation-patterns.md (~1,500 tokens)
2. Use: Only REST section (~200 tokens worth)
3. Waste: ~1,300 tokens of GraphQL/tRPC/WebSocket patterns

Summary

Golden Rules:

1. Start minimal (role + task + requirements)
2. Load on decision points (not before)
3. Load sections, not full files
4. Ask 4 questions before loading
5. Create checkpoints when >3K tokens
6. Archive verbose context immediately

Target: <1,000 tokens for simple tasks, <2,000 for medium, <4,000 for complex

Remember: Context is expensive. Every token loaded must directly contribute to the current decision.