---
name: tech-selection
description: Structured technology selection workflow for evaluating and choosing the right tool, library, or framework for a given problem. Use this skill whenever the user wants to find, compare, or decide on a technology — for example: "Which database should I use?", "What's the best library for X?", "Compare these three frameworks", "We need to pick a charting library", "Evaluate options for our new backend", "Help me choose between React and Vue". Also trigger when the user describes requirements for a new project component and asks what technology to use, or when they want to understand which existing tools might fit their codebase. This skill guides the full process from requirements capture through final decision documentation.
---

# Technology Selection Skill

A structured four-step workflow for selecting the right technology for a problem. Each step produces a concrete artifact; together they form a decision trail that is easy to revisit and share.

---

## Workspace-Hinweis: Zielplattform HVA Client Migration

> **Diese Regel gilt für alle Tech-Entscheidungen im HVA-Client-Migrationsprojekt.**
>
> Die Migration zielt auf **iPadOS** (Swift / SwiftUI). Die Plattformpriorität bei der Bewertung von Technologien ist:
>
> 1. **iPadOS** – primär und entscheidend. Läuft die Technologie nicht auf dem iPad, ist sie ungeeignet.
> 2. **macOS** – sekundär / nice-to-have. Unterstützung für den Mac-Build ist wünschenswert, aber kein K.O.-Kriterium.
> 3. **Windows** – irrelevant. Windows-Kompatibilität spielt bei der Entscheidung keine Rolle.
>
> Der Swift-on-Windows-Build dient ausschließlich CI-Zwecken (Kompilierbarkeit). Plattformspezifische Frameworks (WKWebView, AVFoundation, CoreBluetooth, ARKit, PDFKit, Firebase iOS SDK etc.) werden nach ihrer iPadOS-Verfügbarkeit bewertet, nicht nach Windows-Verfügbarkeit.

---

## Overview

| Step              | Goal                                                      | Output                             |
| ----------------- | --------------------------------------------------------- | ---------------------------------- |
| 1 – Requirements  | Capture what the technology must do                       | `requirements.md`                  |
| 2 – Research      | Find and score candidate technologies                     | `candidates.md`                    |
| 3 – Shortlist     | Present the top 5 and record the decision                 | Appended to `candidates.md`        |
| 4 – Compatibility | Check the chosen technology against the existing codebase | Report appended to `candidates.md` |

---

## Step 1 – Requirements Capture

The goal is to produce a `requirements.md` that clearly describes what the technology must and should do. There are two paths:

**Path A – From existing software**
Analyse the existing codebase or system to extract implicit requirements:

- Read the relevant source files, dependency manifests (`package.json`, `*.csproj`, `go.mod`, `requirements.txt`, etc.), and documentation.
- Identify what the current solution does, what pain points exist, and what constraints must be preserved (platform, language, license).
- Ask the user to confirm the inferred requirements and add anything missing.

**Path B – From a described catalogue**
The user has already described the requirements. Clarify anything ambiguous with targeted questions before proceeding. Typical things to pin down:

- Target platform / runtime environment
- Programming language or ecosystem
- Performance / scale requirements
- License constraints (MIT, Apache, commercial-friendly, etc.)
- Integration requirements (must work with X, Y)
- Maintenance expectations (actively maintained, long-term support)

**`requirements.md` format:**

```markdown
# Technology Requirements – <Topic>

Date: <ISO date>
Author: <context from conversation>

## Must-Have (eliminators)

- …

## Should-Have (weighted positives)

- …

## Nice-to-Have (bonus)

- …

## Constraints

- Platform: …
- Language ecosystem: …
- License: …
- Other: …
```

Save the file next to the relevant project or in the location the user specifies. If no location is specified, place it in the current working directory.

---

## Step 2 – Research and Candidate List

The goal is to find the broadest reasonable set of technology candidates and score each one. Use web search, package registries (npm, PyPI, Maven Central, crates.io, NuGet, pub.dev, etc.), GitHub, and any other available sources.

**What to look for:**

- Primary package repositories for the language/ecosystem
- Comparison articles and benchmark repositories
- GitHub stars, forks, and recent commit dates
- Release history and frequency (signals maintenance health)
- Community size (Stack Overflow tags, Discord/Slack servers, conference presence)

**For each candidate, collect:**

