adr-review

Name: adr-review
Author: opendatahub-io

36stars74forks

How to install adr-review?

opendatahub-io/ai-helpers/adr-review

$npx -y skills add opendatahub-io/ai-helpers --skill adr-review

Installs into the current project.

Summary

Review an Architectural Decision Record (ADR) using a team of six specialist reviewer subagents and produce a consolidated report as both PDF and PPTX slide deck. Use this skill whenever the user asks to review, critique, audit, or get feedback on an ADR, architecture decision, d

Files · 1

View on GitHub

SKILL.md

1	# ADR Review Panel
2
3	This skill runs a panel of specialist reviewer subagents over an Architectural Decision Record (ADR) and produces a consolidated report in two formats: a PDF document and a PPTX slide deck.
4
5	## Why a panel of agents?
6
7	Architecture reviews benefit from multiple independent perspectives. A single reviewer tends to anchor on whichever concern they noticed first and under-weight the others. By running specialists in parallel, each focused on one dimension, we get broader, less-biased coverage — and the synthesis step surfaces tensions between perspectives (e.g. "the cheapest option is also the least reversible") that a single reviewer might flatten.
8
9	## Workflow
10
11	### Step 1 — Prompt for the ADR location and clarifying context
12
13	Always ask the user where the ADR is, even if there's a plausible file in context. Accepted inputs:
14
15	- A path to a Markdown file (`.md`, `.markdown`)
16	- A path to a Word document (`.docx`)
17	- A path to a directory containing multiple ADRs (review each one)
18
19	If the user provides a `.docx`, extract the text first using the `document-skills:docx` skill or `python-docx`. If they provide Markdown, read it directly.
20
21	Use the AskUserQuestion tool to gather any clarifying context the reviewers will need. Ask in a single AskUserQuestion call with multiple questions rather than one-at-a-time. Tailor the questions to what is actually unclear after a quick skim of the ADR — don't ask boilerplate. Typical useful questions:
22
23	- Audience & stakes — "Who is this review for (author self-check, formal arch board, post-incident retro)?" This shapes tone and severity thresholds.
24	- Scope — "Are there dimensions you want the panel to emphasize or skip?" (e.g., "skip cost, we already costed it elsewhere")
25	- Context not in the doc — "Is there background the ADR assumes readers already know? Team size, existing stack, regulatory environment?"
26	- Decision status — "Is this a draft open to changes, or has the decision already been made and you want a risk audit?"
27	- Known concerns — "Anything you're already worried about that you want the panel to focus on?"
28
29	Pass the answers into each reviewer subagent's prompt as a "Review context from the user" block so every reviewer sees the same framing.
30
31	### Step 2 — Read and normalize the ADR
32
33	Read the file and extract the key sections (context, decision, alternatives considered, consequences). ADRs vary in format (MADR, Nygard, custom) — don't require a specific structure, just pull out what's there. If a section is missing, note it; that absence is itself a finding the reviewers should know about.
34
35	### Step 3 — Dispatch the reviewer panel
36
37	Spawn six reviewer subagents in parallel using the Agent tool. Each gets the full ADR text plus its role-specific prompt from `references/reviewer_prompts.md`. Launch all six in a single message — do not serialize them.
38
39	The six reviewers are:
40
41	1. Context & Problem Framing — Is the problem and its forces clearly articulated? Are the stakeholders and constraints named? Were alternatives genuinely considered or is this a post-hoc rationalization?
42	2. Technical Soundness — Is the proposed solution technically correct and feasible? Does it match the problem? Are there known failure modes or anti-patterns?
43	3. Operational & Reliability — How will this be observed, deployed, and recovered? What are the failure modes in production? Is there a rollback plan? SLOs?
44	4. Security & Compliance — Threat model, data handling, authN/authZ, secrets, regulatory implications. What new attack surface does this introduce?
45	5. Cost & Performance — Resource footprint, cost trajectory at scale, latency/throughput characteristics, capacity planning.
46	6. Consequences & Reversibility — Are the trade-offs honestly stated? How hard is this to undo? Vendor/technology lock-in? Migration path if we change our minds?
47
48	Each reviewer must return a structured finding in this shape:
49
50	```markdown
51	## [Reviewer Name]
52	Overall assessment: [Strong / Acceptable / Concerns / Blocking]
53	Strengths: [bullets]
54	Concerns: [bullets, each with the structure below]
55	Open questions: [bullets]
56	Recommendations: [bullets]
57	```
58
59	Each concern must include enough detail for an architect unfamiliar with the review to understand the issue and act on it. Use this structure per concern:
60
61	```markdown
62	- **[severity: low / m

People who liked this also viewed

6 picks

Type

adr-review

36stars74forks

View on GitHub

How to install adr-review?

opendatahub-io/ai-helpers/adr-review

$npx -y skills add opendatahub-io/ai-helpers --skill adr-review

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# ADR Review Panel
2
3	This skill runs a panel of specialist reviewer subagents over an Architectural Decision Record (ADR) and produces a consolidated report in two formats: a PDF document and a PPTX slide deck.
4
5	## Why a panel of agents?
6
7	Architecture reviews benefit from multiple independent perspectives. A single reviewer tends to anchor on whichever concern they noticed first and under-weight the others. By running specialists in parallel, each focused on one dimension, we get broader, less-biased coverage — and the synthesis step surfaces tensions between perspectives (e.g. "the cheapest option is also the least reversible") that a single reviewer might flatten.
8
9	## Workflow
10
11	### Step 1 — Prompt for the ADR location and clarifying context
12
13	Always ask the user where the ADR is, even if there's a plausible file in context. Accepted inputs:
14
15	- A path to a Markdown file (`.md`, `.markdown`)
16	- A path to a Word document (`.docx`)
17	- A path to a directory containing multiple ADRs (review each one)
18
19	If the user provides a `.docx`, extract the text first using the `document-skills:docx` skill or `python-docx`. If they provide Markdown, read it directly.
20
21	Use the AskUserQuestion tool to gather any clarifying context the reviewers will need. Ask in a single AskUserQuestion call with multiple questions rather than one-at-a-time. Tailor the questions to what is actually unclear after a quick skim of the ADR — don't ask boilerplate. Typical useful questions:
22
23	- Audience & stakes — "Who is this review for (author self-check, formal arch board, post-incident retro)?" This shapes tone and severity thresholds.
24	- Scope — "Are there dimensions you want the panel to emphasize or skip?" (e.g., "skip cost, we already costed it elsewhere")
25	- Context not in the doc — "Is there background the ADR assumes readers already know? Team size, existing stack, regulatory environment?"
26	- Decision status — "Is this a draft open to changes, or has the decision already been made and you want a risk audit?"
27	- Known concerns — "Anything you're already worried about that you want the panel to focus on?"
28
29	Pass the answers into each reviewer subagent's prompt as a "Review context from the user" block so every reviewer sees the same framing.
30
31	### Step 2 — Read and normalize the ADR
32
33	Read the file and extract the key sections (context, decision, alternatives considered, consequences). ADRs vary in format (MADR, Nygard, custom) — don't require a specific structure, just pull out what's there. If a section is missing, note it; that absence is itself a finding the reviewers should know about.
34
35	### Step 3 — Dispatch the reviewer panel
36
37	Spawn six reviewer subagents in parallel using the Agent tool. Each gets the full ADR text plus its role-specific prompt from `references/reviewer_prompts.md`. Launch all six in a single message — do not serialize them.
38
39	The six reviewers are:
40
41	1. Context & Problem Framing — Is the problem and its forces clearly articulated? Are the stakeholders and constraints named? Were alternatives genuinely considered or is this a post-hoc rationalization?
42	2. Technical Soundness — Is the proposed solution technically correct and feasible? Does it match the problem? Are there known failure modes or anti-patterns?
43	3. Operational & Reliability — How will this be observed, deployed, and recovered? What are the failure modes in production? Is there a rollback plan? SLOs?
44	4. Security & Compliance — Threat model, data handling, authN/authZ, secrets, regulatory implications. What new attack surface does this introduce?
45	5. Cost & Performance — Resource footprint, cost trajectory at scale, latency/throughput characteristics, capacity planning.
46	6. Consequences & Reversibility — Are the trade-offs honestly stated? How hard is this to undo? Vendor/technology lock-in? Migration path if we change our minds?
47
48	Each reviewer must return a structured finding in this shape:
49
50	```markdown
51	## [Reviewer Name]
52	Overall assessment: [Strong / Acceptable / Concerns / Blocking]
53	Strengths: [bullets]
54	Concerns: [bullets, each with the structure below]
55	Open questions: [bullets]
56	Recommendations: [bullets]
57	```
58
59	Each concern must include enough detail for an architect unfamiliar with the review to understand the issue and act on it. Use this structure per concern:
60
61	```markdown
62	- **[severity: low / m

People who liked this also viewed

6 picks

Type