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

> Change: `improve-task-details-role-inference-and-guided-flow`
> 
> Notes:
> - All code/doc/spec content stays in English.
> - Tool count is **not** limited.
> - Confirmation is **hard-gated** by default; can be auto-skipped via config.

## Status

- ✅ **Implemented** (core behavior + UX contracts shipped).
- 📝 Some follow-up items remain for additional hardening/coverage (diagnostics/logging and a few missing tests), but they do not block the change being considered implemented.

## 1. Proposal Alignment & Baseline

- [x] 1.1 Re-scan current tools in `src/teamlandkarte_mcp/mcp_server.py` and confirm required changes vs. current behavior.
- [ ] 1.2 Confirm existing `SearchCache` semantics (`ttl_minutes`, `max_size`) and how eviction is handled.
- [x] 1.3 Add/update a short architectural note: numeric scores remain visible, categories are primary.

## 2. Configuration: hard confirmation gate (+ optional auto-skip)

- [x] 2.1 Extend matching config model in `src/teamlandkarte_mcp/config.py`:
  - add `require_confirmation: bool = True` under `[matching]`.
- [x] 2.2 Update TOML loading/validation to accept `[matching].require_confirmation`.
- [x] 2.3 Update `database.toml.example` to document `require_confirmation` (default `true`).
- [ ] 2.4 Add tests for config parsing (default true, explicit false).

## 3. Session State: pending + confirmed requirements

- [x] 3.1 Extend `SessionState` in `src/teamlandkarte_mcp/mcp_server.py`:
  - pending requirements object
  - confirmed requirements object (or a confirmed flag/version)
  - guided capture state (see section 6)
- [x] 3.2 Implement internal helper(s):
  - `_set_pending_requirements(req: Requirements)`
  - `_require_confirmed_requirements_or_throw()` (implemented as `_require_confirmed_or_auto`)
- [x] 3.3 Implement tool: `confirm_requirements(confirm: bool = True)`.
- [x] 3.4 Update `extract_requirements`, `collect_structured_requirement_data`, `update_requirements`:
  - always write **pending** requirements
  - never implicitly run matching
  - include next-step guidance to call `confirm_requirements()`
- [x] 3.5 Update `find_matching_capacities` (and DB-backed matching tools) to **hard-enforce** confirmation when `matching.require_confirmation = true`.
- [x] 3.6 Auto-skip behavior:
  - when `matching.require_confirmation = false`, treat pending requirements as confirmed (no refusal).
- [x] 3.7 Add unit tests for confirmation gate behavior.

## 4. Tool: `infer_roles` (ranked roles, no score column)

- [x] 4.1 Add tool `infer_roles(task_id: Optional[str] = None, task_description: Optional[str] = None, limit: int = 5)`.
- [x] 4.2 Enforce input rules:
  - exactly one of `task_id` or `task_description` must be provided.
- [x] 4.3 If `task_id` provided:
  - fetch task from DB, use its description.
- [x] 4.4 Use `TaskAnalyzer.extract_ranked_roles(description, limit=...)`.
- [x] 4.5 Output a markdown table with columns:
  - `Rank | Role | Rationale`
- [ ] 4.6 Add tests for both modes (DB id mocked + free-text).

## 5. Tool output refactors

### 5.1 `get_task_details`

- [x] 5.1.1 Replace current multi-section output with:
  - a single markdown table: `Task ID | Title | Created (date only) | Start | End | Competences | Inferred Role`
  - below: task description
- [x] 5.1.2 Created date formatting: date-only (YYYY-MM-DD).
- [x] 5.1.3 Competences formatting: comma-separated, no numbering.
- [x] 5.1.4 Inferred role:
  - derive from role inference (reuse same analyzer call used by `infer_roles`)
  - show `(none)` if empty
- [ ] 5.1.5 Add/update tests asserting output format.

### 5.2 `validate_task_requirements`

- [x] 5.2.1 Replace current multi-table output with a **single** comparison table.
- [x] 5.2.2 Add a short textual summary below the table.
- [ ] 5.2.3 Add/update tests asserting table shape + summary presence.

## 6. Guided capture: step-specific tools

- [x] 6.1 Define guided capture state model (internal only).
- [x] 6.2 Implement tool `start_guided_capture()`.
- [x] 6.3 Implement tool `guided_set_description(description: str)`.
- [x] 6.4 Implement tool `guided_set_role(role_name: str)`.
- [x] 6.5 Implement tool `guided_set_time_range(date_start: Optional[str] = None, date_end: Optional[str] = None)`.
- [x] 6.6 Implement tool `guided_set_competences(competences: list[str])`.
- [ ] 6.7 Add tests covering the step transitions and open-ended ranges.

## 7. Competence matching regression (AWS/cloud)

- [x] 7.1 Reproduce reported case with a focused test (added deterministic similarity fallback to avoid collapse).
- [x] 7.2 Inspect `TaskAnalyzer` heuristic competence extraction and normalization.
- [x] 7.3 Inspect matching/scoring pipeline.
- [x] 7.4 Fix competence similarity computation so obvious matches ("AWS" vs "AWS") do not collapse.
- [ ] 7.5 Add regression test(s) to prevent reintroduction.

## 8. Search cache reliability

- [ ] 8.1 Add debug-level logging (stderr-safe) around:
  - `SearchCache.store_search` creation
  - `SearchCache.get` misses (include age/ttl if available)
  - eviction events (max_size)
- [ ] 8.2 Verify `max_size` eviction behavior in `SearchCache` implementation.
- [ ] 8.3 Add tests:
  - store -> filter -> paginate within TTL
  - behavior under forced max-size eviction
- [ ] 8.4 (Optional) Add a diagnostic tool returning `server_instance_id` to confirm process continuity during client tests.
- [x] 8.5 Update troubleshooting docs with:
  - ID copy hygiene (avoid extra backticks/whitespace)
  - max_size eviction symptom/fix

## 9. Documentation updates

- [x] 9.1 Update `README.md`.
- [x] 9.2 Update `docs/troubleshooting.md`.
- [x] 9.3 Update OpenSpec design/architecture docs under:
  - `openspec/changes/add-capacity-matching-mcp-server/` (historical baseline)

## 10. QA / Validation

- [x] 10.1 Run full test suite.
- [ ] 10.2 Manually validate in Cherry Studio (guide):
  - guided capture step tools
  - confirmation gating (on/off via config)
  - infer_roles output
  - get_task_details formatting
  - search cache persistence across multi-step tools