# Context Loader

> Discovers and loads only the project context needed for the current task. Use before planning, implementation, review, or debugging to avoid token waste and missing architecture. Emits CONTEXT_PACK. Never makes architectural decisions or loads the entire repo by default.

- Skill: `willianbs/context-loader` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add willianbs/context-loader`
- Raw SKILL.md: https://api.skillmd.com/api/skills/willianbs/context-loader/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: willianbs (https://skillmd.com/u/willianbs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/willianbs/context-loader

---


# Purpose

Build a minimal, sufficient `CONTEXT_PACK` so downstream skills decide with real project knowledge—not guesses.

# When to Use / When NOT to Use

**Use when:** starting any non-trivial engineering task; user mentions “load context”, “what’s the architecture”, or engineering-os begins a path.

**Do not use when:** user already provided a Complete CONTEXT_PACK; or the task is a pure wording edit with zero code impact.

# Preconditions

- A concrete task or question exists.
- Repo (or relevant paths) are accessible.

# Inputs / Outputs

**Inputs:** task statement, optional hints (paths, ticket).

**Outputs:** `CONTEXT_PACK`

# Upstream / Downstream

**Upstream:** engineering-os, model-router (optional).

**Downstream:** nearly all skills; especially spec-validator, adr-enforcer, delivery-planner, feature-implementer, defect-analyst.

# Core Principles

1. Sufficiency over completeness.
2. Authoritative sources beat stale docs when they conflict—and conflicts must be reported.
3. Token budget is a hard constraint.
4. Prefer ADRs, interfaces, and entrypoints over trivia.
5. Never invent missing context.
6. Stop early when Blocked/Incomplete for risky work.
7. Emit a portable artifact others can consume.

# Process

## Lite vs full

| Task risk | Mode |
|-----------|------|
| Typo, comment, tiny chore | lite: target files + nearest README only |
| Feature / bug / review | full discovery |

## Full discovery

1. **Source priority** (load in order, stop when sufficient):
   1. Task-named paths / ticket links
   2. Engineering guardrails (`docs/ENGINEERING_GUARDRAILS.md`, then `AGENTS.md` / `.cursor/rules/` summaries)
   3. ADRs / architecture docs (`docs/adr/`, `adr/`, `ARCHITECTURE.md`)
   4. Package/workspace manifests
   5. Entry points and public APIs for touched areas
   6. Existing tests for those areas
   7. README / CONTRIBUTING for commands only
2. **Dependency discovery** — only immediate neighbors of touched modules.
3. **Conflict detection** — code vs docs vs ADR; list explicitly.
4. **Budget** — default caps: ≤25 files or ~40k tokens of loaded content (whichever first). Summarize beyond that; cite paths instead of pasting.
5. **Completeness gate** — Complete / MostlyComplete / Incomplete / Blocked.

# Evidence Requirements

List every path actually read. Do not claim to have read files you skipped.

# Stop Conditions / Failure Modes

| Condition | Action |
|-----------|--------|
| Critical ADR/docs conflict for the task | `Blocked` |
| Cannot find any relevant code for named feature | `Incomplete` + questions |
| Budget exceeded before sufficiency | Summarize + `MostlyComplete` with gaps |
| No ADRs exist | Note `NoADRs`; do not invent architecture |
| No guardrails file on non-trivial work | Note `NoGuardrails`; suggest guardrails-configurator |

# Severity + Confidence

N/A for most runs. Conflicts that could cause wrong implementation → treat as `High` risk in CONTEXT_PACK.

# Output Contract

```
## CONTEXT_PACK
Completeness: Complete | MostlyComplete | Incomplete | Blocked
Summary: ...
Sources: [paths]
ADR IDs: ...
Conflicts: ...
Budget: files=N tokens≈M (caps ...)
Commands discovered: test/lint/build if found
Gaps / questions: ...
Decision: Proceed | ProceedWithConditions | Revise | Block
```

# Handoffs

- **adr-enforcer** — on conflicts or NoADRs needing bootstrap
- **spec-validator** — if requirements unclear
- **engineering-os** — return pack and continue path

# Never

- Never dump the whole repository.
- Never resolve architecture conflicts by picking a side silently.
- Never invent ADRs, APIs, or business rules.
- Never load secrets from `.env` into the pack; cite path only if needed and redact values.