tech-radar-boot

Overview

One of the five class boots surfaced by team-boot's Class Boots catalog, this skill handles technology selection. It surfaces Tikal's opinion on the technologies relevant to the current prompt so a tech stack choice is informed by the Israeli Tech Radar, and it pairs the selection with a capture suggestion: the chosen stack is an ADR-class decision; the boot suggests /architect-specify and never writes drafts itself.

The radar lookup works like team-discover, but its search surface is the adlc-radar OKF knowledge repository (gitlab.tikalk.dev/tikalk/engineering/agentic-sdlc/adlc-radar) instead of the team CDR index: it extracts candidate technologies from the prompt, matches them against radar technology documents, and injects a compact Tech Radar Context table (ring, quadrant, Tikal's "Why" opinion) plus Tikal-aligned alternatives for anything on Stop.

knowledge/technologies/ is the system of record — one Markdown document per technology with OKF frontmatter and ## Why / ## Description sections. radar.json in that repository is generated output from those documents and MUST NOT be treated as the knowledge source; the helper reads the Markdown.

The radar has four quadrants — DevOps, Backend, AI/ML, Web/Mobile — and four adoption rings:

Each technology document's ## Why section carries Tikal's explicit stance and rationale — that is the opinion to surface. A technology may appear more than once (different quadrants) with different rings; report each relevant placement.

When to Use

Model-invoke this skill whenever the prompt involves choosing or evaluating technology, for example:

• Selecting a framework, library, database, message broker, or cloud tool.
• Comparing options ("X vs Y", "should we use Z").
• Designing a system, service, or pipeline where stack decisions are implied.
• Reviewing an existing stack for modernization or replacement.
• A tech stack choice emerges mid-session (the ADR detection trigger).

Do not invoke it for pure business/product questions with no technology selection, or when the user explicitly says to ignore the radar.

Invoke at the START of a matching task — before planning the todo list and before implementation — so the radar context informs planning. Never defer to session end.

Manual invocation:

/tech-radar-boot               # inject radar context for the current prompt
/tech-radar-boot redis vs kafka

(/tech-radar-context still works as a deprecated alias for this skill.)

Core Process

Step 1: Extract Candidate Technologies

From the current prompt (or the description provided by an invoking skill), extract every named or clearly implied technology: languages, frameworks, libraries, databases, brokers, CI/CD tools, cloud services, AI/LLM tooling, build tools, etc. Normalize obvious aliases (e.g. "postgres" → "PostgreSQL", "k8s" → "Kubernetes", "GH Actions" → "GitHub Actions").

If the prompt implies a category without naming a product (e.g. "we need a vector database", "pick a Python web framework"), treat the category as a query and surface the radar's recommended options in that space.

Step 2: Query the Radar Knowledge Tree

Execute the deterministic search helper script (relative to this skill directory):

POSIX (bash + jq):

bash scripts/bash/radar-search.sh <tech1> [tech2 ...]

Windows (PowerShell):

pwsh scripts/powershell/radar-search.ps1 <tech1> [tech2 ...]

Or for JSON output (add --json for bash, -Json for PowerShell).

The helper:

1. keeps a shallow git clone of the adlc-radar repository in a cache directory (${XDG_CACHE_HOME:-$HOME/.cache}/adlc/radar by default) and refreshes it when the checkout is older than ADLC_RADAR_TTL (default 3 days). --refresh (-Refresh) forces a refresh;
2. parses each knowledge/technologies/<quadrant>/<slug>.md document's frontmatter (title, quadrant, ring, include) and its ## Why section — no HTML parsing, no radar.json;
3. handles alias mapping (k8s → Kubernetes, postgres → PostgreSQL, gh actions → GitHub Actions, etc.);
4. formats the markdown table automatically.

Filters mirror the repository's own tools/search.py: --quadrant <Q>, --ring <R>, --limit <N> (-Limit) for category matches, and --include-excluded (-IncludeExcluded) to include documents marked include: no (they are records excluded from the generated radar and are skipped by default).

If a technology appears in multiple placements with conflicting rings, the script detects and flags it with a Conflicting Guidance note.

Environment overrides: ADLC_RADAR_URL, ADLC_RADAR_BRANCH, ADLC_RADAR_CACHE, ADLC_RADAR_REPO (use an existing local clone and skip git network calls), ADLC_RADAR_TTL, ADLC_RADAR_FALLBACK_URL, ADLC_RADAR_CONNECT_TIMEOUT.

Step 3: Match Technology Documents

For each candidate from Step 1, the helper matches document titles (case-insensitive, alias-aware, allowing minor version suffixes like "Airflow 2" / "Airflow 3" and partial matches like "Redux" → "Redux Toolkit"). A candidate may match documents in multiple quadrants — keep them all.

For category queries (Step 1), the helper falls back to body-term ranking (title hits weigh more than Why hits) and returns the strongest radar recommendations in that space: prefer Keep/Start placements in the matching quadrant, and note any Stop placements as things to avoid.

When you need the full rationale (user is weighing the technology, or the ring is Stop), open the matched document by path and read its ## Why section in full. Follow the repository's navigation rule: knowledge/index.md → quadrant index → the single technology document. Load only the documents the current question needs; never bulk-load knowledge/technologies/.

Step 4: Extract Tikal's Opinion

For every matched document, ## Why is Tikal's opinion / rationale — the primary signal. ## Description is neutral background — use it only if helpful.

Condense ## Why to one or two sentences for the context table (quote it more fully when the ring is Stop or when the user is directly weighing that technology). The helper truncates the table cell; open the document when the full text matters.

Step 5: Recommend Alternatives for Stop

When a candidate matches a Stop document (or is a legacy technology the radar clearly discourages), select Tikal-aligned replacements from the same quadrant on Keep or Start, guided by the ## Why text. Common examples the dataset supports:

• Airflow 2 → Airflow 3 / Dagster
• Create React App → Vite / Next.js
• Jenkins → GitHub Actions / GitLab CI / Tekton
• requirements.txt / Poetry → uv
• Moment.js / Luxon → day.js / date-fns
• Redux / Redux Toolkit → Zustand / TanStack Query
• Ant Design / Styled Components → Tailwind CSS / shadcn/ui / Radix UI

Do not hardcode substitutions beyond what the loaded documents support — derive alternatives from the radar's actual Keep/Start technologies in that quadrant.

Absent Context

If team-boot injected no team context this session (no Team Context & Decisions section in the first user message — unconfigured project or hook failure): say so in one line, emit the section heading with a 0 radar technologies matched (no team context injected — run /team-setup) source line, and continue the task on the radar lookup. Never treat a missing injection as an empty record set. Recovery: run /team-diagnose.

Step 6: Inject Tech Radar Context (Output Contract)

The script's stdout goes to the tool channel — invisible to the user. ALWAYS re-emit the full Tikal Tech Radar Context section in your visible response, before the task answer (or, when 0 matched, the heading + _Source: line). Emit it as markdown blocks — heading, table rows, guidance bullets, and source line each on their own lines; never collapse the section into a single line.

## Tikal Tech Radar Context

| Technology | Quadrant | Ring | Tikal's Opinion (Why?) |
|------------|----------|------|------------------------|
| FastAPI | Backend | Keep | Better alternative to Flask; async, fast, big and growing community. |
| Jenkins | Backend | Stop | Plugin hell + XML config; legacy vs GitHub Actions / GitLab CI / Tekton. |

**Radar guidance**
- ✅ Keep/Start: FastAPI — safe to adopt.
- ⚠️ Stop: Jenkins → consider GitHub Actions, GitLab CI, or Tekton (see Why? above).

_Source: Tikal Israeli Tech Radar — adlc-radar OKF tree (main@abc1234, synced 2026-10-24T10:00:00Z) · 408 documents scanned, 2 placement(s) matched._

_Searched 408 documents, 2 matched._

• One row per matched placement (include duplicates across quadrants when relevant).
• If the helper printed a > ⚠️ notice (stale cache or public-JSON fallback), re-emit that notice verbatim above the table — the user must know which data source answered.
• Group a short Radar guidance list: safe-to-adopt vs avoid-with-alternatives.
• Add a _Source_ line naming the exact source the helper reported:
  • OKF tree: adlc-radar OKF tree (<branch>@<sha>, synced <timestamp>).
  • Stale: the same line plus ; STALE — <reason>.
  • Fallback: FALLBACK public radar.json (<url>).
• N = documents scanned (blips on the fallback path); K = rows shown in the table. K MUST equal the table rows shown. 0 rows matched → emit the section heading + the _Source: line only — no table. A 0-row table header collapses into unrendered single-line markdown; never emit one.

If no candidate technology matches any document, state that plainly with the heading + _Source: line (e.g. _Source: … · 0 technologies matched._) — no table — do not fabricate radar placements.

Step 7: Capture the Selection (Decision Pairing)

A technology selection is an ADR-class decision. When no local memory index exists in the current working directory and the directory sits inside a workspace (detected via a .gitmodules marker in an ancestor), read the workspace root's docs/adlc/memory/ index instead (the dual-read order applies: docs/adlc/memory first, legacy .adlc/memory fallback).

Add/refresh rows in Team Context & Decisions (ID | Name | Type | Rel | Status | Clarify) for the selection, mirrored as a task-list todo (suggest /architect-specify → matching clarify skill at session end for drafts that exist); after code-modifying tasks, add a trailing todo to sweep Team Context & Decisions until Unrecorded: 0 pending · Unclarified: 0 drafts (a draft leaves Unclarified only via its clarify skill or an explicit user handoff to a named clarify or execute skill). If architect-boot was already invoked this session, extend its ledger rows with the radar evidence; at session end, deliver the clarify prompt naming each uncaptured tech-selection decision (ID + capture skill) and each captured draft (ID + clarify skill); if the user defers clarify, mark those rows handed off.

Failure Handling

The helper resolves its data source in this order and always reports which one answered:

1. OKF knowledge tree — cached shallow clone, refreshed inside the TTL.
2. Stale OKF tree — the repository is unreachable (no SSH key, offline, transient failure) but a previous clone exists: the helper uses it and prints a > ⚠️ staleness notice. Re-emit that notice; never present stale data as current.
3. Public radar JSON — no usable clone at all: the helper announces that it is working with https://tikalk.com/radar.json (generated from the same knowledge tree, possibly lagging it) and answers from it. Re-emit that notice in your visible response.
4. Unavailable — both the repository and the public JSON fail: emit the heading with _Source: … radar unavailable … · 0 technologies matched._ and continue the user's task without radar context.

Never substitute fabricated data, and never claim the OKF tree answered when the notice says otherwise.

Red Flags

• Fabricating a ring, quadrant, or "Why" opinion for a technology that is not in the loaded dataset — report 0 matches instead.
• Reading radar.json from the knowledge repository as if it were the system of record — knowledge/technologies/ is canonical and radar.json is generated output.
• Silently hiding a stale-cache or public-JSON fallback notice.
• Hardcoding Stop→alternative substitutions not backed by the loaded documents.
• Reporting the neutral ## Description text as Tikal's opinion — the opinion lives in ## Why.
• Ignoring duplicate placements: the same technology can sit in different quadrants with different rings; surface each relevant placement.
• Bulk-loading knowledge/technologies/ instead of following index → quadrant → technology document.
• Treating the skill load as the work — the Core Process must actually run and produce the Tech Radar Context table.
• Reading radar findings via the script and answering without re-emitting the context section (script stdout goes to the tool channel — invisible to the user) — the visible response MUST carry the findings.
• Collapsing the context section into a single line — heading, table rows, guidance, and source line each go on their own markdown lines.
• Injecting radar context but skipping the capture suggestion — a tech selection that informed no ADR is a decision that evaporated.
• Writing a draft (or any file) yourself — the boot only suggests; /architect-specify writes.

Verification

• Candidate technologies were extracted from the prompt (or category queries formed when no product was named).
• The helper read the adlc-radar OKF knowledge tree (or reported, with a visible notice, that it used the stale clone or the public JSON fallback).
• A Tikal Tech Radar Context table was produced with columns Technology / Quadrant / Ring / Tikal's Opinion (Why?), with the opinion sourced from the document's ## Why section.
• Stop-ring matches include Tikal-aligned Keep/Start alternatives from the same quadrant, derived from the loaded documents.
• A _Source_ line reports the resolved source (OKF tree SHA + sync time, stale, or fallback) and the match count; a no-match run yields no table (heading + source line only) rather than fabricated data. On total unavailability, an error is reported and the skill continues without radar context.
• Tech selections made this session appear in Team Context & Decisions with /architect-specify as the capture skill, each carrying a _Suggested capture: … → run /architect-specify._ line; no files were written by this skill.

Configuration

• Knowledge source: git@gitlab.tikalk.dev:tikalk/engineering/agentic-sdlc/adlc-radar.git (knowledge/technologies/), cached as a shallow clone and refreshed after 3 days (ADLC_RADAR_TTL, default 259200 seconds; --refresh forces it).
• Cache location: ${XDG_CACHE_HOME:-$HOME/.cache}/adlc/radar (ADLC_RADAR_CACHE). ADLC_RADAR_REPO points the helper at an existing local clone instead (no git network calls — useful when developing the radar repository).
• Public fallback: https://tikalk.com/radar.json (ADLC_RADAR_FALLBACK_URL), used only when no checkout is usable, always with a visible notice.
• Fetch security: the SSH fetch is non-interactive (BatchMode=yes, connect timeout 10s by default); the public fallback is pinned to HTTPS (--proto '=https') and fails closed. The fallback JSON is only parsed, never executed. Radar content is treated as data for display.
• Git failure, timeout, or malformed frontmatter degrades to the next source in the ladder; it never blocks the user's task.