From 28c76a76d4a3ce9c34bb40f30f05fc73c4a3b9f3 Mon Sep 17 00:00:00 2001 From: Ollie Agent Date: Thu, 20 Aug 2026 17:45:29 +0200 Subject: [PATCH] Record architecture over prompting lesson --- doc/lessons-learned.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/lessons-learned.md b/doc/lessons-learned.md index e84f6a2..df48ca9 100644 --- a/doc/lessons-learned.md +++ b/doc/lessons-learned.md @@ -22,6 +22,24 @@ pre-optimizer for the model's action space: it narrows the likely useful capabilities while leaving final selection, tool loading, argument generation, and execution to the normal agent loop. +## Architecture beats prompting alone + +The larger lesson is that reliable agent behavior cannot be achieved by prompt +wording alone. Prompting tells the model what behavior is desired, but it does +not reliably solve capability discovery for smaller models. The local embedding +model and injected user-facing guidance work together as runtime architecture: + +- embeddings select the relevant capabilities before generation; +- injected prompts explain how and when to use those capabilities; +- bounded tool and skill disclosure preserves context for the task; +- the agent loop and toolsrv enforce the resulting execution path. + +This combination moves behavior that would otherwise require repeated model +reasoning into deterministic runtime preparation. The model still decides and +acts, but it starts with the right capabilities and explicit operational +instructions. In practice, this is more effective than adding more prompt text +or expecting a small model to discover the complete tool surface unaided. + ## Progressive disclosure beats a complete catalog Injecting every tool and skill into every prompt consumes context and makes