| Field                     | What it means                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------------- |
| **Name**                  | Official name + link to homepage or repo                                                       |
| **Short description**     | One sentence: what problem does it solve?                                                      |
| **Primary use case**      | The main domain it was built for                                                               |
| **Maturity**              | Age in years (approximate first stable release)                                                |
| **Adoption**              | Stars / downloads / company users — a qualitative label works: _niche / moderate / widespread_ |
| **Update rate / support** | Last release date, release cadence (quarterly / monthly / sporadic), open issue count trend    |
| **Requirement coverage**  | Which Must-Haves, Should-Haves, and Nice-to-Haves it satisfies — list them briefly             |
| **Score (1–10)**          | Your overall viability rating. See scoring rubric below.                                       |

**Scoring rubric:**

- **10** — covers all requirements, actively maintained, widespread adoption, no known blockers
- **7–9** — covers all must-haves, minor gaps in should-haves, healthy maintenance
- **4–6** — covers most must-haves, notable gaps or maintenance concerns
- **1–3** — significant must-have gaps or high risk (abandonware, security history, license issues)

A score below 4 is worth noting but exclude it from the shortlist.

**`candidates.md` format:**

```markdown
# Technology Candidates – <Topic>

Date: <ISO date>
Requirements file: <relative path to requirements.md>

## Candidate Table

| Name | Description | Use case | Age | Adoption | Last release | Update cadence | Req. coverage | Score |
| ---- | ----------- | -------- | --- | -------- | ------------ | -------------- | ------------- | ----- |
| …    | …           | …        | …   | …        | …            | …              | …             | …     |

## Candidate Details

### <Name>

**Homepage:** <URL>
**Repository:** <URL>

**Requirement coverage:**

- ✅ Must: <list>
- ✅ Should: <list>
- ⚠️ Missing: <list>

**Risks / notes:** <any concerns — license, security, ecosystem lock-in>
```

Save `candidates.md` in the same directory as `requirements.md`.

---

## Step 3 – Shortlist and Decision

Select the **five highest-scoring candidates** (break ties by adoption breadth) and present them to the user. Frame each one in plain language — what makes it a strong fit, and what the trade-off is.

**Presentation format:**

```
## Top 5 for <Topic>

1. **<Name>** (score 9) — <one-sentence pitch>
   Trade-off: <one sentence on the main downside or risk>

2. …
```

Then ask the user to choose, encouraging them to add a brief comment explaining their reasoning. The comment does not have to be long — even "simpler API" or "team already knows it" is valuable.

Once the user has decided, append the decision to `candidates.md`:

```markdown
## Decision

Chosen: **<Name>**
Date: <ISO date>
Decided by: <user / team>

Rationale: <user's comment, or a summary of the discussion>

Alternatives considered:

- <Name 2>: ruled out because <reason>
- <Name 3>: ruled out because <reason>
- …
```

---

## Step 4 – Compatibility Check

Before closing, inspect the existing codebase to check whether anything would prevent adopting the chosen technology, or whether a competing technology is already in use.

**What to look for:**

1. **Existing dependencies** — check all relevant manifests for packages in the same domain. If a competitor is already present, flag it clearly.
2. **Architectural patterns** — does the project use a pattern that the chosen technology requires to be restructured? (e.g., a framework-level router that conflicts)
3. **Platform / runtime constraints** — does the chosen technology support all target platforms already used in the project?
4. **License compatibility** — does the chosen license fit alongside the project's existing licenses?
5. **Version constraints** — minimum language version or runtime version required vs. what the project uses.

Report the findings honestly. Green findings are encouraging; orange findings (manageable friction) should be noted; red findings (blockers) must be flagged prominently and may warrant reconsidering the decision.

Append the compatibility report to `candidates.md`:

```markdown
## Compatibility Check

Checked against: <codebase path or project description>
Date: <ISO date>

| Area                  | Finding   | Status       |
| --------------------- | --------- | ------------ |
| Existing dependencies | <finding> | ✅ / ⚠️ / 🔴 |
| Architecture          | <finding> | ✅ / ⚠️ / 🔴 |
| Platform support      | <finding> | ✅ / ⚠️ / 🔴 |
| License               | <finding> | ✅ / ⚠️ / 🔴 |
| Version requirements  | <finding> | ✅ / ⚠️ / 🔴 |

**Overall:** <summary — clear path forward / manageable friction / blocker found>
```

If a red blocker is found, surface it explicitly and ask the user whether to revisit the shortlist or accept the risk.

---

## Workflow Notes

- You don't always need to start at Step 1. If the user already has requirements, start at Step 2. If they already have a shortlist, start at Step 3.
- Research breadth matters more than depth in Step 2. A wide initial list with honest scores is more useful than a narrow list with exhaustive details.
- The score is your opinion — be honest about uncertainty. If you couldn't find good maintenance data for a candidate, say so rather than guessing.
- Steps 1–3 produce files that become the project's permanent decision record. Write them as if a colleague will read them in six months without any context from this conversation.
