BMAD Context Extraction

BMAD Context Extraction

Why Context Extraction Matters

Architecture documents can span thousands of lines across many files. Developers working on a single story should not need to read 100% of the architecture to be effective. Context extraction solves this by:

• Reducing cognitive load — developers see only what is relevant to their story
• Preventing drift — extracted context includes source citations so decisions can be traced
• Enabling parallel work — each story is self-contained with embedded context
• Maintaining accuracy — citations let developers verify context against the source

How Bob (SM) Extracts Context

When creating a story, bob-sm follows this process:

1. Identify Relevant Architecture

Read the story's acceptance criteria and tasks to determine which architectural concerns apply:

• Which system components are touched?
• Which APIs or data models are involved?
• What patterns or conventions must be followed?
• Are there security, performance, or scaling constraints?

2. Extract Specific Sections

From the architecture docs in docs/architecture/, extract ONLY the sections relevant to this story. Do not copy entire documents. Target:

• Specific API endpoint definitions the story implements
• Data model schemas the story creates or modifies
• Authentication/authorization rules if the story touches protected resources
• Naming conventions and code patterns from the architecture style guide
• Integration points with other components

3. Write Dev Notes with Citations

Every extracted block in Dev Notes must include a source citation:

## Dev Notes

### API Design
The user endpoint follows RESTful conventions with JWT auth:
- POST /api/users — create new user
- GET /api/users/:id — retrieve user profile
- Auth: Bearer token required, validated via middleware
[Source: architecture/api-design.md#user-endpoints]

### Data Model
User schema includes: id (UUID), email (unique), name, created_at, updated_at
Password is stored as bcrypt hash, never returned in API responses.
[Source: architecture/data-model.md#user-schema]

### Conventions
- Use repository pattern for data access
- All endpoints return { data, error, meta } envelope
[Source: architecture/index.md#coding-conventions]

Source Citation Format

Citations follow this pattern:

[Source: architecture/<filename>.md#<section-heading>]

• filename is the architecture doc file name
• section-heading is the nearest heading above the extracted content, lowercased with hyphens
• Multiple sources can be cited per block

Examples:

• [Source: architecture/index.md#tech-stack]
• [Source: architecture/api-design.md#error-handling]
• [Source: architecture/data-model.md#relationships]
• [Source: architecture/auth.md#jwt-flow]

What Goes in Dev Notes vs Architecture Docs

Dev Notes are a lens into the architecture, not a copy. They should be concise and actionable.

Cross-Referencing Between Stories

When a story builds on work from a previous story, bob-sm should include:

### Previous Story Context
Story E1.S2 implemented the user authentication endpoint. The auth middleware
created there should be reused for this story's protected routes.
[Source: stories/story-E1.S2.md#completion-notes]

This creates a chain of context that helps developers understand the evolving codebase without re-reading all prior stories.

Context Freshness

Architecture documents may change during the project. Context extraction should be re-done when:

• The architecture doc's last modified date is newer than the story's creation date
• A prior story's implementation caused architecture changes
• The architect (winston-architect) has flagged specific docs as updated

Bob-sm should check file modification timestamps before extracting context for new stories. If architecture has changed since the last story was created, re-extract affected sections for accuracy.