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

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

• 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.
• 1.3 Add/update a short architectural note: numeric scores remain visible, categories are primary.

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

• 2.1 Extend matching config model in src/teamlandkarte_mcp/config.py:
  • add require_confirmation: bool = True under [matching].
• 2.2 Update TOML loading/validation to accept [matching].require_confirmation.
• 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

• 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)
• 3.2 Implement internal helper(s):
  • _set_pending_requirements(req: Requirements)
  • _require_confirmed_requirements_or_throw() (implemented as _require_confirmed_or_auto)
• 3.3 Implement tool: confirm_requirements(confirm: bool = True).
• 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()
• 3.5 Update find_matching_capacities (and DB-backed matching tools) to hard-enforce confirmation when matching.require_confirmation = true.
• 3.6 Auto-skip behavior:
  • when matching.require_confirmation = false, treat pending requirements as confirmed (no refusal).
• 3.7 Add unit tests for confirmation gate behavior.

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

• 4.1 Add tool infer_roles(task_id: Optional[str] = None, task_description: Optional[str] = None, limit: int = 5).
• 4.2 Enforce input rules:
  • exactly one of task_id or task_description must be provided.
• 4.3 If task_id provided:
  • fetch task from DB, use its description.
• 4.4 Use TaskAnalyzer.extract_ranked_roles(description, limit=...).
• 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

• 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
• 5.1.2 Created date formatting: date-only (YYYY-MM-DD).
• 5.1.3 Competences formatting: comma-separated, no numbering.
• 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

• 5.2.1 Replace current multi-table output with a single comparison table.
• 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

• 6.1 Define guided capture state model (internal only).
• 6.2 Implement tool start_guided_capture().
• 6.3 Implement tool guided_set_description(description: str).
• 6.4 Implement tool guided_set_role(role_name: str).
• 6.5 Implement tool guided_set_time_range(date_start: Optional[str] = None, date_end: Optional[str] = None).
• 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)

• 7.1 Reproduce reported case with a focused test (added deterministic similarity fallback to avoid collapse).
• 7.2 Inspect TaskAnalyzer heuristic competence extraction and normalization.
• 7.3 Inspect matching/scoring pipeline.
• 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.
• 8.5 Update troubleshooting docs with:
  • ID copy hygiene (avoid extra backticks/whitespace)
  • max_size eviction symptom/fix

9. Documentation updates

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

10. QA / Validation

• 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