Template Division Best Practices

Overview

This document defines best practices and patterns for creating well-structured divisions in Thalabus templates, particularly divisions that use the QueryExecutor tool for systematic case analysis. These patterns ensure that agents can execute queries effectively and generate consistent, high-quality analytical output.

Reference Example

The similar_cases_country_of_origin division (sequence 301) in PythonServer/Examples/Template_UseCase_Asylum.xml serves as the canonical reference implementation of these best practices.

Division Structure

A well-designed division contains multiple <instructions> blocks, each targeting a specific processing state. Each instruction block must be self-contained because agents can only see one instruction block at a time.

Required Instruction Blocks

<instructions for_status="open"> - Primary query execution instructions
<instructions for_status="compiling summary"> - Summary generation guidelines (plain text)
<instructions for_status="compiling issues"> - Issue identification guidelines (JSON)
<instructions for_status="compiling recommendations"> - Recommendation generation guidelines (JSON)
<instructions for_status="in review"> - Review and refinement instructions

Division Lifecycle and Status Transitions

Complete Workflow State Machine

Each division progresses through a defined lifecycle managed by the ReasoningStatus enum:

┌─────────────────┐
│  OPEN           │ ← Initial state
│  ("open")       │
└────────┬────────┘
         │ JSON: {"optional_new_tasks": [...]}
         ↓
