Orchestrator/bahn/teamlandkarte-mcp/openspec/changes/improve-task-details-role-inference-and-guided-flow/proposal.md

# Change Proposal: Improve Task Details, Role Inference, Guided Requirements Capture, and Search Reliability

- **Change ID**: `improve-task-details-role-inference-and-guided-flow`
- **Status**: Implemented
- **Target**: `teamlandkarte-mcp`
- **Author**: (to fill)
- **Date**: 2026-02-12

## Summary

This proposal refines several MCP tools and interaction flows to improve usability in Cherry Studio and other MCP clients:

1. `get_task_details` should return a concise markdown summary (table) of the task plus description below.
2. Introduce a dedicated tool `infer_roles` for role inference from either a DB task ID or free-text description.
3. `validate_task_requirements` should return a single comparison table plus a short written summary.
4. When a user requests a person search without providing project/task details, switch to a **step-by-step guided capture** (no "all questions at once").
5. Enforce a **mandatory confirmation step** before triggering matching, for both free-text and guided capture / structured entry.
6. Fix a suspected competence matching regression (cloud expert + AWS scoring ends up `Low`), likely caused by extraction/matching issues.
7. Improve search session robustness for pagination/filtering:
   - search tools emit a JSON block containing `search_id`/`filter_id`
   - non-UUID `search_id` inputs are rejected early with a clear message
   - internal tracking of the latest search id (session state) for diagnostics only; **no** "get last search id" tool is provided
8. Update documentation, architecture, and design markdown accordingly.

## Motivation

- Current outputs are verbose and inconsistent across tools.
- Role inference exists but is not clearly available as an explicit tool.
- Guided capture and confirmation are required to prevent accidental matching runs.
- Cache invalidation/expiry breaks multi-step flows (`filter_search_results`, pagination, etc.).

## Goals

- Produce stable, markdown-first outputs that are easy to consume in chat UIs.
- Make role inference available as an explicit, reusable capability for both DB-backed tasks and free-text.
- Improve correctness and robustness of role/requirements extraction and semantic matching via the server’s Azure OpenAI integration.
- Ensure multi-step search workflows remain functional for realistic time spans.
- Remove artificial constraints on the number of exposed MCP tools.

## Non-Goals

- Re-introducing Hive/PyHive support.
- Changing the underlying DB schema.
- Replacing LLM-based role inference with a numeric-only scorer (categorical matching output should remain the main UX).

## Proposed Changes

### 1) `get_task_details` output format

Change `get_task_details(task_id)` to return:

1. A markdown table with columns:
   - Task ID
   - Title
   - Created (date only, no time)
   - Start
   - End
   - Competences (comma-separated, no numbering)
   - Inferred Role
2. Below the table:
   - The task description (plain markdown, no table)

Notes:
- "Inferred Role" is derived using `infer_roles` (see section 2). If no role is inferred, display `(none)`.

### 2) Dedicated role inference tool: `infer_roles`

Add a tool to infer roles from either:

- A DB task via `task_id`, or
- A free-text `task_description`

Signature:

- `infer_roles(task_id: Optional[str] = None, task_description: Optional[str] = None, limit: int = 5) -> str`

Output:
- A markdown table containing all recognized roles, each with:
  - Rank
  - Role
  - Rationale

Behavior:
- Exactly one of `task_id` or `task_description` must be provided.
- Uses Azure OpenAI chat completion for role inference (no heuristic fallback).

### 3) `validate_task_requirements` output format

Change output to:

1. A single markdown comparison table that contrasts DB vs extracted information.
2. Table must include:
   - Task ID
   - Title
   - Time ranges (DB vs extracted)
   - Competences (DB vs extracted)
3. Below the table, a short written summary, including:
   - Skill overlap and notable differences
   - Any missing DB fields (dates/skills)

### 4) Step-by-step guided capture mode (step-specific tools)

Introduce a guided capture workflow for the case:

> User requests people/capacity search but provides insufficient task/project details.

The guided flow should collect input sequentially using step-specific tools (to avoid free-text ambiguity):

1. Task description
2. Role
3. Time range
4. Competences

Implementation idea:
- Add a server-side state machine stored in `SessionState`.
- Add tools such as:
  - `start_guided_capture()`
  - `guided_set_description(description: str)`
  - `guided_set_role(role_name: str)`
  - `guided_set_time_range(date_start: Optional[str] = None, date_end: Optional[str] = None)`
  - `guided_set_competences(competences: list[str])`

### 5) Enforce confirmation before matching (shared mechanism, hard-gated)

`extract_requirements` and structured/guided capture must not directly trigger matching.

Instead, both should:
- produce a "pending" `Requirements` object, and
- require a confirmation step **before matching tools can execute**.

Hard enforcement:
- `find_matching_capacities` (and any DB-backed matching tool) must refuse to run unless requirements have been explicitly confirmed **or** confirmation is auto-skipped by configuration (see below).

