agentleFS
fapariciorfaparicior/sdlc-skills/skills/architecture/adr-review-alternatives/SKILL.md

adr-review-alternatives

Skill2 starsChanged yesterdayMITView on GitHub

Research current technologies, benchmarks, and modern alternatives to ADRs using active web search. TRIGGER THIS SKILL when user mentions: review adr alternatives, analyze adr alternatives, research tech alternatives, evaluate tech stack, audit adr currency, compare adr technologies, check tech radar, or asks if our technologies are still optimal.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Default: Review all active ADRs in docs/adr/.

    line 40
  2. Very specific:

    Do not rely solely on pretraining memory.

    line 44
  3. Distinctive:

    Update summary table of recommendations (*Keep*, *Consider*, *Replace*).

    line 80
  4. Distinctive:

    If the analysis recommends an architectural modification:

    line 86
  5. Distinctive:

    Before ending your turn, verify every item below with concrete evidence (not just a checkmark).

    line 93

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

PROTOCOL: ADR-REVIEW-ALTERNATIVES (EXECUTION LEVEL 3)

<state_machine> CURRENT_STEP -> REQUIRED_TOOL -> REQUIRED_OUTPUT -> MANDATORY_HALT Step 1: Scope -> read_file (docs/adr/) -> Active ADRs in scope -> Continue to Step 2 Step 2: Web Research -> search_web (2026 benchmarks, adoption, pricing) -> Primary & secondary source evidence -> Continue to Step 3 Step 3: Tech Radar -> classify Adopt / Trial / Assess / Hold -> Quadrant mapping per technology -> Continue to Step 4 Step 4: Write Reports -> read_file(templates/TEMPLATE-*.md) -> ADR_ALTERNATIVES_ANALYSIS.md + EXECUTIVE_SUMMARY.md -> 🛑 HALT TURN (Present reports) </state_machine>

<execution_invariants>

  1. WORKFLOW IMMUTABILITY: Execute all steps in strict order (workflow structure = immutable | step reasoning = flexible).
  2. MANDATORY ACTIVE WEB SEARCH: Never rely solely on pretraining memory; execute live search_web queries for 2026 benchmarks and adoption.
  3. TEMPLATE LOCK: You MUST call read_file on templates/TEMPLATE-ADR_ALTERNATIVES_ANALYSIS.md and templates/TEMPLATE-EXECUTIVE_SUMMARY.md before writing the report artifacts.
  4. ESCAPE HATCH: If the situation does not fit the contract, do not silently improvise and do not force-fit: declare the deviation in one line and ask. </execution_invariants>

<output_contract>

  • TARGET_PATHS: docs/adr/_reports/ADR_ALTERNATIVES_ANALYSIS.md and docs/adr/_reports/EXECUTIVE_SUMMARY.md
  • SOURCE_TEMPLATES: templates/TEMPLATE-ADR_ALTERNATIVES_ANALYSIS.md and templates/TEMPLATE-EXECUTIVE_SUMMARY.md (MUST call read_file before writing)
  • SCHEMA_INVARIANCE: Preserve every H1/H2/H3 section heading and summary table schema verbatim.
  • ESCAPE_HATCH: Never silently omit or invent template sections. If a section genuinely does not apply, preserve the heading and write "N/A — [1-line rationale]", or halt and ask the user before deviating. </output_contract>

📋 Step-by-Step Workflow

1. Define Scope of Review

  • Default: Review all active ADRs in docs/adr/.
  • Scoped: Review a specific domain or ADR requested by the user (e.g., ORM, Auth, Framework).

2. Conduct Active Web Research

Do not rely solely on pretraining memory. Execute active web searches (search_web) using targeted 2026 query templates:

Query Patterns

# Alternatives & Comparisons
"[Technology] alternatives 2026"
"[Tech A] vs [Tech B] 2026 comparison"
"best [category] for TypeScript 2026"

# Benchmarks & Performance
"[Technology] performance benchmarks 2026"
"[Technology] bundle size comparison"

# Industry Adoption & Surveys
"State of [category] 2026 survey"
"[Technology] adoption trends 2026"

# Pricing & Scalability
"[Technology] pricing free tier 2026"
"[Technology] cost at scale"

Evaluation Priorities

  1. Primary Sources (High): Official documentation, GitHub repos with recent commits, State of JS surveys, official engineering blogs.
  2. Secondary Sources (Medium): Tech comparison articles from 2025–2026, tech conference presentations, community discussions (Hacker News, Reddit r/webdev).
  3. Discard (Low): Marketing fluff without metrics, tutorials from 2023 or earlier.

3. Apply Tech Radar Classification

Categorize each candidate technology into one of 4 quadrants:

  • Adopt: Mature, rock-solid industry standard with massive support.
  • Trial: Promising, production-ready alternative worth testing in a small feature or spike.
  • Assess: Emerging technology to watch closely without adopting yet.
  • Hold: Deprecated, stagnating, or accumulating severe community friction.

4. Update Report Artifacts

  1. Update docs/adr/_reports/ADR_ALTERNATIVES_ANALYSIS.md:
    • Update summary table of recommendations (Keep, Consider, Replace).
    • Detail the findings per ADR: modern alternatives, performance, DX, and research notes with search queries executed.
  2. Update docs/adr/_reports/EXECUTIVE_SUMMARY.md:
    • High-level overview for the team with immediate vs. future recommendations.

5. Transition to Action

If the analysis recommends an architectural modification:

  • Suggest /amend-adr if the existing technology should be used differently (e.g. adding an abstraction).
  • Suggest /create-adr to draft a replacement ADR and mark the old one as Superseded.

<self_validation_gate> Before ending your turn, verify every item below with concrete evidence (not just a checkmark). If any item cannot be cited with real evidence from this turn, DO NOT produce your final response — fix the violation first:

  • Web Search Evidence: Exact search_web queries executed in this turn and URLs cited: <N queries, M sources>
  • Template Read Evidence: Exact paths passed to read_file (templates/TEMPLATE-ADR_ALTERNATIVES_ANALYSIS.md & templates/TEMPLATE-EXECUTIVE_SUMMARY.md): <paths>
  • Output & Schema Evidence: Exact report paths written (docs/adr/_reports/*.md) with Tech Radar classifications (Adopt / Trial / Assess / Hold) and any "N/A — [rationale]" sections noted: <paths> </self_validation_gate>

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.