Msia Prompts

Key points:

• SECURITY_START and SECURITY_END are Python string constants in loader.py, NOT .md files
• client_context and mode_context are dynamically injected — DO NOT hardcode them in .md files
• All .md files are read-cached at startup; changes require agent service restart
• loader.py:get_prompt_stats() returns token estimates per module (use for auditing)

Canonical Location Map

Each rule/instruction type has exactly ONE canonical home. Adding content to the wrong file creates duplicates and contradictions.

PROHIBITED duplications (will cause contradictions):

• Variant question format defined in mode files → use core/09_inline_questions.md only
• "Si vienes de / coming from" blocks in mode .md files → that is loader.py's job
• Pricing rules copied into mode files → core/07_pricing_rules.md is the source
• Security rules outside core/01_security.md

Token Budgets

Token estimate formula: len(file_content) // 4 (matches loader.py:get_prompt_stats() convention). Budgets = current measured size + 10% headroom.

Core Modules

Mode Files

⚠️ presupuesto_mode.md is at 91% of its cap. See "Large File Split Guidance" below before adding anything to this file.

Measure current size:

python -c "print(len(open('agent/prompts/PATH').read()) // 4)"
# or use the loader:
# from agent.prompts.loader import get_prompt_stats; print(get_prompt_stats())

Pre-Edit Checklist

MANDATORY before any change to agent/prompts/:

1. Load this skill — Read skills/msia-prompts/SKILL.md fully
2. Locate the canonical file — Use the Canonical Location Map above to confirm you're editing the RIGHT file
3. Measure current tokens — Run python -c "print(len(open('agent/prompts/PATH').read()) // 4)" or use get_prompt_stats()
4. Check for duplicates — Search other prompt files for the rule you're about to add:

   rg "your rule keyword" agent/prompts/
   

   If the rule exists elsewhere, DO NOT duplicate — update only the canonical file
5. Check for stale markers — Before submitting, grep for:

   rg "FIX-|INTERNAL_MARKER|T-[0-9]|version history|versión anterior" agent/prompts/
   

6. Measure tokens after edit — Confirm the file stays within its budget
7. Run lint tests — pytest tests/agent/prompts/test_prompt_lint.py -v must pass

Anti-Patterns

AP-1: Stale Markers

❌ # FIX-1: workaround for bug, <!-- T-6: temporary -->, INTERNAL_MARKER

Why harmful: These are developer notes, not LLM instructions. They consume tokens and confuse the model about what it should actually do.

Rule: Remove all markers before committing. Notes belong in ADRs (docs/decisions/) or code comments, never in .md prompt files.

AP-2: Duplicate Rules

❌ Same variant question format defined in presupuesto_mode.md AND consulta_mode.md AND expediente_*.md

Why harmful: Creates contradictions when rules diverge across files, wastes tokens (7x in a real documented case), and requires synchronised updates across every file.

Rule: One canonical file per rule type. All others reference or omit — never duplicate.

AP-3: Transition Blocks in Mode Files

❌ ## Si vienes de una transición\nRecuerda el contexto previo... in mode .md files

Why harmful: loader.py already injects mode_context dynamically. The .md block is always overridden and just wastes tokens.

Rule: Never add "Si vienes de / coming from" sections in mode .md files. That logic lives in loader.py.

AP-4: Version History / Migration Notes

❌ ## Diferencias clave vs versión anterior\n- Se eliminó el campo X...

Why harmful: Migration notes are for developers, not the LLM. They're outdated within one sprint and cost real tokens per turn.

Rule: Delete version history sections. Architectural decisions go in docs/decisions/ (ADRs).

AP-5: Emphasis Bloat

❌ 71 instances of NUNCA/CRITICAL/PROHIBIDO/🚨 across prompt files

Why harmful: Emphasis loses meaning when overused. LLM attention is diluted when every sentence is "critical".

Rule: Max 5 NUNCA/CRITICAL per file. Use sparingly for truly critical behaviours only.

AP-6: Unbounded Growth

❌ presupuesto_mode.md growing from ~20 KB to ~43 KB over 6 months

Why harmful: Per-turn token cost compounds. At 18,600 tokens/turn × thousands of turns = significant cumulative cost.

Rule: Check token budget after every edit. If a file exceeds 80% of its cap, evaluate splitting before adding more content.

Large File Split Guidance

If a mode file exceeds 80% of its token cap (8,640 tokens / 34,560 chars for modes), consider splitting:

Steps:

1. Identify functional sections in the file (e.g., presupuesto_mode.md has: step-by-step flow, pricing algorithm, image rules, FAQ examples)

2. Name split files as {mode}_{section}.md (e.g., presupuesto_mode_pricing.md)

3. Update loader.py to conditionally load split files based on sub-state:

   # In loader.py — conditional mode file loading
   if mode == "PRESUPUESTO_MODE":
       parts = ["presupuesto_mode_core.md"]
       if context.get("showing_pricing"):
           parts.append("presupuesto_mode_pricing.md")
   

4. Never split core modules — they are always loaded together

Current candidate: presupuesto_mode.md at 91% cap (~9,834 tokens). Recommended next split point: when it exceeds 10,000 tokens.

Critical Rules

1. ✅ ALWAYS load msia-prompts skill before editing any file in agent/prompts/
2. ✅ ALWAYS check Canonical Location Map before adding a rule
3. ✅ ALWAYS measure tokens before AND after your edit
4. ✅ ALWAYS run test_prompt_lint.py after edits
5. ✅ ALWAYS remove stale markers before submitting
6. ❌ NEVER duplicate rules across files — one canonical location per rule type
7. ❌ NEVER add client/context data to .md files — that is loader.py's job
8. ❌ NEVER add transition blocks ("Si vienes de...") to mode .md files
9. ❌ NEVER add version history or migration notes to .md files
10. ❌ NEVER commit if test_prompt_lint.py fails

Resources

• Prompt files: agent/prompts/ (core/ + modes/)
• Assembly logic: agent/prompts/loader.py
• Lint tests: tests/agent/prompts/test_prompt_lint.py
• Token stats: loader.py:get_prompt_stats()
• Architecture: agent/AGENTS.md → Prompt System section
• Related skill: msia-agent — agent architecture, tools, modes, state
• ADRs: docs/decisions/ — especially 002-dynamic-prompts.md