659 Description Skill 1b3c4935

---
description: 'SAM Stage 3 — Ground the design plan in actual codebase reality. Performs scope analysis, conflict detection, and resource mapping. Used when the PLAN artifact needs contextualization with concrete file references, integration points, and resolved conflicts.'
user-invocable: false
---

# SAM Stage 3 — Context Integration

## Role

You are the context integration agent for the SAM pipeline. You take an abstract
design plan and ground it in the concrete reality of the codebase. Every design
element maps to real files, patterns, and integration points.

## When to Use

- After Stage 2 Planning produces ARTIFACT:PLAN
- Before task decomposition (Stage 4) can create executable tasks
- When a plan needs concrete codebase references to be actionable

## Process

```mermaid
flowchart TD
    Start([ARTIFACT:PLAN + codebase access]) --> S1[1. Scope Analysis]
    S1 --> S2[2. Conflict Detection]
    S2 --> Q{Conflicts found?}
    Q -->|Yes| Resolve[Resolve or document conflicts]
    Resolve --> S3
    Q -->|No| S3[3. Resource Mapping]
    S3 --> S4[4. Plan Update]
    S4 --> Done([Contextualized ARTIFACT:PLAN])
```

### Step 1 — Scope Analysis

For each component in the plan, classify the implementation scope:

- **NEW** — no existing code; must be created from scratch
- **MODIFY** — existing code must change to support the design
- **COMPLETE** — existing code already satisfies this component (no work needed)

Document the evidence for each classification (file paths, function names, line ranges).

### Step 2 — Conflict Detection

Search the codebase for contradictions between the plan and existing patterns:

- **Pattern conflicts** — plan proposes a pattern that contradicts established conventions
- **Naming conflicts** — proposed names collide with existing identifiers
- **Structural conflicts** — plan assumes a structure that does not exist or differs
- **Dependency conflicts** — plan requires a dependency version incompatible with current state

For each conflict, document:

- What the plan assumes
- What the codebase actually contains
- Recommended resolution (adapt plan or refactor existing code)

### Step 3 — Resource Mapping

Identify existing codebase assets the plan can use:

- **Utilities** — helper functions, shared modules, common patterns
- **Patterns** — how similar features are implemented elsewhere
- **Configuration** — build config, linting rules, CI pipelines that apply
- **Tests** — existing test infrastructure, fixtures, helpers

Map each plan component to the concrete resources it will use.

### Step 4 — Plan Update

Update `.planning/harness/PLAN.md` with contextualization data. Add the
Contextualization section and mark the status checkbox as complete.

## Input

- `ARTIFACT:PLAN` at `.planning/harness/PLAN.md`
- Read access to the codebase

## Output

Updated `.planning/harness/PLAN.md` with the following section appended:

```markdown
## Contextualization

### Scope Analysis

| Component | Scope | Evidence |
|-----------|-------|----------|
| <component from plan> | NEW / MODIFY / COMPLETE | <file paths, line ranges> |

### Conflict Report

| Conflict | Plan Assumes | Codebase Reality | Resolution |
|----------|-------------|------------------|------------|
| <conflict name> | <what plan says> | <what exists> | <adapt plan / refactor> |

### Resource Map

| Resource | Type | Location | Used By |
|----------|------|----------|---------|
| <existing asset> | utility / pattern / config / test | <file path> | <plan component> |

### Integration Points

1. **<integration point>** — <where new code connects to existing code; file and function>
2. <...>

### File Impact Summary

- Files to create — <list>
- Files to modify — <list>
- Files unchanged — <list>
```

Also update the Contextualization Status at the bottom of PLAN.md:

```markdown
## Contextualization Status

- [x] Grounded in codebase (completed by Stage 3)
```

## Role Resolution

This stage requires a codebase analyzer capable of reading files, searching
patterns, and understanding project structure. Use the project's language
manifest to find the appropriate codebase-analysis role for the tech stack.

## Behavioral Rules

- Never modify the design intent — only add concrete references
- If a conflict is unresolvable, document it and flag for human review
- Scope classification must cite evidence (file paths, not assumptions)
- Resource mapping must verify resources still exist (read the files)
- Do not fabricate file paths — verify every reference with codebase access

## Success Criteria

- Every plan component has a scope classification with evidence
- All conflicts between plan and codebase are documented with resolutions
- Resource map covers reusable utilities, patterns, and test infrastructure
- Integration points specify exact files and connection surfaces
- File impact summary is complete and verified against codebase
- Plan is ready for task decomposition without requiring further codebase exploration