┌─────────────────┐
│  IN PROGRESS    │ ← Automatic (no instructions)
│  ("in progress")│   Tasks are being executed
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│ COMPILING       │ ← Summary compilation
│ SUMMARY         │   Plain text prose summary only
│ ("compiling     │
│   summary")     │
└────────┬────────┘
         │ Output: Summary text (prose/markdown)
         ↓
┌─────────────────┐
│ COMPILING       │ ← Issue identification
│ ISSUES          │   Structured list of issues
│ ("compiling     │
│   issues")      │
└────────┬────────┘
         │ JSON: {"optional_issues": [...]}
         ↓
┌─────────────────┐
│ COMPILING       │ ← Recommendations generation
│ RECOMMENDATIONS │   Structured recommendations
│ ("compiling     │   and focus content settings
│  recommendations│
│     ")          │
└────────┬────────┘
         │ JSON: {
         │   "optional_recommendations": [...],
         │   "optional_focus_content_id": [...],
         │   "optional_split_to_chunks": false
         │ }
         ↓
┌─────────────────┐
│  IN REVIEW      │ ← Quality assessment
│  ("in review")  │
└────────┬────────┘
         │ JSON: {
         │   "internal_thoughts": "...",
         │   "optional_new_tasks": [...]
         │ }
         ↓
    Decision Point:
    ┌─────────────┴─────────────┐
    │                           │
    ↓ (if refinement needed)    ↓ (if complete)
┌─────────────────┐      ┌─────────────────┐
│ COMPILING       │      │  COMPLETE       │
│ SUMMARY         │      │  ("complete")   │
│ (revisit)       │      └─────────────────┘
└────────┬────────┘
         │
         ↓
    (returns to IN REVIEW)

Status-Specific Output Requirements

Status: "open"

Instructions Used: <instructions for_status="open">
Output Format: JSON only
JSON Schema: REASONING_COMMAND_FOR_STATUS_OPEN_JSON json { "optional_new_tasks": ["task description 1", "task description 2"] }
Fields:
optional_new_tasks (optional): Array of task descriptions to be created

Status: "in progress"

Instructions Used: None (automatic state)
Agent Behavior: Executes tasks created in "open" status
Output: Task execution results are stored internally
Transition: Automatically moves to "compiling summary" when all tasks complete

Status: "compiling summary"

Instructions Used: <instructions for_status="compiling summary">
Output Format: Plain text prose/markdown only
Purpose: Generates the actual summary text based on division instructions
Content: No JSON structure, pure narrative summary
Next Status: Automatically advances to "compiling issues"

Status: "compiling issues"

Instructions Used: <instructions for_status="compiling issues">
Output Format: JSON only
JSON Schema: REASONING_COMMAND_FOR_STATUS_COMPILING_ISSUES_JSON json { "optional_issues": [{ "issue_id": "i-<id>", "description": "Issue description", "severity": "low|medium|high", "status": "open|in progress|closed" }] }
Fields:
optional_issues (required array, can be empty): Outstanding issues found
Next Status: Automatically advances to "compiling recommendations"

Status: "compiling recommendations"

Instructions Used: <instructions for_status="compiling recommendations">
Output Format: JSON only
JSON Schema: REASONING_COMMAND_FOR_STATUS_COMPILING_RECOMMENDATIONS_JSON json { "optional_recommendations": ["recommendation 1", "recommendation 2"], "optional_focus_content_id": ["docid-1", "docid-2"], "optional_split_to_chunks": false }
Fields:
optional_recommendations (required array, can be empty): Recommendations for improvement
optional_focus_content_id (required array, can be empty): Document IDs for focused review
optional_split_to_chunks (required boolean): Whether to split summary into chunks
Next Status: Automatically advances to "in review"

Status: "in review"

Instructions Used: <instructions for_status="in review">
Output Format: JSON only
JSON Schema: REASONING_COMMAND_FOR_STATUS_IN_REVIEW_JSON json { "internal_thoughts": "Analysis of results and reasoning...", "optional_new_tasks": ["refinement task 1", "refinement task 2"] }
Fields:
internal_thoughts (optional): Reasoning about result quality and needs
optional_new_tasks (optional): Array of refinement tasks if results are insufficient

Status: "complete"

Instructions Used: None
Agent Behavior: Division is finished, no further processing
Output: None

Critical Instruction Design Implications

DO: - ✅ In "open" instructions: Focus on query construction and decision-making logic - ✅ In "compiling summary" instructions: Focus on how to structure the prose summary - ✅ In "compiling issues" instructions: Focus on what constitutes an issue and severity criteria - ✅ In "compiling recommendations" instructions: Focus on actionable recommendations and focus content selection - ✅ In "in review" instructions: Focus on quality assessment criteria and refinement strategies

DON'T: - ❌ In "open" instructions: Don't reference optional_issues or optional_recommendations (wrong status) - ❌ In "compiling summary" instructions: Don't reference JSON fields (prose only) - ❌ In "compiling issues" instructions: Don't reference optional_recommendations (wrong status) - ❌ In "compiling recommendations" instructions: Don't reference optional_issues (wrong status) - ❌ In "in review" instructions: Don't instruct prose output generation (JSON only) - ❌ In any status: Don't reference JSON fields that don't exist in that status's schema

Optional Instructions and Edge Case Handling

All Instructions Are Optional

Critical Design Principle: Every <instructions for_status="..."> block is optional. A template may omit any or all instruction blocks for any status.

Agent Behavior When Instructions Are Missing: 1. Immediate State Advancement: If no instructions exist for the current status, the agent automatically advances to the next status without leaving AgentDeepReasoning 2. While Loop Pattern: The _process_division() method uses a while loop to handle consecutive missing instructions in a single pass 3. No External Re-entry: Missing instructions don't require exiting the agent and re-entering - transitions happen internally

Implementation Details: - Each state transition method checks for missing instructions using self._skip_division(division) - If instructions are missing: logs INFO message, advances to next_status(), and sets more_planning_required = True - The while loop continues until either instructions are found or the division reaches COMPLETE status

LLM Failure Handling

Critical Robustness Principle: The LLM may return None, wrong data types, missing JSON fields, or malformed data. All state transition methods handle these gracefully.

Error Handling Patterns: 1. None Result Check: if result is None: → use safe defaults and advance to next status 2. Type Validation: if not isinstance(result, dict): → use safe defaults and advance 3. Missing Key Handling: result.get('field', default_value) with safe fallbacks 4. Exception Catching: Try-except blocks around all LLM calls with automatic status advancement

Behavior on LLM Failure: - Logs WARNING message with details - Uses safe default values (empty arrays, False for booleans, empty strings) - Advances to next status automatically using ReasoningStatus.next_status(div_status) - Sets more_planning_required = True to allow for potential recovery in later states - Never gets stuck in a loop - always makes forward progress

Example Default Values:

# For compiling summary
summary = ""  # Empty summary on failure

# For compiling issues
issues = []  # Empty issues list on failure

# For compiling recommendations
recommendations = []
focus_content_id = []
split_to_chunks = False

State Transition Method Structure

Each state transition method (_process_division_compiling_summary, _process_division_compiling_issues, _process_division_compiling_recommendations) follows this robust pattern:

def _process_division_<status>(self, division, ...):
    # 1. Check for missing instructions
    if not instructions_exist:
        log(INFO, "No instructions for status <status>")
        next_status = ReasoningStatus.next_status(div_status)
        division.set_status(next_status)
        more_planning_required = True
        return {"skipped": True}

    # 2. Call LLM with try-except
    try:
        result = self._call_llm(...)

        # 3. Validate result
        if result is None or not isinstance(result, dict):
            # Use defaults and advance
            log(WARNING, "LLM returned invalid result")
            <use_safe_defaults>
        else:
            # Extract fields with safe fallbacks
            field1 = result.get('field1', default1)
            field2 = result.get('field2', default2)

        # 4. Update division and advance
        <update_division_with_results>
        next_status = ReasoningStatus.next_status(div_status)
        division.set_status(next_status)
        more_planning_required = True

    except Exception as e:
        # 5. Handle exceptions gracefully
        log(WARNING, f"Exception during <status>: {e}")
        next_status = ReasoningStatus.next_status(div_status)
        division.set_status(next_status)
        more_planning_required = True

    return reasoning_result

Key Robustness Features: - ✅ Handles missing instructions (immediate advancement) - ✅ Handles None results (safe defaults + advancement) - ✅ Handles wrong types (safe defaults + advancement) - ✅ Handles missing dict keys (.get() with defaults) - ✅ Handles exceptions (catch-all + advancement) - ✅ Never gets stuck (always advances to next status) - ✅ Logs all edge cases for debugging

1. Instructions for Status="open"

Output Format: JSON only - {"optional_new_tasks": ["..."]}

This is the primary instruction block where agents execute queries and gather data. The agent outputs a JSON structure indicating any new tasks to create, not prose output.

1.1 Structure and Components

A. Header Section

Tool Recommendation

<instructions for_status="open" recommended_tools="+QueryExecutor">

Use recommended_tools="+QueryExecutor" to indicate this division requires the QueryExecutor tool
The + prefix signals addition to available tools

Opening Statement

Use the QueryExecutor tool with the thalabus query language to identify asylum cases
that are genuinely comparable to the current case, using [PRIMARY DIMENSION] as the
primary similarity axis and [SECONDARY CHARACTERISTICS] as similarity anchors.

Clearly state which tool to use
Define the primary dimension of analysis
Identify what makes cases "comparable"

B. Dimension Objective

Purpose: Defines the analytical goal specific to this division's focus area.

Pattern:

**Dimension objective:**
[Describe what precedents or patterns this division aims to identify]
[Explain what makes this dimension unique from other divisions]
[State the intended use of the findings]

Example:

**Dimension objective:**
Identify precedents involving applicants from the same or closely related countries
who present a comparable legal and procedural profile, in order to extract relevant
reasoning patterns and outcomes.

Key Principles: - Be specific about the dimension being analyzed - Explain why this dimension matters for the overall analysis - Keep it focused (one clear goal per division)

C. Similarity Principle / Matching Criteria

Purpose: Defines what makes a case "similar" or "comparable" within this dimension.

Pattern:

**Similarity principle (mandatory):**
A case is considered "similar" only if it matches:
- [PRIMARY CRITERION], AND
- [SECONDARY CRITERION(S)]

Example:

**Similarity principle (mandatory):**
A case is considered "similar" only if it matches:
- the same (or closely related) COUNTRY_OF_ORIGIN, AND
- at least one additional core characteristic of the current case.

Key Principles: - Use AND logic to ensure meaningful similarity - Avoid overly broad matches (e.g., don't accept just one category match) - Make it mandatory to prevent weak results

D. Query Construction Rules

Purpose: Provides step-by-step instructions for building valid queries.

Pattern:

**Query construction rules:**
1. Extract [PRIMARY_CATEGORY] from the current case (mandatory).
2. Identify one or more of the following characteristics if already known at this stage:
   - [CHARACTERISTIC_1]
   - [CHARACTERISTIC_2]
   - [CHARACTERISTIC_3]
3. Only use category names and approved values defined in the [ONTOLOGY] categories CSV.
4. Do not use free-form inference or placeholders.
5. [Additional rules specific to this dimension]

Key Principles: - Number the rules for clarity - Start with what's mandatory - Reference the ontology/CSV explicitly - Prohibit unsupported values or free-form text - Include dimension-specific guidance

E. Example Queries

Purpose: Provides concrete query examples showing progression from specific to broader.

Pattern:

**Queries to execute (progressive, from most specific to broader):**

- Query 1 (mandatory, focused similarity):
  [SPECIFIC QUERY WITH MULTIPLE CRITERIA]

- Query 2 (conditional, [condition explanation]):
  [ALTERNATIVE QUERY OR BROADER VARIANT]
  OR
  [ANOTHER ALTERNATIVE]

- Query 3 (optional, [when to use]):
  [EVEN BROADER BUT STILL ANCHORED QUERY]

Example:

**Queries to execute (progressive, from most specific to broader):**

- Query 1 (mandatory, focused similarity):
  COUNTRY_OF_ORIGIN=COUNTRY_CODE AND PROCEDURAL_STAGE=STAGE_VALUE

- Query 2 (conditional, Dublin or admissibility anchoring):
  COUNTRY_OF_ORIGIN=COUNTRY_CODE AND DUBLIN_PROCEDURE=TRUE
  OR
  COUNTRY_OF_ORIGIN=COUNTRY_CODE AND ADMISSIBILITY=VALUE

- Query 3 (optional, regional but still anchored):
  COUNTRY_OF_ORIGIN=COUNTRY_CODE_1,COUNTRY_CODE_2,COUNTRY_CODE_3
  AND PROCEDURAL_STAGE=STAGE_VALUE

Key Principles: - Label each query (mandatory/conditional/optional) - Explain when to use each variant - Progress from specific to broader but maintain similarity principle - Use placeholders in UPPER_CASE to indicate values to extract

F. Important Warnings

Purpose: Prevent common mistakes or overly broad queries.

Pattern:

**Important:**
Do NOT [describe what should be avoided]
[Explain why this restriction matters]

Example:

**Important:**
Do NOT execute a query that contains only COUNTRY_OF_ORIGIN without at least one
additional legal or procedural constraint.

G. Execution Instructions

Purpose: Specifies exact parameters for QueryExecutor tool calls.

Pattern:

**Execution instructions:**
- For each constructed query, call QueryExecutor with:
  - query: the constructed query string
  - ontology_id: "[ONTOLOGY_NAME]"
  - generate_pretty: true
  - limit: [NUMBER]
  - min_score: [THRESHOLD]
  - instructions_to_report:
    Use the following text as the value for the QueryExecutor's instructions_to_report parameter. Copy it exactly as given here.
    This text instructs the LLM analyzing the RAG results on how to generate its report:

    "[DETAILED INSTRUCTIONS FOR LLM - SEE SECTION 1.2 BELOW]"

Key Principles: - Specify ALL parameters explicitly - Use limit appropriate for the analysis (typically 2-6) - Set min_score based on expected quality (0.2-0.6 typical range) - Set generate_pretty: true for formatted output - Always include instructions_to_report for LLM guidance

Parameter Guidelines: - limit: Number of documents to retrieve per query - Use 2-3 for highly specific queries - Use 4-6 for broader exploratory queries - Remember: This is per query, not total - min_score: Minimum relevance score (0.0 to 1.0) - 0.6+: Very high relevance (restrictive) - 0.3-0.5: Moderate relevance (balanced) - 0.1-0.2: Lower threshold (exploratory) - ontology_id: The ontology name (e.g., "Juris", "FictionalStories") - generate_pretty: Set to true for markdown formatted output

1.2 Instructions to Report

Purpose: Guides the LLM that analyzes retrieved fragments on how to generate reports.

Critical Principle: Since agents cannot see the division's context when executing the tool, all necessary guidance must be embedded in instructions_to_report.

Pattern:

"**Dimension objective for this analysis:**
 [Restate the dimension objective from the division]

 **For each retrieved case, provide:**
 - [What to extract from the case]
 - [What to analyze]
 - [What patterns to identify]
 - [What similarities/differences to note]

 **Requirements:**
 - [Output format requirements]
 - [Quality standards]
 - [Specific formatting (e.g., title format)]"

Example:

"**Dimension objective for this analysis:**
 Identify precedents involving applicants from the same or closely related countries
 who present a comparable legal and procedural profile. Extract relevant reasoning
 patterns and outcomes specific to country-of-origin cases with similar procedural
 or legal characteristics.

 **For each retrieved case, provide:**
 - A case-specific summary of the legal reasoning applied
 - The outcome or decision reached
 - Any patterns relevant to country-of-origin risk assessment
 - Procedural or substantive similarities to the query parameters

 **Requirements:**
 - Do not generalize beyond the specific decision retrieved
 - Maintain case-by-case distinction in your analysis
 - Use this title format for each case (example for DECISION_ID=D-1234/2010):
   **Summary of the Findings (Swiss Federal Administrative Court - Decision D-1234/2010)**"

Key Principles: - Restate the dimension objective - The LLM needs context - Be specific about what to extract - Don't assume the LLM knows - Require case-by-case analysis - Prevent inappropriate generalization - Provide title format - Ensure consistent output structure - Set quality standards - E.g., "do not generalize", "maintain distinctions"

H. Constraints

Purpose: Final warnings or limitations specific to this dimension.

Pattern:

**Constraints:**
- [Constraint about data handling]
- [Constraint about interpretation]
- [Constraint about reporting]

Example:

**Constraints:**
- Do not merge findings across cases.
- Do not generalize beyond retrieved decisions.
- Explicitly state when similarity is limited due to missing matching characteristics.

I. Task Management (Optional)

Purpose: Guide the LLM on when to create new tasks via the optional_new_tasks JSON field.

Critical Architecture Note: The "open" status outputs JSON: {"optional_new_tasks": ["..."]}. Task creation happens through this JSON structure, not through prose output.

When to Create Tasks: - When additional analysis dimensions are discovered during query execution - When follow-up research is needed that falls outside current division scope - When data quality issues require additional queries or verification

When NOT to Create Tasks: - ❌ To "update" or "compile" summaries - this happens automatically on status transition - ❌ To document findings - this is not applicable to JSON output statuses - ❌ For routine query extensions - use "in review" status workflow instead

Key Principles: - Task creation is optional and should be used sparingly - Focus tasks on genuinely new work, not workflow steps - Summary compilation is status-driven, not task-driven - The agent's primary role in "open" status is query execution

2. Instructions for Status="compiling summary"

Output Format: Plain text prose/markdown only

Purpose: Guides the agent on how to synthesize findings into a coherent narrative summary.

Pattern:

<instructions for_status="compiling summary">
Write a short analytical summary titled
"[TITLE OF SUMMARY]".

The summary must include:
- [Required element 1]
- [Required element 2]
- [Required element 3]
- [Required element 4]
- [Explicit statement about edge cases]
</instructions>

Example:

<instructions for_status="compiling summary">
Write a short analytical summary titled
"Summary of similar cases by country of origin".

The summary must include:
- Number of genuinely comparable cases found
- Which similarity anchors were applied (e.g. procedure, admissibility)
- Countries represented
- Recurring legal reasoning patterns
- Explicit statement if no sufficiently similar cases were found
</instructions>

Key Principles: - Provide an exact title - List required elements as bullet points - Include quantitative elements (counts, numbers) - Include qualitative elements (patterns, reasoning) - Require explicit statements about edge cases (e.g., "if no cases found") - Focus purely on narrative content, not JSON structure

2a. Instructions for Status="compiling issues"

Output Format: JSON only - {"optional_issues": [...]}

Purpose: Guides the agent on identifying and structuring issues found during the analysis.

Pattern:

<instructions for_status="compiling issues">
Review the query execution results and identify any issues that need to be reported
to the user regarding [specific aspect of this division].

**Identify issues such as:**
- [Issue type 1]
- [Issue type 2]
- [Issue type 3]

**For each issue identified:**
- Assign a unique issue_id in format "i-<division_id>-<number>"
- Provide a clear description of the issue
- Set appropriate severity: "low", "medium", or "high"
- Set initial status as "open"

**Note:** If no issues are found, return an empty list.
</instructions>

Example:

<instructions for_status="compiling issues">
Review the query execution results and identify any issues that need to be reported
to the user regarding the search for similar cases by country of origin.

**Identify issues such as:**
- Insufficient number of comparable cases found (fewer than 3)
- Cases lack meaningful similarity anchors
- Query constraints were too restrictive or too broad
- Missing or incomplete category values
- Technical errors during query execution

**For each issue identified:**
- Assign a unique issue_id in format "i-similar_cases_country_of_origin-1"
- Provide a clear description of the issue
- Set appropriate severity: "low", "medium", or "high"
- Set initial status as "open"

**Note:** If no issues are found, return an empty list.
</instructions>

Key Principles: - Define what constitutes an issue for this specific division - Provide concrete examples of issue types - Specify the severity criteria - Allow for empty list (no issues is valid) - Focus on problems/concerns, not solutions (those go in recommendations)

2b. Instructions for Status="compiling recommendations"

Output Format: JSON only - {"optional_recommendations": [...], "optional_focus_content_id": [...], "optional_split_to_chunks": false}

Purpose: Guides the agent on generating actionable recommendations and setting focus content for next divisions.

Pattern:

<instructions for_status="compiling recommendations">
Based on the query execution results and any identified issues, provide recommendations
for [specific goal of this division].

**Recommendations may include:**
- [Recommendation type 1]
- [Recommendation type 2]
- [Recommendation type 3]

**Note:** Each recommendation should be a clear, actionable statement. If no recommendations
are needed, return an empty list.
</instructions>

Example:

<instructions for_status="compiling recommendations">
Based on the query execution results and any identified issues, provide recommendations
for improving the analysis of similar cases by country of origin.

**Recommendations may include:**
- Suggestions to broaden or narrow search parameters
- Alternative similarity anchors to try
- Additional queries that could provide better results
- Manual review suggestions for specific cases
- Adjustments to min_score or other query parameters

**Note:** Each recommendation should be a clear, actionable statement. If no recommendations
are needed, return an empty list.
</instructions>

Key Principles: - Provide actionable, specific recommendations - Focus on solutions and next steps - Allow for empty list (no recommendations is valid) - Keep recommendations focused on the division's objective - Each recommendation should be independently understandable

3. Instructions for Status="in review"

Output Format: JSON only - {"internal_thoughts": "...", "optional_new_tasks": ["..."]}

Purpose: Enables agents to assess result quality and decide whether refinement queries are needed. The agent outputs a JSON structure with internal reasoning and any additional tasks, not prose output.

Critical Architecture Principle

Agents see only one instruction block at a time. The "in review" instructions cannot reference or rely on the "open" instructions. Therefore, you must repeat all essential information needed for query construction and execution.

3.1 Structure and Components

A. Review Mandate

Review the compiled summary for this division. Ensure it accurately reflects the
findings from the QueryExecutor results and adheres to the specified requirements.

Furthermore: if the queries have not returned a sufficient number of results, execute
additional queries using the extension strategies defined below.

Output Expectation: The agent will analyze the results and output JSON with: - internal_thoughts: Reasoning about whether results are sufficient - optional_new_tasks: Empty array if results are adequate, or array of refinement tasks if not

B. Assessment Criteria

Purpose: Defines when results are insufficient and action is needed.

Pattern:

**Assessment criteria for result sufficiency:**
Results are considered insufficient if:
- [Quantitative criterion - e.g., fewer than X cases]
- [Quality criterion - e.g., lack of meaningful similarity]
- [Analytical criterion - e.g., cannot identify patterns]
- [Edge case criterion - e.g., no results despite clear characteristics]

Example:

**Assessment criteria for result sufficiency:**
Results are considered insufficient if:
- Fewer than 3 genuinely comparable cases were found across all queries
- The returned cases lack meaningful similarity anchors (only country match, no legal/procedural overlap)
- The compiled summary cannot identify any recurring legal reasoning patterns
- No cases were found despite the current case having clear procedural or legal characteristics

C. Trigger for Additional Queries

**When to execute additional queries:**
Execute additional queries if the criteria above indicate insufficient results AND
at least one of the following extension strategies is applicable.

D. Query Extension Strategies

Purpose: Provides concrete strategies for broadening the search while maintaining quality.

Pattern:

**Query extension strategies (apply within dimension objective only):**

Strategy 1: [Strategy name]
- [How to apply it]
- [What to maintain]
- [When to use]

Strategy 2: [Strategy name]
- [How to apply it]
- [Example]

[Continue for each strategy]

Example:

**Query extension strategies (apply within dimension objective only):**

Strategy 1: Lower the similarity threshold
- Reduce min_score from 0.6 to 0.5 or 0.45
- Keep the same query structure and similarity anchors
- Use when the query logic is sound but scoring is too strict

Strategy 2: Broaden regional scope
- Expand COUNTRY_OF_ORIGIN to include neighboring or culturally related countries
- MUST maintain at least one procedural or legal anchor
- Example: COUNTRY_OF_ORIGIN=AFG,IRN,PAK AND PROCEDURAL_STAGE=VALUE

Strategy 3: Use alternative similarity anchors
- If PROCEDURAL_STAGE yielded no results, try REFUGEE_GROUNDS
- If DUBLIN_PROCEDURE yielded no results, try ADMISSIBILITY
- Replace one anchor with another, do not remove all anchors

Strategy 4: Combine semantic and categorical search
- Add semantic terms to an existing categorical query
- Example: "asylum application" AND COUNTRY_OF_ORIGIN=VALUE

Key Principles: - Number strategies for reference - Provide concrete examples - Maintain dimension focus (don't allow abandoning core criteria) - Progress from conservative to broader adjustments

E. Dimension Objective Constraint

Purpose: Prevents extensions that deviate from the division's focus.

Pattern:

**Dimension objective (mandatory constraint):**
All extended queries MUST remain focused on [restate dimension objective].
Do NOT extend queries beyond [core requirement] combined with [anchoring requirements].

Example:

**Dimension objective (mandatory constraint):**
All extended queries MUST remain focused on identifying precedents involving applicants
from the same or closely related countries who present a comparable legal and procedural
profile. Do NOT extend queries beyond country-of-origin similarity combined with
legal/procedural characteristics.

F. Repeated Query Construction Rules

Purpose: Since agents can't see the "open" instructions, repeat essential rules.

Pattern:

Here are the instructions for the QueryExecutor tool:

**Query construction rules:**
1. [Rule 1 - typically about mandatory extraction]
2. [Rule 2 - about optional characteristics]
3. [Rule 3 - about using approved values only]
4. [Rule 4 - about prohibitions]
5. [Rule 5 - about query requirements]
6. [Rule 6 - about what NOT to do]

What to Include: - All mandatory extraction requirements - Reference to the ontology/CSV - Prohibition of free-form values - Core similarity requirements - Key "do not" rules

G. Execution Instructions for Extended Queries

Purpose: Provides complete parameters for refined queries.

Pattern:

**Execution instructions for extended queries:**
- For each constructed query, call QueryExecutor with:
  - query: the constructed query string
  - ontology_id: "[ONTOLOGY]"
  - generate_pretty: true
  - limit: [NUMBER]
  - min_score: [adjusted value, e.g. 0.5 or 0.45 if applying Strategy 1]
  - instructions_to_report:
    Use the following text as the value for the QueryExecutor's instructions_to_report parameter. Copy it exactly as given here.
    This text instructs the LLM analyzing the RAG results on how to generate its report:

    "[EXACT SAME INSTRUCTIONS_TO_REPORT AS IN 'OPEN' STATE]"

Key Principles: - Use identical instructions_to_report text from the "open" state - Allow adjusted min_score based on extension strategy - Keep other parameters consistent - Include the full instruction text (don't reference or abbreviate)

4. Critical Workflow Architecture

JSON-Only Output for "Open" and "In Review" States

Critical Understanding: Based on the AgentDeepReasoning implementation, the "open" and "in review" statuses only generate JSON output, not prose:

"open" status: Outputs { "optional_new_tasks": [...] }
"in review" status: Outputs { "internal_thoughts": "...", "optional_new_tasks": [...] }

Implication: Instructions for these statuses should NOT include sections like: - "After executing extended queries:" - This doesn't apply to JSON output - "Document which extension strategy was used" - JSON doesn't have a place for this - Any prose-based output instructions

What to Include Instead: - Focus on query construction rules - Define when to create new tasks (via optional_new_tasks JSON field) - Specify QueryExecutor parameters clearly - Keep instructions focused on decision-making, not on generating prose output

What NOT to Include: - ❌ "After executing extended queries:" sections - ❌ Instructions to "document findings in your output" - ❌ "IMPORTANT - Task Creation:" prohibition blocks (redundant since JSON only has task field) - ❌ Any instructions about formatting prose output

Summary Generation Happens in "Compiling Summary" Status

Summary generation is a separate workflow step that occurs when the division transitions to "compiling summary" status. The "open" and "in review" states focus purely on: 1. Executing queries via QueryExecutor 2. Deciding if additional tasks are needed (via JSON optional_new_tasks)

4. Common Patterns and Anti-Patterns

✅ DO: Best Practices

Self-Contained Instructions
Each <instructions> block must be complete
Don't reference other instruction blocks
Repeat information when necessary
Clear Dimension Focus
State the dimension objective prominently
Maintain focus throughout all instructions
Prevent scope creep in extension strategies
Concrete Examples
Provide example queries with placeholders
Show query progression (specific → broader)
Include example output formats
Explicit Prohibitions
State what NOT to do
Explain why certain approaches are prohibited
Use "Important:" or "Constraints:" sections
Quality Controls
Set minimum similarity requirements (AND logic)
Define sufficiency criteria
Require case-by-case analysis (prevent over-generalization)
Consistent Parameters
Use the same ontology_id throughout
Keep limit/min_score appropriate for the dimension
Always include generate_pretty: true

❌ DON'T: Anti-Patterns

Cross-Referencing Instructions ```xml

Follow the same query rules as defined in the "open" state. ```

Vague Dimension Goals ```

Dimension objective: Find similar cases.

Dimension objective: Identify precedents involving applicants from the same or closely related countries who present a comparable legal and procedural profile. ```

Single-Criterion Queries ```

Query: COUNTRY_OF_ORIGIN=AFG

Query: COUNTRY_OF_ORIGIN=AFG AND PROCEDURAL_STAGE=FIRST_INSTANCE ```

Missing instructions_to_report ```python # BAD: LLM doesn't know what to do with fragments QueryExecutor(query="...", limit=5)

# GOOD: LLM gets explicit guidance QueryExecutor(query="...", limit=5, instructions_to_report="...") ```

Incomplete Repetition in "in review" ```xml

If insufficient results, lower the min_score.

If insufficient results, execute new queries with: - query: [construction rules repeated] - min_score: 0.5 (lowered from 0.6) - instructions_to_report: [full text repeated] ```

Overly Permissive Extension Strategies ```

Strategy: If no results, remove all category constraints and use only semantic search.

Strategy: Broaden COUNTRY_OF_ORIGIN to neighboring countries but MUST maintain at least one procedural or legal anchor. ```

Creating Tasks for Summary Updates ```xml

After executing extended queries: - Update the compiled summary to incorporate new findings - Create a task to compile the summary with the new results

After executing extended queries: - Document which extension strategy was used and why in your output - Note any new findings in your output

IMPORTANT - Task Creation: Do NOT create tasks to update or compile the summary for this division. ```

Why This Is Bad: - Summary compilation is workflow-driven (status transitions), not task-driven - Creating tasks for summary updates causes confusion and duplicate work - The "compiling summary" status instructions already define how summaries are created - Agents should focus on query execution and documentation, not workflow management

5. Template Checklist

Use this checklist when creating or reviewing a division:

For_status="open" Instructions

[ ] Tool recommendation specified: recommended_tools="+QueryExecutor"
[ ] Clear opening statement about what tool to use and why
[ ] Dimension objective section present and specific
[ ] Similarity principle section defines AND logic for matches
[ ] Query construction rules numbered and complete
[ ] Example queries provided (mandatory, conditional, optional)
[ ] Important warnings included
[ ] Execution instructions section with ALL parameters:
[ ] query parameter explained
[ ] ontology_id specified
[ ] generate_pretty: true included
[ ] limit value specified (typically 2-6)
[ ] min_score value specified (typically 0.2-0.6)
[ ] instructions_to_report included with full text
[ ] instructions_to_report contains:
[ ] Restated dimension objective
[ ] What to extract from each case
[ ] Output format requirements
[ ] Quality standards (e.g., "do not generalize")
[ ] Title format example
[ ] Constraints section present
[ ] IMPORTANT - Task Creation prohibition section present at end:
[ ] Explicitly prohibits creating tasks to update/compile summary
[ ] Explains that summary compilation is automatic
[ ] Clarifies agent role: execute queries and gather results only

For_status="compiling summary" Instructions

[ ] Exact summary title provided
[ ] Required elements listed as bullet points
[ ] Includes quantitative requirements (counts, numbers)
[ ] Includes qualitative requirements (patterns, reasoning)
[ ] Includes edge case handling ("if no cases found...")
[ ] Focuses purely on prose/narrative content (no JSON references)

For_status="compiling issues" Instructions

[ ] Issue identification criteria clearly defined
[ ] Examples of issue types provided
[ ] Issue ID format specified
[ ] Severity criteria explained
[ ] Allows for empty list (no issues is valid)
[ ] Focuses on problems/concerns, not solutions

For_status="compiling recommendations" Instructions

[ ] Recommendation types clearly described
[ ] Actionable and specific guidance provided
[ ] Allows for empty list (no recommendations is valid)
[ ] Recommendations are solution-focused
[ ] Each recommendation is independently understandable

For_status="in review" Instructions

[ ] Review mandate stated
[ ] Assessment criteria section defines insufficiency
[ ] Trigger condition for additional queries stated
[ ] Query extension strategies section present:
[ ] Multiple strategies listed and numbered
[ ] Each strategy has concrete guidance
[ ] Examples provided for each strategy
[ ] Dimension objective constraint restated to prevent scope creep
[ ] Query construction rules repeated (since agent can't see "open" state)
[ ] Execution instructions for extended queries section complete:
[ ] All QueryExecutor parameters specified
[ ] min_score shown as adjustable
[ ] instructions_to_report text repeated IN FULL
[ ] After executing extended queries section provides guidance:
[ ] Focuses on documenting findings (NOT updating summary)
[ ] Requires documentation of which extension strategy was used
[ ] Acknowledges limitations if still insufficient
[ ] IMPORTANT - Task Creation prohibition section present at end:
[ ] Explicitly prohibits creating tasks to update/compile summary
[ ] Explains that summary compilation happens automatically
[ ] Clarifies to document findings only

6. Reusability and Adaptation

Creating Similar Divisions for Other Dimensions

When creating new divisions following this pattern (e.g., for procedural posture, admissibility, persecution grounds, etc.):

Identify the Dimension
What specific aspect of cases are you analyzing?
What makes this dimension distinct from others?
Define the Core Category
What is the PRIMARY category from the ontology?
Example: COUNTRY_OF_ORIGIN, PROCEDURAL_STAGE, REFUGEE_GROUNDS
Identify Similarity Anchors
What SECONDARY criteria should be combined with the primary?
These create the AND logic for meaningful similarity
Adapt the Dimension Objective
Replace "country of origin" with your dimension
Maintain the structure: "Identify precedents involving [DIMENSION] who present [CHARACTERISTICS]"
Adjust Query Examples
Use your primary category as the base
Add appropriate secondary criteria
Maintain the specific → broader progression
Customize Extension Strategies
Strategy 1 (lower threshold) - usually reusable as-is
Strategy 2 (broaden scope) - adapt to your dimension (e.g., "broaden date range", "include adjacent categories")
Strategy 3 (alternative anchors) - list alternatives specific to your dimension
Strategy 4 (semantic) - reusable as-is
Update instructions_to_report
Replace dimension-specific language
Keep the structural requirements (title format, case-by-case analysis, etc.)

7. Relationship to QueryExecutor Tool

How Division Instructions Map to Tool Parameters

Division Element	QueryExecutor Parameter	Purpose
Query construction rules	`query`	Defines the thalabus query string
Ontology reference	`ontology_id`	Scopes to specific category definitions
Limit value	`limit`	Number of documents per query
Min score threshold	`min_score`	Relevance threshold for inclusion
Instructions to report	`instructions_to_report`	Guides LLM analysis of fragments
Generate pretty flag	`generate_pretty`	Enables markdown output
Extension strategies	Adjusted `min_score`, modified `query`	Refinement parameters

Understanding Limit Behavior

Critical: The limit parameter applies per document, not per fragment.

limit=5 means "retrieve top 5 documents"
Each document may contain multiple fragments
instructions_to_report is executed on documents (or their fragments)
Filtering happens BEFORE LLM processing

Example Flow:

Query matches 100 documents
  ↓ (apply limit=5)
Top 5 documents selected
  ↓ (apply min_score=0.6)
Documents with score ≥ 0.6 retained
  ↓ (extract fragments)
Fragments from retained documents
  ↓ (apply instructions_to_report)
LLM generates report for each document/fragment

8. Testing and Validation

Validation Steps for New Divisions

Syntax Validation
Ensure all XML is well-formed
Check that instruction blocks are properly closed
Verify recommended_tools attribute syntax
Completeness Check
Run through the checklist in Section 5
Ensure all required sections present
Verify instructions_to_report is included
Self-Containment Test
Read "in review" instructions in isolation
Can an agent execute queries without seeing "open" instructions?
Is all necessary information repeated?
Dimension Focus Test
Do all queries maintain the core dimension?
Do extension strategies preserve dimension focus?
Are there appropriate prohibitions?
Example Query Test
Can you construct actual queries from the examples?
Are placeholders clear (UPPER_CASE)?
Do queries respect the similarity principle?
Integration Test
Load the template
Verify division appears correctly
Test query execution with sample data

9. Version History and Evolution

Version 2.1 Improvements (Current)

Based on the Template_UseCase_Asylum.xml reference:

Enhanced instructions_to_report
Added explicit dimension objective in report instructions
Required case-by-case analysis
Standardized title format
Comprehensive Extension Strategies
Four distinct strategies defined
Concrete examples for each
Maintained dimension focus
Complete Instruction Repetition
Full query construction rules in "in review"
Complete instructions_to_report text repeated
Self-contained execution instructions
Explicit Sufficiency Criteria
Quantitative thresholds (e.g., "fewer than 3 cases")
Quality indicators
Clear trigger conditions

Version 2.2 Improvements (January 2026)

Building on Version 2.1, this update clarifies workflow boundaries and prevents task confusion:

Task Creation Prohibition
Added explicit prohibition against creating tasks to update summaries
Clarified that summary compilation is workflow-driven (status transitions), not task-driven
Prevents confusing task recommendations like "Update the compiled summary to incorporate new findings"
Updated Post-Execution Instructions
Changed from "Update the compiled summary" to "Document findings in your output"
Emphasizes documentation over workflow management
Clarifies agent responsibility: execute queries and document results only
Enhanced Documentation
Added Section 1.I (Task Creation Prohibition) for "open" instructions
Added Section 3.1.I (Task Creation Prohibition) for "in review" instructions
Updated Section 4 with new anti-pattern (#7) about task creation
Updated checklist in Section 5 to verify task prohibition sections
Workflow Clarity
Reinforces that "compiling summary" status handles summary generation automatically
Agents focus on their current status responsibilities, not on triggering other statuses
Prevents duplicate work and confusion about workflow steps

Version 2.3 Improvements (January 2026)

Architectural correction based on AgentDeepReasoning implementation analysis:

JSON-Only Output Architecture
Documented that "open" and "in review" statuses output JSON only, not prose
"open" outputs: {"optional_new_tasks": [...]}
"in review" outputs: {"internal_thoughts": "...", "optional_new_tasks": [...]}
Only "compiling summary" status generates prose/text output
Removed Inappropriate Instruction Blocks
Removed "After executing extended queries:" sections from "in review" instructions
These sections implied prose output incompatible with JSON-only architecture
Removed associated task prohibition blocks (redundant for JSON output)
Updated Documentation Structure
Section 1.I: Changed from "Task Creation Prohibition" to "Task Management (Optional)"
Section 3.1.H: Removed "Post-Execution Instructions"
Section 3.1.I: Removed redundant "Task Creation Prohibition"
Added Section 4: "Critical Workflow Architecture" explaining JSON vs prose output
Clarified Instruction Focus
"open" and "in review" instructions now focus on:
- Query construction rules
- Decision-making logic
- When to create tasks (via JSON field)
Removed all references to:
- "Document findings in your output" (N/A for JSON)
- "After executing queries..." (N/A for JSON)
- Prose formatting instructions (N/A for JSON)
Workflow State Machine Emphasis
Summary generation is a separate state ("compiling summary"), not a task
Status transitions are automatic, not agent-initiated
Tasks should be for genuinely new work, not workflow steps

Version 2.4 Improvements (January 2026)

Complete lifecycle documentation with status-specific output requirements:

Division Lifecycle Documentation
Added comprehensive state machine diagram showing all status transitions
Documented complete workflow: open → in progress → compiling summary → in review → complete
Explained decision point where "in review" can loop back to "compiling summary"
Status-Specific JSON Schemas
"open" status: REASONING_COMMAND_FOR_STATUS_OPEN_JSON
- Fields: optional_new_tasks (optional array)
"compiling summary" status: Two-stage process
- Stage 1: Prose summary generation
- Stage 2: REASONING_COMMAND_FOR_STATUS_READY_FOR_SUMMARY_JSON
- Fields: optional_issues, optional_recommendations, optional_focus_content_id, optional_split_to_chunks (all required)
"in review" status: REASONING_COMMAND_FOR_STATUS_IN_REVIEW_JSON
- Fields: internal_thoughts (optional), optional_new_tasks (optional array)
Critical Instruction Design Implications
Added explicit DO/DON'T guidance for each status
Prevents cross-contamination of JSON fields between statuses
Examples: Don't reference optional_issues in "open" instructions (wrong status)
Output Format Clarity
Each major section now explicitly states the output format at the top
Clear distinction between JSON-only statuses and prose-generating status
Emphasized that "compiling summary" is the ONLY status that generates prose summary
Stage 2 Metadata Documentation
Documented the automatic Stage 2 metadata collection in "compiling summary"
Clarified purpose and usage of each required JSON field
Provided guidance on when to use optional_issues vs optional_recommendations

Version 2.5 Improvements (January 2026)

Comprehensive guidance on issues/recommendations substantive focus:

Section 9: Issues and Recommendations: Substantive Content Focus
Core Principle: Issues/recommendations are about case SUBSTANCE, not information gathering
Explicitly distinguished between:
- ✅ Substantive issues (legal problems in the case, adverse jurisprudence, evidentiary gaps)
- ❌ Process concerns (search quality, query results quantity, tool effectiveness)
Division-Specific Guidance
Division 100 (Management Summary): Strategic case issues (exclusion risks, fundamental legal defects)
Division 220 (Detailed Analysis): Evidentiary deficiencies in input documents
Divisions 301-312 (Similar Cases): Adverse legal patterns found IN retrieved jurisprudence
Division 401 (Asylum Assessment): Substantive weaknesses in asylum eligibility
Division 402 (Removal Assessment): Medical/humanitarian barriers to removal
Severity Guidelines by Division
Provided division-specific criteria for high/medium/low severity categorization
Included concrete examples for each severity level
Emphasized outcome-determinative vs. concerns-worth-noting distinction
Critical Clarification for Similar Cases Divisions
Issues should describe THE CONTENT of retrieved cases, not the quantity
Example: "All retrieved cases with murder convictions led to exclusion" (substantive issue)
NOT: "Only found 2 comparable cases" (process concern)
Acceptable to return {} if jurisprudence is favorable
Recommendations as Actionable Strategies
Good: "Commission psychiatric evaluation focusing on suicide risk"
Good: "Develop argument distinguishing from adverse precedent X"
Poor: "Search for more cases" (process-focused)
Poor: "Broaden query parameters" (tool configuration)
State-Specific Output Formats
Each of the three compilation states has a dedicated output format
"compiling summary": Plain text prose only
"compiling issues": JSON with issues array
"compiling recommendations": JSON with recommendations and focus content
No conflation or multi-stage processing within a single state
Optional Instructions Pattern
All instruction blocks are optional for any state
Missing instructions trigger automatic state advancement
No special attributes needed to skip state processing
When to Generate Issues/Recommendations
Generate when: substantive problems exist, adverse patterns found, barriers identified
Omit when: case is strong, evidence complete, jurisprudence favorable
Simply omit the instruction block if not needed (automatic skip)

Future Considerations

Parameterization
Consider extracting common values (limit, min_score) to template-level parameters
Allow easier global adjustment
Tool-Agnostic Patterns
While focused on QueryExecutor, patterns could apply to other tools
Consider generalization for other analytical tools
Automated Validation
Build validators to check division completeness
Automated checklist verification

9. Issues and Recommendations: Substantive Content Focus

9.1 Core Principle

Issues and recommendations are about substantive case content, NOT about information gathering or search quality.

The optional_issues and optional_recommendations fields in the Stage 2 JSON output (during "compiling summary" status) should identify and describe: - Substantive legal problems in the case itself - Factual weaknesses or gaps in the evidence - Adverse patterns found in retrieved jurisprudence - Medical, humanitarian, or security barriers affecting the case outcome

They should NOT describe: - ❌ Search/query result quantity ("only found 2 cases") - ❌ Process problems ("need to broaden search parameters") - ❌ Tool effectiveness ("similarity scores too low") - ❌ Information retrieval concerns ("insufficient query results")

9.2 Division-Specific Guidance

Division 100 (Management Summary)

Focus: Strategic substantive issues in the case

Issue Examples: - ✅ "Prior conviction for violent crime creates Art. 53 exclusion risk" (severity: high) - ✅ "Persecution claim lacks nexus to protected ground" (severity: high) - ✅ "Country of origin jurisprudence shows systematic rejection of similar claims" (severity: medium) - ❌ "Need more information about medical condition" (this is a process concern, not a substantive issue)

Severity Guidelines: - High: Case-determinative barriers (exclusion grounds, fundamental legal defects, systematic adverse jurisprudence) - Medium: Significant weaknesses affecting prospects (weak persecution narrative, credibility gaps, attribution unclear) - Low: Minor concerns that should be addressed (supplementary evidence helpful, minor inconsistencies)

Division 220 (Detailed Analysis)

Focus: Evidentiary deficiencies in INPUT documents

Issue Examples: - ✅ "Medical report states depression but provides no suicide risk assessment" (severity: high) - ✅ "Persecution narrative names actors but provides no evidence of state involvement" (severity: medium) - ✅ "Timeline gaps make it impossible to assess whether persecution is ongoing" (severity: high) - ❌ "Need to categorize documents" (this is a task, not a substantive issue)

Severity Guidelines: - High: Critical information completely missing that prevents core legal analysis - Medium: Significant gaps that weaken assessment (vague attribution, insufficient detail, inconsistencies) - Low: Minor gaps worth noting (missing corroboration, approximate dates sufficient but not ideal)

Divisions 301-312 (Similar Cases)

Focus: Adverse legal patterns or precedents discovered FROM retrieved case law

Issue Examples: - ✅ "All 5 retrieved cases with murder convictions resulted in Art. 53 exclusion" (severity: high) - ✅ "Jurisprudence shows systematic skepticism of political persecution claims from safe third countries" (severity: high) - ✅ "Similar medical conditions consistently found insufficient for removal barrier" (severity: medium) - ✅ "Post-decision conversions deemed opportunistic in all retrieved cases" (severity: high) - ❌ "Only found 2 comparable cases" (this is about search results, not substantive legal content) - ❌ "Need to broaden country of origin search" (this is a process recommendation, not a substantive issue)

Severity Guidelines: - High: Systematic adverse outcomes in comparable cases (all similar claims rejected, exclusion applied consistently) - Medium: Mixed but concerning patterns (majority of cases adverse, significant scrutiny observed) - Low: Jurisprudential concerns worth noting (evidentiary standards strict, one adverse precedent)

Critical Note: These divisions should analyze THE CONTENT of retrieved jurisprudence, not the quantity or quality of search results. If only 1 case is found but it shows systematic rejection of identical claims, that's a high-severity substantive issue. If 10 cases are found and they're all favorable, there may be no issues to report.

Division 401 (Asylum Assessment)

Focus: Substantive legal weaknesses in asylum eligibility

Issue Examples: - ✅ "Alleged harm does not qualify as persecution - appears to be private criminal matter" (severity: high) - ✅ "No nexus to protected ground - applicant not targeted for race/religion/nationality/political opinion/social group" (severity: high) - ✅ "Attribution ambiguous - unclear if harm from state or non-state actors" (severity: medium) - ✅ "Internal flight alternative appears available - applicant could relocate within country" (severity: medium) - ❌ "Need more country conditions information" (this is a task/process concern)

Severity Guidelines: - High: Fundamental barriers to asylum eligibility (no persecution, no protected ground nexus, effective state protection proven) - Medium: Significant weaknesses (attribution ambiguous, internal flight available, weak nexus) - Low: Concerns not determinative (minor credibility issues, supplementary evidence would help)

Division 402 (Removal Assessment)

Focus: Medical, humanitarian, or legal barriers to removal

Issue Examples: - ✅ "Severe psychiatric condition with documented suicide risk meets concrete danger threshold" (severity: high) - ✅ "Life-threatening medical condition with no treatment available in origin country" (severity: high) - ✅ "Removal would violate Art. 3 ECHR due to risk of torture" (severity: high) - ✅ "Psychiatric condition documented but suicide risk assessment incomplete" (severity: medium) - ❌ "Need psychiatric evaluation report" (this is a recommendation for gathering evidence, not an issue itself)

Severity Guidelines: - High: Barriers that likely prevent removal execution (concrete danger established, Art. 3 ECHR violation, no treatment available) - Medium: Significant concerns about feasibility (suicide risk unclear, treatment availability uncertain, continuity of care concerns) - Low: Concerns unlikely to prevent removal (condition manageable, treatment available, temporary obstacles)

9.3 Recommendations: Actionable Strategies

Recommendations should provide specific, actionable strategies to address the identified substantive issues:

Good Recommendations: - ✅ "Commission psychiatric evaluation focusing on suicide risk prognosis" - ✅ "Obtain country expert opinion on state protection effectiveness for this ethnic group" - ✅ "Develop legal argument distinguishing current case from adverse precedent X based on temporal nexus" - ✅ "Consider alternative legal characterization as social group membership rather than political opinion"

Poor Recommendations: - ❌ "Search for more cases" (process-focused, not addressing substantive issue) - ❌ "Broaden query parameters" (search quality, not case substance) - ❌ "Try different similarity thresholds" (tool configuration, not legal strategy)

9.4 When to Generate Issues/Recommendations

Generate when: - Substantive legal problems exist in the case - Evidence has critical gaps - Jurisprudence reveals adverse patterns - Medical/humanitarian barriers are present - Security or exclusion concerns arise

Omit or return empty {} when: - Case is substantively strong (no legal weaknesses) - Evidence is complete and credible - Jurisprudence is favorable or neutral - No removal barriers identified

Note: For similar_cases divisions (301-312), it's acceptable to have NO issues if the retrieved jurisprudence is favorable. The absence of adverse patterns is itself a finding - don't invent process-related issues just to populate the field.

9.5 Implementation Pattern in Instructions

The "compiling summary" instructions should follow this two-section pattern:

<instructions for_status="compiling summary">
# ROLE AND OBJECTIVE
## When you are requested to output the summary in plain text:
[Instructions for Stage 1: prose summary generation]

## When you are requested to output json:
Your task is to identify [substantive aspect relevant to this division].

### Issues (optional_issues)
Generate issues based on [substantive problems/patterns/barriers]. Each issue must have:
- issue_id: unique identifier starting with "i-" (e.g., "i-[division]-[category]-001")
- description: clear description of the [substantive problem]
- severity: categorize as follows:
  * high: [Division-specific high-severity criteria with examples]
  * medium: [Division-specific medium-severity criteria with examples]  
  * low: [Division-specific low-severity criteria with examples]
- status: always set to "open" for new issues

Examples: [3-5 concrete examples of substantive issues for this division]

### Recommendations (optional_recommendations)
Provide [strategic/evidentiary/legal] recommendations:
- [Specific types of recommendations relevant to this division]
- [Focus on addressing the substantive issues identified]

Note: [When to omit JSON output or return empty object]
</instructions>

9.6 Skipping Compilation States

To skip any of the three compilation states, simply omit the instruction block:

<!-- Omit any of these to skip that state -->
<instructions for_status="compiling summary">...</instructions>
<instructions for_status="compiling issues">...</instructions>  <!-- Omit to skip -->
<instructions for_status="compiling recommendations">...</instructions>  <!-- Omit to skip -->

The agent will automatically advance through states that have no instructions.

Common patterns: - Summary only: Provide only "compiling summary" instructions (skip issues and recommendations) - No issues: Provide "compiling summary" and "compiling recommendations" (skip issues) - Full pipeline: Provide all three instruction blocks

Use summary-only for: - Purely factual divisions (document lists, case overviews) - Structural divisions (table of contents, chapter headers) - Divisions that aggregate content from other divisions - Divisions where the output itself provides recommendations as prose

Examples: - Division displaying input documents (summary only) - Chapter header with table of contents (summary only) - Document categorization (summary only, factual) - Strategic recommendations division (summary only, prose recommendations)

10. Table-Based Output Format for Assessment Divisions

10.1 Overview and Purpose

Assessment divisions (particularly in Chapter 4: Final Assessment) benefit from a structured table-based output format that systematically decomposes complex legal assessments into manageable analytical units. This format has been successfully implemented in:

Division 4.1 (Asylum Eligibility Assessment)
Division 4.2 (Removal Enforceability Assessment)
Division 4.3 (Strategic Legal Recommendations)
Division 4.4 (Next Steps / Action Plan)

10.2 Standard Table Structure

The canonical table structure uses four columns with specific cognitive and architectural purposes:

Element	Evidence	Applicable Laws	Assessment
[Analytical unit]	[Supporting facts]	[Legal references]	[Determination]

10.3 Column-by-Column Rationale

Column 1: Element (Divide et Impera)

Purpose: Decompose complex legal questions into discrete, manageable analytical units.

Cognitive Principle: Divide et impera (divide and conquer) - breaking down a complex assessment into smaller, focused units allows for: - Systematic coverage of all relevant aspects - Prevents omissions or superficial treatment - Creates logical structure for both LLM generation and human review - Enables granular tracking of which elements have been addressed

Examples: - Asylum Assessment: "Applicants' own explanation", "Perpetrators' apparent motive", "Particular social group claim" - Removal Assessment: "Fitness for transport", "Treatment availability in country of origin", "Concrete danger threshold" - Recommendations: Category headings like "Priority Arguments and Evidence Gathering", "Primary vs. Fallback Legal Theories"

Implementation Principle: Each row = one focused analytical question. The decomposition should be: - Mutually exclusive: No overlap between elements - Collectively exhaustive: All relevant aspects covered - Logically sequenced: Natural flow from one element to the next

Column 2: Evidence (Factual Foundation)

Purpose: Gather and present the factual basis for assessment of each analytical unit.

Cognitive Principle: Evidence grounding - separating facts from legal conclusions prevents: - Circular reasoning (using conclusions as evidence) - Unsupported assertions - Confusion between what is claimed vs. what is proven - Enables verification and challenge of factual premises

Content Guidelines: - Summarize relevant facts from case documents - Quote or paraphrase applicant statements when relevant - Reference documentary evidence (medical reports, police records, witness statements) - Note evidentiary gaps or weaknesses - Use neutral, descriptive language (not evaluative)

Examples: - "Both applicants repeatedly state that the threats and the assault stem from a family vendetta linked to their son's murder" - "Police opened joint investigation but no suspects identified; offered only advice, no personal protection" - "Medical assessment shows chronic renal insufficiency, arterial hypertension, generalized osteoarthritis"

Architectural Benefit for LLMs: By requiring evidence presentation before assessment, the instructions force the LLM to: 1. Ground analysis in documented facts 2. Avoid premature conclusions 3. Create a clear audit trail from facts → legal assessment

Column 3: Applicable Laws (Normative Information Sources)

Purpose: Reference the legal framework and normative standards that govern the assessment of each element.

Dual Function:

A. For Human Users (Reference Function) - Provides direct clickable references to legal provisions - Enables verification of legal reasoning - Supports understanding of why specific criteria apply - Facilitates legal research and case preparation

B. For Machine Processing (Factual Source Function) - Creates structured, machine-readable links to normative information - Enables future retrieval-augmented generation (RAG) from legal databases - Supports automated consistency checking across cases - Allows traceability of legal reasoning chains

Format Specification:

<span class="info-source" id="law://[URL-encoded reference]">[Display text]</span>

Examples: - Art. 3 LAsi - Art. 83 para 4 LEtr - JICRA 2006 No. 18 - Multiple references: Art. 3 LAsi Subsidiarity principle

Why URL Encoding: - Spaces encoded as %20 - Special characters encoded properly - Ensures valid URI structure for future database lookup - Enables programmatic parsing and reference resolution

Content Guidelines: - Include ALL relevant legal provisions for this element - Reference applicable case law when establishing standards - Include legal principles or doctrines (e.g., "Subsidiarity principle", "Concrete danger threshold") - Provide multiple references when element involves intersection of laws

Column 4: Assessment (Synthesis and Determination)

Purpose: Elaborate the legal assessment for this specific element, synthesizing evidence and law into a clear determination.

Cognitive Principle: Constrained attention window - by the time the LLM generates this column, all necessary context is in close proximity within the same table row: - Column 1 (Element) defines the question - Column 2 (Evidence) provides the facts - Column 3 (Laws) provides the legal framework - Column 4 synthesizes these into a determination

Transformer Architecture Benefit: - LLM attention mechanisms naturally focus on tokens in close proximity - Having all context within a single table row (typically < 200 tokens apart) ensures: * All attention heads can capture relationships between evidence, law, and assessment * No need to recall information from distant context * Reduced risk of attention drift or context loss * More consistent and grounded reasoning

Assessment Quality Requirements: - Binary determinations where appropriate: "YES/NO", "QUALIFIES/DOES NOT QUALIFY", "LAWFUL/NOT LAWFUL" - Brief reasoning: Explain how evidence + law → determination - Decisive language: "does qualify" not "may qualify" (unless genuine uncertainty exists) - Explicit conclusions: Don't leave assessments ambiguous

Examples: - "The motive is personal/family-vendetta, not an attribute such as ethnicity, religion, nationality, political opinion, or membership in a socially-recognizable group." - "DETERMINATION: YES – state protection is not effective/available." - "DETERMINATION: Execution of removal is EXIGIBLE."

Progressive Refinement Pattern: - Individual row assessments build toward section-level determinations - Section-level determinations build toward final binary conclusion - Each assessment references or builds upon previous assessments - Creates logical chain: micro-assessments → macro-assessment → final conclusion

10.4 Architectural Benefits Summary

For LLM Generation: 1. Structured decomposition prevents analysis gaps 2. Sequential column processing enforces evidence → law → assessment reasoning chain 3. Proximity-based attention ensures all context is accessible to transformer 4. Binary determinations force clarity and prevent hedging 5. Audit trail from facts through law to conclusion enables quality control

For Human Consumption: 1. Scannable structure - easy to review specific elements 2. Traceable reasoning - can verify how conclusions were reached 3. Clickable legal references - immediate access to normative sources 4. Granular assessment - see not just final answer but reasoning for each component

For Machine Processing: 1. Structured data - tables are parseable, extractable, queryable 2. Linked legal references - URI structure enables automated lookup 3. Consistent format - enables cross-case comparison and pattern analysis 4. Typed determinations - binary values can be extracted programmatically

10.5 Implementation in Instructions

Pattern for "compiling summary" instructions:

<instructions for_status="compiling summary">
# ROLE AND OBJECTIVE
You are a legal assessment LLM...

MANDATORY CONTENT AND FORMAT

**SECTION 1: [Section Name]**

Present a table with the following structure:

| Element | Evidence | Applicable Laws | Assessment |
|---------|----------|-----------------|------------|
| [Element 1 name] | [Summarize relevant facts] | <span class="info-source" id="law://...">[Law reference]</span> | [DETERMINATION: YES/NO with reasoning] |
| [Element 2 name] | [Summarize relevant facts] | <span class="info-source" id="law://...">[Law reference]</span> | [DETERMINATION: YES/NO with reasoning] |
| Overall [category] | [Summary of all evidence] | <span class="info-source" id="law://...">[Law reference]</span> | **DETERMINATION: [YES/NO]** – [conclusion]. |

After the table, provide a brief textual determination (1-2 sentences):
**Determination:** **[YES/NO]** – [restate conclusion].

---

**SECTION 2: [Next Section Name]**
[Repeat table structure]

STYLE AND CONSTRAINTS
- Use HTML tables with proper markdown formatting
- In "Applicable Laws" column, ALWAYS use format: `<span class="info-source" id="law://[URL-encoded]">[Display]</span>`
- Make DETERMINATIVE statements with reasoning
- Use decisive binary language where appropriate
</instructions>

10.6 Variations by Division Type

Assessment Divisions (4.1, 4.2): - Focus on legal determinations (asylum eligibility, removal barriers) - Heavy use of binary YES/NO, QUALIFIES/DOES NOT QUALIFY - Emphasis on legal reasoning chains - Multiple tables building to final binary conclusion

Recommendation Division (4.3): - Focus on strategic guidance - "Priority" replaces binary determination - Rationale column explains strategic purpose - Less formal legal reasoning, more practical guidance

Action Division (4.4): - Focus on operational execution - "Urgency & Expected Output" replaces assessment - "Responsible Party" added as second column - Emphasis on concrete deliverables and timing

10.7 When to Use Table Format

✅ USE table format when: - Assessment requires systematic coverage of multiple elements - Determinations must be grounded in specific evidence and law - Human review requires traceability of reasoning - Machine processing may need to extract structured determinations - Complex legal questions benefit from decomposition

❌ DON'T use table format when: - Content is purely narrative (case overview, background) - No analytical decomposition needed (simple fact listing) - Format would be forced or artificial - Prose is more natural and readable

Consider for these division types: - Legal assessments (asylum, removal, admissibility) - Risk analysis (systematic evaluation of risk factors) - Comparative analysis (if comparing specific elements across cases) - Strategic planning (recommendations, next steps)

NOT appropriate for: - Document listings (input documents, police records) - Purely factual summaries (case overview) - Narrative synthesis (decision summary) - Free-form strategic discussions (where structure would be constraining)

11. Summary

A well-structured division following these best practices achieves:

✅ Clarity: Agents know exactly what to do at each state ✅ Self-Containment: Each instruction block is complete and independent ✅ Consistency: Standardized structure across dimensions ✅ Quality: Built-in controls prevent poor results ✅ Adaptability: Extension strategies handle edge cases ✅ Maintainability: Clear patterns make updates easier ✅ Workflow Discipline: Agents stay focused on their status responsibilities without creating confusing tasks

The similar_cases_country_of_origin division exemplifies these principles and serves as the template for all similar analytical divisions.

References

Template: Examples/Template_UseCase_Asylum.xml
Reference Division: <division id="similar_cases_country_of_origin">
Tool: src/core/extensions/skillsets/PlatformSkills/QueryExecutor.py
Query Language: Documentation/Documents/THALABUS_QUERY_LANGUAGE.md