---
name: cont
effort: medium
description: >
  Load codebase context silently before starting work, optimized for LLM
  comprehension using research-backed structured formatting.
  Trigger: /cont followed by keywords (e.g., "/cont planner merchant",
  "/cont login user", "/cont dio menu"). Launches codebase-architect
  as subagent, returns one-line Italian confirmation. Keeps main
  context window clean. Also invoked automatically by /prd at kickoff.
---

# Context Primer

Load structured, task-adaptive context about a topic into the conversation before the user's real prompt. Based on research findings from Liu et al. 2023 (Lost in the Middle), Wu et al. 2024 (ClashEval), Asai et al. 2023 (Self-RAG), and Anthropic 2025 engineering guidance.

## Project Context

**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `paths.prd_dir`, `paths.wiki_dir`, `paths.adrs_dir`.
**Gated by features:** `features.has_backlog` (skip backlog grep when `false`), `features.has_wiki_overlay` (skip wiki search AND the wiki-log instrumentation tap), `features.has_adrs` (skip ADR includes), `features.has_prd_workflow` (skip PRD reads).
**Overlay:** loads `.baldart/overlays/context-primer.md` if present — project-specific topic vocabulary, must-include canonical docs.
**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.

## Effort

**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
reasoning depth for this run — detect it once at kickoff and strip the token
before consuming user input. Level→behavior mapping, parsing contract, and
precedence caveats: `framework/agents/effort-protocol.md`.


## Key Research Principles

1. **Constraints FIRST** — primacy effect: critical info at start gets +30% recall
2. **XML structure** — reduces misinterpretation vs flat text (Anthropic 2025)
3. **Dense > verbose** — 50% compression preserves 97% quality (Li et al. 2023)
4. **Stale context is harmful** — models override correct knowledge 60%+ with
   erroneous retrieved content (Wu et al. 2024). Timestamp all memory items.
5. **Task-adaptive selection** — bug fixes need different context than new features

## Workflow

1. Extract topic keywords from the user's input (e.g., "planner merchant").

2. **Detect task type** from keywords and conversation context:

   | Task Type | Signal Words |
   |-----------|-------------|
   | `bug-fix` | fix, bug, broken, error, crash, fails, non funziona |
   | `new-feature` | add, new, create, implement, feature, prd |
   | `refactor` | refactor, clean, simplify, migrate, move |
   | `doc-update` | doc, docs, document, readme, update docs |
   | `query` | how, what, where, why, explain, check, capire |

   Default to `query` if ambiguous.

3. Launch `codebase-architect` agent with this prompt template:

```
Load context about: {keywords}
Task type: {task_type}

TOKEN BUDGET: stay under 15K tokens total. Prefer the canonical router + targeted reads over broad file scans.

SEARCH STRATEGY — canonical-router-first, verify-only-if-needed:

1. Resolve the topic to its canonical source. Read `${paths.references_dir}/ssot-registry.md`
   to route `{keywords}` to the owning reference doc / ADR, then read only the matched
   section(s). If the topic is documentation-heavy and `features.has_wiki_overlay: true`,
   also consult `${paths.wiki_dir}/index.md` and any must-include docs listed in
   `.baldart/overlays/context-primer.md` (verify wiki claims against canonical docs).

2. Targeted searches:
   a. Agent memory: grep MEMORY.md index for topic match, read ONLY
      matching files (skip files >20KB unless filename matches keywords).
   b. Backlog (when `features.has_backlog: true`): grep `${paths.backlog_dir}/*.yml` for card titles matching keywords.
      Read only the matching cards, not all cards.
   c. Git: `git log --oneline -10 --grep="{keywords}"` (10 results max).

3. Broader search (when steps 1-2 are thin):
   a. Grep the project's source root for 2-3 specific identifiers from steps 1-2.
      When `features.has_lsp_layer: true` AND the identifier is a symbol (function /
      type / class name, not a free-text phrase), prefer LSP `find-references` /
      `go-to-definition` over Grep — it filters textual collisions before any file
      read. Cap at 3 LSP calls, then fall back. See `framework/agents/code-search-protocol.md`.
      When `features.has_code_graph: true` AND the question is structural/relational
      (how X connects to Y, impact, clusters), prefer the Graphify code graph
      (`graphify query`/`path`/`affected`) — see `framework/agents/code-graph-protocol.md`.
   b. Read key file headers (first 50 lines) to identify structure.
   DO NOT read `${paths.prd_dir}/` or `${paths.references_dir}/` files in full —
   route via the registry and read only the specific section you need.

4. Targeted verification (ALL cases):
   - Verify ONLY runtime-sensitive claims (auth patterns, API contracts,
     current schema) against actual code.
   - Files <200 lines: read in full.
   - Files 200-500 lines: read first 50 lines + specific section.
   - Files >500 lines: grep for key exports/functions, read only those.
   - NEVER read agent memory files >20KB in full.

TASK-ADAPTIVE RULES:
- "query": canonical docs + memory only. Skip source code unless code-specific.
- "bug-fix": canonical docs + recent git changes + error-related code. Skip arch docs.
- "new-feature": canonical docs + patterns in same domain + ADRs. Skip unrelated areas.
- "refactor": canonical docs + affected files + dependency refs. Skip design rationale.
- "doc-update": SSOT registry. Skip source code.

WIKI OVERLAY ROUTING:
- If the topic is about synthesized knowledge, dashboards, reading guides, or
  recurring documentation questions, prefer the derived wiki overlay as a
  compression layer.
- Always verify wiki claims against canonical repo docs before using them as
  working truth.

Return output in this EXACT XML format (30-50 lines max):

<context_primer task_type="{task_type}">
  <constraints>
    <!-- MOST CRITICAL — active gotchas, forbidden patterns, known bugs -->
    <!-- Put highest-impact constraints first (primacy effect) -->
    <c>[MUST] constraint text (source: file or AGENTS.md section)</c>
  </constraints>
  <area>One-line description of the module/domain</area>
  <key_code>
    <!-- 3-5 most relevant source files — paths only, not content -->
    <file path="src/path/to/file.ts">Brief role description</file>
  </key_code>
  <key_docs>
    <!-- 2-4 most relevant doc/spec/ADR paths -->
    <doc ref="docs/path/to/doc.md">Brief description</doc>
  </key_docs>
  <status>Current state: active card, last commit, blockers</status>
  <memory_notes>
    <!-- Memory-derived content WITH acquisition dates -->
    <note acquired="YYYY-MM-DD">Note content</note>
    <note acquired="YYYY-MM-DD" stale="true">Old note [STALE — verify]</note>
  </memory_notes>
</context_primer>

CRITICAL OUTPUT RULES:
- Constraints section MUST come FIRST (research: primacy effect +30%)
- Keep total output under 50 lines — dense beats verbose
- Every memory_notes entry MUST have an acquired date
- If a memory item file was modified >7 days ago AND refers to current
  state (not permanent decisions), mark it stale="true"
- Do NOT include file contents or code snippets. Paths and summaries only.
- If no constraints found, use <constraints/> (empty, not omitted)
```

4. After the agent returns, respond to the user with ONLY:

```
Contesto caricato ({task_type}): {one-line summary of the area}.
Pronto.
```

The XML context lives in the conversation history from the agent result.
It will inform subsequent responses without cluttering visible output.

## Examples

- `/cont planner merchant` → `Contesto caricato (query): CTP planner v2 (table management merchant). Pronto.`
- `/cont fix booking overlap` → `Contesto caricato (bug-fix): Booking overlap validation in reservation API. Pronto.`
- `/cont new prize scanning` → `Contesto caricato (new-feature): Prize scanning flow (wheel + scratch card). Pronto.`

## Rules

- ALWAYS use `codebase-architect` as `subagent_type` in the Agent tool call.
- NEVER dump the agent's full output to the user. Only the confirmation line.
- If the user provides fewer than 1 topic keyword (e.g., bare "/cont"),
  ask for more specific keywords.
- The agent runs in foreground (not background) — the user waits for
  confirmation before sending their real prompt.
- When invoked by another skill (e.g., /prd), the task_type is inferred
  from that skill's context (e.g., /prd → "new-feature").
