# Tech Radar Boot

> Use when choosing or evaluating a technology (framework, database, library, cloud tool) — injects Tikal Israeli Tech Radar context (adoption ring, quadrant, opinion, Keep/Start alternatives for Stop items) from the adlc-radar OKF knowledge repository, and pairs the selection with ADR capture via /architect-specify; invoked from team-boot's Class Boots catalog (formerly tech-radar-context).

- Skill: `tikalk/tech-radar-boot` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add tikalk/tech-radar-boot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tikalk/tech-radar-boot/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tikalk (https://skillmd.com/u/tikalk)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/tikalk/tech-radar-boot

---


# 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**:

| Ring | Meaning | Guidance |
|------|---------|----------|
| `Try` | New stuff that on the surface seems good (good press, new solution) | Explore / evaluate; not yet endorsed for production use |
| `Start` | A good solution more companies should use; if in beta, active progress and contribution | Recommend adopting on new projects |
| `Keep` | Stable release (non-beta) with major supporter acceptance (large community, used by corporates) | Recommend by default for current & new work |
| `Stop` | Items we recommend companies stop using — better alternatives exist | Warn against; recommend a `Keep`/`Start` alternative |

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
bash scripts/bash/radar-search.sh <tech1> [tech2 ...]
```

Windows (PowerShell):
```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.

```markdown
## 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, never a table header.

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).

| Trigger | Action |
|---------|--------|
| Tech stack chosen ("we'll use X") | ADR → suggest `/architect-specify`, citing the radar rows that informed it |
| "X vs Y" comparison resolved | ADR → suggest `/architect-specify` with the comparison outcome |
| `Stop`-ring technology retained anyway | ADR → suggest `/architect-specify` documenting why the radar guidance was overridden |

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.

