feat: constrain agent questions to user-friendly abstraction level (#13)

Agents and gap analyzer were asking overly technical questions like
"What are the precise X, Y, Z coordinates for the M4 mounting holes?"
— details only a CAD engineer would know. Users describe intent; agents
should derive the technical parameters.

- Add question abstraction rules to gap analyzer system prompt
- Apply CrewAI system_template on advisory agents (design, engineering,
cnc) via {{ .System }} / {{ .Prompt }} to preserve default behaviour
while injecting question-level guidance
- Improve part name extraction patterns in DesignState

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

agents/agent_flow.py

@@ -28,6 +28,31 @@ logger = logging.getLogger(__name__)
 WIKI_DIR = Path(__file__).parent.parent / "docs" / "wiki"
 
 
+# ── CrewAI prompt templates ─────────────────────────────────────────────────
+# Applied via CrewAI's system_template / prompt_template on advisory agents.
+# {{ .System }} expands to the default system slices (role_playing + tools);
+# {{ .Prompt }} expands to the task slice.  This preserves all default CrewAI
+# behaviour (tool-use format, etc.) while injecting question-level guidance.
+
+_ADVISOR_SYSTEM_TEMPLATE = """\
+{{ .System }}
+
+## Question Guidelines
+When asking the user clarifying questions, follow these rules strictly:
+- Ask questions a normal person can answer. The user describes INTENT; you derive the technical details.
+- NEVER ask for exact coordinates, precise radii, specific tolerance values, or CAD-level parameters.
+- Frame questions in everyday language and offer 2-4 plain-language suggestions.
+- GOOD: "Where should the mounting holes go?" → "one in each corner", "evenly spaced along edges"
+- BAD:  "What are the precise X, Y, Z coordinates for the M4 mounting holes?"
+- GOOD: "How thick should the walls be?" → "thin (1-2mm)", "standard (3-5mm)", "heavy-duty (6mm+)"
+- BAD:  "What is the minimum wall thickness in mm for the vertical ribs?"
+- GOOD: "Should the edges be sharp or rounded?"
+- BAD:  "What fillet radius should be applied to the internal pocket edges?"
+- You are the expert — infer technical parameters from the user's high-level answer."""
+
+_ADVISOR_PROMPT_TEMPLATE = "{{ .Prompt }}"
+
+
 # ── Data models ───────────────────────────────────────────────────────────────
 
 
@@ -400,6 +425,9 @@ class AgentDispatchFlow(Flow[AgentFlowState]):
 
         knowledge_sources = self._build_knowledge_sources() if agent_id in ("cnc", "cam") else []
 
+        # Advisory agents get system_template with question-abstraction
+        # guidance via CrewAI's prompt customisation (see _ADVISOR_SYSTEM_TEMPLATE).
+        is_advisor = agent_id in ADVISOR_IDS
         crew_agent = Agent(
             role=agent_def.role,
             goal=agent_def.goal,
@@ -407,8 +435,10 @@ class AgentDispatchFlow(Flow[AgentFlowState]):
             llm=llm,
             tools=tools,
             verbose=False,
-            allow_delegation=settings.crew.collaboration and agent_id in ADVISOR_IDS,
+            allow_delegation=settings.crew.collaboration and is_advisor,
             knowledge_sources=knowledge_sources if knowledge_sources else None,
+            system_template=_ADVISOR_SYSTEM_TEMPLATE if is_advisor else None,
+            prompt_template=_ADVISOR_PROMPT_TEMPLATE if is_advisor else None,
         )
 
         memories = self._recall_for_agent(agent_id)

agents/design_state.py

@@ -240,7 +240,9 @@ class DesignState(BaseModel):
         # Extract part name from user message if not set
         if not state.part_name and user_message:
             name_patterns = [
-                r'(?:need|want|design|make|create)\s+(?:a|an)\s+(.{5,40}?)\s*(?:with|for|that|,|$)',
+                r'(?:need|want|design|make|create|build|model)\s+(?:a|an|the)\s+(.{3,40}?)\s*(?:with|for|that|using|,|\.|$)',
+                r'(?:need|want|design|make|create|build|model)\s+(.{3,40}?)\s*(?:with|for|that|using|,|\.|$)',
+                r"(?:i'm|i am)\s+(?:building|making|designing)\s+(?:a|an|the)\s+(.{3,40}?)\s*(?:with|for|that|using|,|\.|$)",
             ]
             for pattern in name_patterns:
                 match = re.search(pattern, user_message, re.IGNORECASE)

agents/gap_analyzer.py

@@ -62,6 +62,8 @@ what information is still missing to produce a complete CNC-ready design.
 Rules:
 - Do NOT flag gaps for information already present in the design state.
 - Do NOT flag gaps for information the user just provided in their message.
+- Do NOT ask about the part name — the system derives it automatically.
+- Do NOT repeat questions that were already asked in previous turns.
 - Invent descriptive category names (e.g. "bolt_pattern", "thermal_rating",
   "load_capacity") — there is no fixed set.
 - Use snake_case for category names.
@@ -73,6 +75,25 @@ Rules:
   "design", "engineering", "cnc", "cad", or "cam".
 - If no gaps exist, return has_gaps: false with empty lists.
 - Set severity on each question card matching the gap it addresses.
+
+Question abstraction level — CRITICAL:
+- Ask questions a normal person can answer, NOT questions requiring CAD or
+  engineering expertise. The user describes INTENT; the agents derive the
+  technical implementation.
+- NEVER ask for exact coordinates, precise radii, specific tolerance values,
+  G-code parameters, or CadQuery implementation details.
+- GOOD: "Where should the mounting holes go?" with suggestions like
+  "one in each corner", "evenly spaced along the edges", "centered on top".
+- BAD: "What are the precise X, Y, Z coordinates for the M4 mounting holes?"
+- GOOD: "Should the edges be sharp or rounded?"
+- BAD: "What fillet radius should be applied to the internal pocket edges?"
+- GOOD: "How thick should the walls be?" with suggestions like "thin
+  (1-2mm)", "standard (3-5mm)", "heavy-duty (6mm+)".
+- BAD: "What is the minimum wall thickness in mm for the vertical ribs?"
+- Frame questions in everyday language. Offer 2-4 plain-language suggestions
+  that map to concrete engineering values behind the scenes.
+- Technical details (coordinates, exact radii, tolerance classes, feed rates)
+  are the agents' job to determine from the user's high-level answers.
 """