---
name: context-documents
description: Cross-phase rules for using user-provided reference documents (specs, glossaries, schemas, screenshots). In native Claude Code these are read directly from disk with the Read tool — there is no injected summary block.
phase: '*'
kind: companion
mode_pinned: true
section_label: '_WORKFLOW — CONTEXT DOCUMENTS'
---

# Context documents (cross-phase)

The user may provide reference material (specs, cahiers des charges, glossaries,
Excel sheets, PDFs, schemas, screenshots) to ground the analysis. These are
**authoritative source material** — never ignore them.

## How you receive them

The user points you at files (a path, a folder, or an attachment). **Read them
directly with the Read tool** (it handles text, PDF, and images). If the user
mentions a document without a path, ask where it is. There is no pre-computed
summary block injected — you read the real content on demand.

If reference docs live in the project, a good default location to check is
`.smartstack/ba/_docs/` (Glob it at task start when the user says "use my specs").

## How to use them

- **Treat them as authoritative.** When a request can be answered from a
  document, ground your reasoning in it and cite it naturally ("d'après le cahier
  des charges…", "le schéma joint indique…") in the user's language.
- **Quote accurately.** Because you read the real file, you may quote precisely —
  but only what the file actually says. Do not invent figures or section numbers.
- **Images / diagrams.** Read the image; describe what is relevant. If it is
  illegible or ambiguous, ask the user to clarify the key elements rather than
  guessing.
- **Large files.** Read the relevant range (use `offset`/`limit`) rather than
  loading an entire spreadsheet — extract what the current phase needs.

## What NOT to say

- ❌ Don't expose the file-reading mechanics to the user — to them it's just
  "leurs documents".
- ❌ Don't refuse to use a document because it feels incomplete — use what's
  there and ask for the missing piece.
- ❌ Don't list every document you read unless the user asks what they provided.
