Revision control
+ # The Seven Skill-Loading Patterns
+
+ Canonical reference for how agents in the Qt Doc Agent Framework load
+ skills. Every agent's definition names which patterns it uses; the
+ orchestrator picks patterns 6 (hierarchical) and 7 (verification) at the
+ framework level.
+
+ Adapted from established Claude Code skill-design practice; the summary
+ table and detailed sections below are the framework's public reference.
+
+ ## Summary
+
+ | # | Pattern | How it works | Best for | Watch out for |
+ |---|---------|--------------|----------|---------------|
+ | 1 | **System Prompt Embedding** | Rules pasted into the system prompt | Small, stable rule sets needed every run | Uses up context permanently; doesn't scale past ~2 skills |
+ | 2 | **Upfront Loading** | Agent reads all skill files at start | Short workflows; skills needed continuously | Claude forgets earlier content in long conversations; wastes memory on irrelevant skills |
+ | 3 | **GATE-Based / Just-in-Time** | Agent reads a specific skill at each decision point | Multi-step workflows; large skill libraries | More complex prompt design; extra file reads per run |
+ | 4 | **RAG / Retrieval** | External search retrieves relevant passages | Very large knowledge bases (100+ docs) | Rules may get cut in half during retrieval; less control over what's retrieved |
+ | 5 | **Tool-Based Lookup** | Skills exposed as tools the agent calls on demand | Exploratory tasks; strong models (Opus) | Agent may skip lookups; hard to verify which rules were checked |
+ | 6 | **Hierarchical / Cascading** | Knowledge split across prompt layers (orchestrator → agent → skill) | Multi-agent systems with an orchestrator | Adds complexity for single-agent setups |
+ | 7 | **Multi-Agent Verification** | Second pass checks first agent's output against the rules | High-stakes outputs where errors are costly | Slower; doubles compute; needs concrete verification criteria |
+
+ **The framework's stack combines 1 + 2 + 3 + 6 + 7.** Most real agents
+ layer multiple patterns.
+
+ ## How to pick a pattern
+
+ Decision tree (in order — take the first `YES`):
+
+ - Small, stable, always-needed rule set? → **Pattern 1: System Prompt Embedding.**
+ - Skill needed at one specific step in a multi-step workflow? → **Pattern 3: GATE-Based** (the recommended default).
+ - Skill needed continuously across a short workflow? → **Pattern 2: Upfront Loading.**
+ - Knowledge base too large to fit in any prompt? → **Pattern 4: RAG.**
+ - Skill better modeled as a tool call the agent decides when to invoke? → **Pattern 5: Tool-Based Lookup.**
+ - Multi-agent system with an orchestrator? → **Pattern 6: Hierarchical** (combine with Pattern 3).
+ - High-stakes output where errors are costly? → **Add Pattern 7: Multi-Agent Verification.**
+
+ ## How the framework uses each pattern
+
+ | # | Where |
+ |---|-------|
+ | 1 | Orchestration rules embedded in [`../CLAUDE.md`](../CLAUDE.md). |
+ | 2 | Initial-check pair (`skill-framework-fitness` + `skill-security-hygiene`) loaded upfront on every dispatch. |
+ | 3 | Stage agents GATE-load skills at the decision point they apply to. Recommended default for new agents. |
+ | 5 | Tool wrappers live in [`../tools/`](../tools/); a skill invokes them at a specific step. No tool shipped yet. |
+ | 6 | The four-layer chain (**harness → orchestrator → agent → skill**) is Pattern 6 by construction. |
+ | 7 | Orchestrator's post-agent verification gates (see [`../agents/orchestrator.md`](../agents/orchestrator.md)). |
+
+ Pattern 4 (RAG) is not used and is not planned; the framework's
+ knowledge base is small enough that GATE-based loading handles it
+ without retrieval overhead.
+
+ ## Pattern 1: System Prompt Embedding
+
+ **How it works.** Rules are pasted directly into the system prompt so
+ the model always has them in context.
+
+ **Tradeoffs.** Maximum recall — the model never forgets what's in its
+ prompt. But it permanently uses up context window space on every run,
+ whether or not the rules are relevant. Doesn't scale past roughly two
+ skills' worth of content before it crowds out the memory Claude needs
+ for the actual task.
+
+ **Example in this framework.** `../CLAUDE.md` embeds harness orientation
+ directly: the layer hierarchy, the environment, the resource-priority
+ rule. Every framework session sees this content because the harness
+ loads CLAUDE.md automatically.
+
+ **When to use it:**
+
+ - Small, stable rule sets (under ~2,000 tokens, roughly 1,500 words).
+ - Rules needed on every run (routing, environment, output-format skeleton).
+ - Configuration that rarely changes.
+
+ **When to avoid it:**
+
+ - Large or growing knowledge bases.
+ - Rules that only apply to specific task types.
+ - Content that changes frequently (each edit means updating the prompt).
+
+ ## Pattern 2: Upfront Loading
+
+ **How it works.** The agent reads all its skill files at the start of
+ a run, before doing any work.
+
+ **Tradeoffs.** Simple to implement — just list the files to read in the
+ agent prompt. But it wastes memory on skills that may not be relevant,
+ and the content goes stale: by the time the agent reaches Step 8 and
+ needs formatting rules it read at Step 1, that content is far back in
+ the conversation and Claude pays less attention to it.
+
+ **Example in this framework.** The orchestrator's pre-flight loads the
+ initial-check pair upfront on every dispatch:
+
+ ```
+ Load before routing to the stage agent:
+ - skills/skill-framework-fitness/SKILL.md
+ - skills/skill-security-hygiene/SKILL.md
+ ```
+
+ These two skills apply to *every* framework artifact regardless of
+ pipeline, so paying the upfront cost is worth it — a GATE at every
+ possible decision point would be wasteful. Every other framework skill
+ is a candidate for Pattern 3 instead.
+
+ **When to use it:**
+
+ - Skills needed continuously throughout a short workflow.
+ - Small skill files (under ~1,000 tokens each).
+ - When context decay isn't an issue (workflows under ~10 steps).
+
+ **When to avoid it:**
+
+ - Long multi-step workflows (10+ steps) — content decays; use Pattern 3.
+ - Large skill files — pay the cost only at the step that needs them.
+ - When only a subset of rules applies to any given task.
+
+ **Failure mode this addresses.** An early version of a hypothetical
+ review agent could load ten skills at Step 1 (~4,000 lines total). By
+ Step 8, when it needs the output-format template, that template is
+ thousands of lines back in the conversation. The agent produces
+ plain-text output instead of Doc Team diff format — it has "forgotten"
+ the template it read at the start. Fix: switch that template to
+ Pattern 3 and load it at Step 8, right when the agent needs it.
+
+ ## Pattern 3: GATE-Based / Just-in-Time Loading
+
+ **This is the recommended default for framework agents.** Handles the
+ widest range of workflows.
+
+ **How it works.** The agent workflow defines explicit decision points
+ (GATEs) where the agent must stop, read a specific skill file, apply
+ it, and show evidence it followed the skill before continuing.
+
+ **Tradeoffs.** Efficient context use — only the relevant skill is in
+ working memory when it's applied. Fresh recall at the decision point.
+ Auditable, because the agent must cite evidence. But it requires more
+ complex prompt engineering: you design the workflow with explicit gates
+ and specify which skill maps to which step.
+
+ **Example shape for a new agent.** An agent definition that uses
+ Pattern 3 looks like this:
+
+ ```markdown
+ ## Design principle: skills at decision points
+
+ Do NOT load all skills upfront. Load the specific skill at the moment
+ you need it to make a decision. This keeps the skill fresh in context
+ when applied and forces you to follow the skill as a procedure rather
+ than from memory.
+
+ ### Step 4: Diagnose
+
+ **GATE — Read the skill matching the input type before proceeding.**
+
+ | Input type | Read this now |
+ |------------------|--------------------------------------------|
+ | {type A} | ../skills/skill-{name-a}/SKILL.md |
+ | {type B} | ../skills/skill-{name-b}/SKILL.md |
+
+ ### Step 8: Format output
+
+ **GATE — Read ../skills/skill-doc-diff/SKILL.md NOW.**
+ ```
+
+ Every GATE requires evidence: the agent produces a "Skills Loaded"
+ block, a validation output, a grep result, or a citation showing it
+ followed the skill.
+
+ **How to design a GATE-based agent:**
+
+ 1. Map the workflow as numbered steps.
+ 2. Identify which steps require reference material.
+ 3. For each step, name the exact skill file and section.
+ 4. Label those steps GATE.
+ 5. Require evidence (validation output, grep results, citations) that
+ the skill was followed.
+
+ **When to use it:**
+
+ - Multi-step workflows with distinct decision points.
+ - Large skill libraries where only two or three skills apply per task.
+ - When auditability matters — you need to prove rules were followed.
+ - Skills that change often; fresh reads pick up revisions.
+
+ **When to avoid it:**
+
+ - Simple single-step tasks.
+ - When the same skill is needed continuously (Pattern 2 is simpler).
+ - When Read-call overhead is a real concern.
+
+ ## Pattern 4: RAG / Retrieval-Augmented Generation
+
+ **Not used in this framework.**
+
+ **How it works.** An external search system (a vector database or
+ embedding index) finds the most relevant passages from a large
+ knowledge base at query time and injects them into the prompt.
+
+ **Tradeoffs.** Scales to enormous knowledge bases — thousands of pages,
+ multiple manuals, entire codebases. But you lose control over exactly
+ what gets retrieved and what surrounds it. Chunk boundaries may split
+ a rule in half. Retrieval relevance depends on embedding quality.
+
+ **Why the framework skips it.** The framework's knowledge base is
+ moderate — a small set of rule skills plus reference materials. GATE-
+ based loading handles that without RAG overhead. RAG also risks
+ retrieval that splits interdependent rules (rule R14 references rule
+ R15; a chunk missing the cross-reference is worse than no chunk).
+
+ **When to use it (elsewhere):**
+
+ - Very large knowledge bases (100+ documents, entire style guides).
+ - Questions where skills can't be pre-mapped to steps.
+ - When "good enough" recall is acceptable — combine with Pattern 7 to
+ catch retrieval errors.
+
+ ## Pattern 5: Tool-Based Lookup
+
+ **How it works.** Skills are exposed as callable tools — commands the
+ agent runs on demand, like reading a file, running a grep, or invoking
+ a binary. The agent decides when to invoke them.
+
+ **Tradeoffs.** The agent has autonomy to decide when to consult
+ references. Works well when the agent can reliably judge what it
+ doesn't know. The risk is skipping: if the tool isn't forced, the agent
+ may not call it, especially under time pressure or with simpler models.
+
+ **How it differs from Pattern 3 (GATE-Based):**
+
+ | Aspect | GATE-Based | Tool-Based |
+ |--------------|-------------------------------|-------------------------------|
+ | Who decides | Prompt designer | Agent (the model) |
+ | When loaded | At predefined workflow steps | When the agent chooses |
+ | Guarantee | Mandatory (GATE = must read) | Optional (agent may skip) |
+ | Flexibility | Fixed workflow | Adaptive to novel tasks |
+
+ **Example in this framework.** A prose-linting workflow that
+ delegates to Vale would live in [`../tools/`](../tools/) — for
+ example, `../tools/vale/` with a `run-vale.sh` wrapper. A skill that
+ loads Vale via Pattern 5 would say: *"When you reach a prose-check
+ step, call `../tools/vale/run-vale.sh` on the target file and enumerate
+ findings."* Same shape for an ImageMagick verifier or a Mermaid
+ renderer. No tool ships in the framework yet; `tools/` is empty.
+
+ **When to use it:**
+
+ - Exploratory tasks where the reference isn't predictable.
+ - When the agent model is strong enough to self-direct (Opus-class).
+ - As a supplement to Pattern 3 for edge cases.
+ - General-purpose agents (not domain-specific workflows).
+
+ **When to avoid it:**
+
+ - Compliance-critical workflows — the agent might skip a required check.
+ - Smaller models that may not reliably self-direct.
+ - When you need auditable proof every rule was consulted.
+
+ ## Pattern 6: Hierarchical / Cascading Prompts
+
+ **How it works.** Knowledge is split across layers. A base system
+ prompt, a task-specific agent prompt, and per-step skill files. Each
+ layer contains only what's relevant at that level.
+
+ **Example in this framework — the four-layer chain:**
+
+ ```
+ Layer 1 — Harness (../CLAUDE.md, ~2,500 tokens)
+ Dispatch rules, environment, resource priority.
+ Always in context.
+
+ Layer 2 — Orchestrator (../agents/orchestrator.md, ~4,000 tokens)
+ Pipeline routing, pre-flight, initial check, verification gates.
+ Loaded when framework work is dispatched.
+
+ Layer 3 — Stage agent (../agents/{name}.md, ~2,000-3,000 tokens)
+ Workflow steps, skill-to-step mapping, input handling.
+ Loaded when the orchestrator routes to it.
+
+ Layer 4 — Skill (../skills/{skill-name}/SKILL.md, ~2,000-5,000 tokens each)
+ Detailed rules, examples, reference tables.
+ Loaded at GATE points inside the stage agent.
+ ```
+
+ The harness does not need to know pipeline-specific dispatch details.
+ The stage agent does not need to know the dispatch logic for other
+ agents. Each layer sees only what it needs.
+
+ **When to use it:**
+
+ - Multi-agent systems with an orchestrator.
+ - When different tasks need different subsets of knowledge.
+ - When you want to separate "what to do" from "how to do it."
+
+ **When to avoid it:**
+
+ - Single-agent systems — the layering adds complexity for no benefit.
+ - When all knowledge is needed at every layer.
+
+ ## Pattern 7: Multi-Agent Verification
+
+ **How it works.** A second pass (or a second agent) checks the first
+ agent's output against the knowledge base. The reviewer catches errors
+ the generator missed.
+
+ **Example in this framework — the orchestrator's post-agent verification.**
+ After every stage-agent run, the orchestrator performs independent
+ checks before presenting results:
+
+ ```markdown
+ ## Orchestrator Verification
+ - [x/!] Public/private API: {header}, {export macro}, {conclusion}
+ - [x/!] \since: {commit} in {tag} (or: agent inferred — REJECT)
+ - [x/!] Output filename: {algorithm result} matches agent's field
+ - [x/!] Source text: line numbers match actual file
+ - [x/!] Proposed fix compliance: {any rule violations found}
+ ```
+
+ Each agent declares its own gate list in its definition file; the
+ orchestrator runs those gates independently. The rule: if the agent's
+ output has errors, regenerate corrected suggestions rather than
+ listing errors alongside the flawed output.
+
+ This catches a specific failure mode: fixes that address one issue but
+ introduce another (fixing passive voice while adding wordiness, fixing
+ grammar while breaking line length).
+
+ **When to use it:**
+
+ - High-stakes outputs where errors have real cost (published docs,
+ code patches, compliance reports).
+ - When the generator agent has known blind spots.
+ - When verification criteria are concrete and checkable.
+
+ **When to avoid it:**
+
+ - Low-stakes tasks where speed matters more than precision.
+ - When verification criteria are subjective.