Orchestrator/bahn/teamlandkarte-mcp/.kiro/specs/capacity-details-enrichment/tasks.md

Implementation Plan: Capacity Details Enrichment

Overview

Extend the get_capacity_details tool in src/teamlandkarte_mcp/mcp_server.py to fetch and display description, references, and certificates for a capacity. The change is localized to the tool function with inline formatting. All DB client methods already exist.

Tasks

• 1. Extend get_capacity_details with enrichment data fetching and formatting

  • 1.1 Add DB calls for description, references, and certificates

    • After the existing get_capacity_by_id call, add sequential calls to db_client.get_capacity_description(capacity_id), db_client.get_capacity_references(capacity_id), and db_client.get_capacity_certificates(capacity_id)
    • Requirements: 1.1, 2.1, 3.1

  • 1.2 Format the Beschreibung section

    • If description is non-empty, render ## Beschreibung\n\n<text>
    • If description is None or empty, render ## Beschreibung\n\nBeschreibung: (keine)
    • Requirements: 1.2, 1.3

  • 1.3 Format the Referenzen section

    • If references exist, render ## Referenzen followed by bullet points: - **partner_name**: projects for each reference
    • If a reference has an empty partner_name, render only - projects (no bold partner prefix)
    • If no references exist, render ## Referenzen\n\nReferenzen: (keine)
    • Requirements: 2.2, 2.3, 2.4

  • 1.4 Format the Zertifizierungen section

    • If certificates exist, render ## Zertifizierungen followed by bullet points: - certificate for each entry
    • If no certificates exist, render ## Zertifizierungen\n\nZertifizierungen: (keine)
    • Requirements: 3.2, 3.3

  • 1.5 Assemble output in fixed section order

    • Combine sections in order: capacity table, Beschreibung, Referenzen, Zertifizierungen, Next Steps
    • Separate each section with a blank line
    • Requirements: 4.1, 4.2

• 2. Write unit tests for the enriched output

  • 2.1 Test full data scenario

    • Mock DB client to return a known description, list of references (with and without partner_name), and list of certificates
    • Assert output contains all expected section headers, content, and correct ordering
    • Create test file tests/test_capacity_details_enrichment.py
    • Requirements: 1.2, 2.2, 2.3, 3.2, 4.1

  • 2.2 Test empty-state scenario

    • Mock DB client to return None description, empty references list, empty certificates list
    • Assert output contains "(keine)" placeholders for all three sections
    • Requirements: 1.3, 2.4, 3.3

  • 2.3 Test capacity-not-found unchanged

    • Mock get_capacity_by_id to return None
    • Assert the tool still returns the existing error message without calling enrichment methods
    • Requirements: (error handling, no regression)

• 3. Checkpoint

  • Ensure all tests pass, ask the user if questions arise.

• 4. Property-based tests with Hypothesis

  • 4.1 Write property test: All enrichment data is fetched

    • Property 1: All enrichment data is fetched for any capacity
    • Generate random capacity IDs; mock DB to return a capacity. Verify get_capacity_description, get_capacity_references, and get_capacity_certificates are each called exactly once with the correct ID.
    • Create test file tests/test_capacity_details_enrichment_pbt.py
    • Validates: Requirements 1.1, 2.1, 3.1

  • 4.2 Write property test: Non-empty data appears in output

    • Property 2: Non-empty data appears in output
    • Generate random non-empty descriptions (text strategy), random lists of CapacityReferenceRow dicts with non-empty projects and partner_name, and random lists of non-empty certificate strings. Assert all generated data appears in the formatted output.
    • Validates: Requirements 1.2, 2.2, 3.2

  • 4.3 Write property test: Section ordering is fixed

    • Property 3: Section ordering is fixed
    • Generate random combinations of present/absent data (description: str|None, references: 0-5 items, certificates: 0-5 items). Assert section headers appear in the correct order with blank-line separation.
    • Validates: Requirements 4.1, 4.2

• 5. Final checkpoint

  • Ensure all tests pass, ask the user if questions arise.

• 6. Update agent skill documentation

  • 6.1 Update .github/skills/capacity-browsing/SKILL.md
    • Change the get_capacity_details description to mention description, references, and certifications alongside role, competences, and availability window
  • 6.2 Update .kiro/agents/teamlandkarte.md
    • Change the get_capacity_details description to mention that it shows description, references, and certifications alongside the basic profile

Notes

• Tasks marked with * are optional and can be skipped for faster MVP
• The implementation language is Python (matching the existing codebase and design)
• All DB client methods (get_capacity_description, get_capacity_references, get_capacity_certificates) already exist — no data layer changes needed
• Property tests use Hypothesis with @settings(max_examples=100)