Config key (name + location):
- Add a matching section flag in `database.toml`:

  ```toml
  [matching]
  require_confirmation = true
  ```

- Default: `true` (strict).
- When `false`: pending requirements are treated as auto-confirmed (skip confirmation).

Implementation idea:
- Keep `confirm_requirements` parameters for backwards compatibility, but route the behavior through a shared internal helper and a shared tool:
  - internal: `_set_pending_requirements(req)`
  - tool: `confirm_requirements(confirm: bool = True)`

### 6) Fix competence matching producing incorrect `Low` results

Investigate and fix why "Cloud expert" + "AWS" competences yields `Low` across all capacities.

Hypotheses:
- Requirements extraction produces empty or wrong competences.
- Competence normalization / matching thresholds could be misapplied.

Deliverables:
- Add a regression test reproducing the AWS case.
- Ensure competence scoring uses the extracted competences correctly.

Capacity scoring UX note:
- Keep numeric scores (`overall_score`, `competence_score`, `role_score`) visible.
- Emphasize categorical results (`Top`/`Good`/`Partial`/`Low`) as the primary interpretation in docs and tables.

### 7) Fix search cache expiry / invalid IDs in multi-step tools

Observed:
- `filter_search_results` and `get_results_by_category` sometimes return
  "Unknown or expired search_id".

Additional observed behavior in chat clients:
- Some clients shorten, reformat, or accidentally reuse a previous `search_id`
  when the user requests another category (e.g. "show Good results").

Assumption:
- The server process is continuous (no restart between tool calls).

Likely causes to verify (not only TTL):
- **Eviction due to `[cache].max_size`** (entry removed even within TTL).
- Search IDs **not stored** on all paths (serialization error, early return, etc.).
- **ID formatting/copy issues** (backticks/whitespace) in client UIs.
- Hidden **process restarts / multiple instances** in the client environment.

Proposed fixes:
- Verify `SearchCache` TTL configuration and access.
- Verify and test behavior under max-size eviction.
- Ensure IDs are stored on every `store_search` call.
- Add troubleshooting guidance to copy IDs without surrounding formatting.
- Ensure search tools return a machine-readable JSON block containing IDs:
  - `find_matching_capacities` returns `{search_id, filter_id=null}`
  - `filter_search_results` returns `{search_id, filter_id}`
  - `get_results_by_category` echoes `{search_id, filter_id, category, page, ...}`
- Reject non-UUID `search_id` values early (clear message: expected UUID).
- Track latest `search_id` server-side (session state) for diagnostics only; **no** "get last search id" tool is provided.

### 8) Documentation updates

Update:
- `README.md`
- `docs/troubleshooting.md`
- OpenSpec design/architecture docs

…to reflect:
- new/changed tool outputs
- `infer_roles`
- guided capture step tools
- confirmation requirement
- role inference and capacity scoring UX (categorical)
- cache behavior expectations

## Implementation Task List

### A. Tool output refactors

1. Update `get_task_details` to produce the new table-first format.
2. Implement `infer_roles` and reuse it from `get_task_details`.
3. Update `validate_task_requirements` output as specified.
4. Add/adjust markdown table helpers if needed (column wrapping, newline handling).

### B. Role inference and extraction robustness

5. Review role/requirements extraction prompts and output validation.
6. Add regression tests for:
   - role inference
   - AWS/cloud expert competence matching not collapsing to `Low`

### C. Guided capture + confirmation flow

7. Design a minimal state machine for guided capture in `SessionState`.
8. Implement step-specific guided tools:
   - `start_guided_capture`
   - `guided_set_description`
   - `guided_set_role`
   - `guided_set_time_range`
   - `guided_set_competences`
9. Add `matching.require_confirmation` to the configuration model + loader (default: `true`).
10. Implement shared confirmation tool `confirm_requirements(confirm: bool = True)`.
11. Refactor `extract_requirements` and structured/guided collection tools to set pending requirements and instruct confirmation.
12. Refactor matching tools to hard-enforce confirmation unless `matching.require_confirmation = false`.

### D. Search cache reliability

13. Diagnose and fix `SearchCache` invalidation/expiry issues.
14. Add tests covering:
    - storing search results
    - subsequent filtering
    - pagination
    - TTL behavior
    - max-size eviction behavior
15. Add (optional) diagnostic support for identifying server instance continuity.

### E. Documentation and specs

16. Update `README.md` for the new workflow and new tools.
17. Update `docs/troubleshooting.md` with Cherry Studio guidance for multi-step flows (including ID copy hygiene and cache eviction notes).
18. Update OpenSpec design and architecture notes for guided capture, confirmation, and categorical-first scoring (numeric scores remain visible).

## Open Questions / Clarifications Needed

- (resolved) `infer_roles` output should be `Rank | Role | Rationale` only (no numeric score).
- (resolved) Guided time ranges should allow open-ended ranges (either start or end may be omitted).