review_adr
Analyze Architecture Decision Records for completeness, identify missing context, unconsidered alternatives, and optimistic consequences to improve decision quality.
Instructions
AI quality review of an ADR — scores completeness, flags missing context, unconsidered alternatives, and optimistic consequences
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| adr_id | Yes | ADR ID to review |
Implementation Reference
- adr.js:42-84 (handler)The implementation of the ADR review logic which calls the Claude API.
export async function reviewADR(adr) { const stream = client.messages.stream({ model: 'claude-opus-4-6', max_tokens: 2048, thinking: { type: 'adaptive' }, system: `You are a senior software architect reviewing Architecture Decision Records for quality and completeness. Evaluate the ADR critically and return a JSON review with this exact structure: { "score": <integer 0-100>, "summary": "One-sentence overall assessment", "issues": [ { "severity": "high|medium|low", "field": "context|decision|consequences|title", "message": "specific problem description" } ], "suggestions": [ "Concrete, actionable improvement suggestion" ] } Evaluate against these criteria: - Context: Is the problem clearly stated? Are constraints and forces explained? - Decision: Are alternatives considered and rejected? Is the rationale explicit? - Consequences: Are both positive and negative outcomes listed? Are risks acknowledged? - Title: Does it capture the decision, not just the topic?`, messages: [ { role: 'user', content: `Review this ADR for quality:\n\n# ${adr.title}\n\n## Context\n${adr.context}\n\n## Decision\n${adr.decision}\n\n## Consequences\n${adr.consequences}`, }, ], }); const response = await stream.finalMessage(); for (const block of response.content) { if (block.type === 'text') { const match = block.text.match(/\{[\s\S]*\}/); if (match) return JSON.parse(match[0]); } } throw new Error('Failed to parse review JSON from AI response'); } - index.js:157-192 (registration)Registration of the `review_adr` tool and its MCP handler.
server.registerTool('review_adr', { description: 'AI quality review of an ADR — scores completeness, flags missing context, unconsidered alternatives, and optimistic consequences', inputSchema: { adr_id: z.number().describe('ADR ID to review'), }, }, async ({ adr_id }) => { if (!process.env.ANTHROPIC_API_KEY) { throw new Error('ANTHROPIC_API_KEY is required for AI review'); } const adr = getADR(adr_id); if (!adr) throw new Error(`ADR ${adr_id} not found`); const review = await reviewADR(adr); const severityIcon = { high: '🔴', medium: '🟡', low: '🟢' }; const issueLines = (review.issues ?? []) .map(i => `${severityIcon[i.severity] ?? '•'} [${i.field}] ${i.message}`) .join('\n') || 'No issues found'; const suggestionLines = (review.suggestions ?? []) .map((s, i) => `${i + 1}. ${s}`) .join('\n') || 'No suggestions'; const output = `## ADR-${adr_id} Review — Score: ${review.score}/100 **${review.summary}** ### Issues ${issueLines} ### Suggestions ${suggestionLines}`; return { content: [{ type: 'text', text: output }] }; });