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.
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- adr-amendSkill
- adr-createSkill
- adr-validateSkill
- agents-maintainerSkill
- audit-docsSkill
- explore-domainSkill
- sdlc-guideSkill
- setup-sdlcSkill
- inception-workshopSkill
- prd-workshopSkill
- user-story-mappingSkill
- modify-flowSkill
- reverse-engineer-domainSkill
- create-moduleSkill
- implement-flowSkill
- create-entity-lifecycleSkill
- create-featuresSkill
- create-flow-documentationSkill
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
- Very specific: line 40
Default: Review all active ADRs in docs/adr/.
- Very specific: line 44
Do not rely solely on pretraining memory.
- Distinctive: line 80
Update summary table of recommendations (*Keep*, *Consider*, *Replace*).
- Distinctive: line 86
If the analysis recommends an architectural modification:
- Distinctive: line 93
Before ending your turn, verify every item below with concrete evidence (not just a checkmark).
≈ “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.
Files
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>
- WORKFLOW IMMUTABILITY: Execute all steps in strict order (
workflow structure = immutable | step reasoning = flexible). - MANDATORY ACTIVE WEB SEARCH: Never rely solely on pretraining memory; execute live
search_webqueries for 2026 benchmarks and adoption. - TEMPLATE LOCK: You MUST call
read_fileontemplates/TEMPLATE-ADR_ALTERNATIVES_ANALYSIS.mdandtemplates/TEMPLATE-EXECUTIVE_SUMMARY.mdbefore writing the report artifacts. - 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.mdanddocs/adr/_reports/EXECUTIVE_SUMMARY.md - SOURCE_TEMPLATES:
templates/TEMPLATE-ADR_ALTERNATIVES_ANALYSIS.mdandtemplates/TEMPLATE-EXECUTIVE_SUMMARY.md(MUST callread_filebefore 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
- Primary Sources (High): Official documentation, GitHub repos with recent commits, State of JS surveys, official engineering blogs.
- Secondary Sources (Medium): Tech comparison articles from 2025–2026, tech conference presentations, community discussions (Hacker News, Reddit r/webdev).
- 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
- 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.
- 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-adrif the existing technology should be used differently (e.g. adding an abstraction). - Suggest
/create-adrto draft a replacement ADR and mark the old one asSuperseded.
<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_webqueries 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>
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
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.

