adr

/adr — Architecture Deep Research

When the user invokes /adr (or asks any of the trigger questions in the description above), do the following.

Step 1. Confirm the decision name

Ask the user one question, in chat:

What's the architecture decision you're making? (e.g. "event bus topology", "retrieval architecture", "auth provider")

Capture their answer as <DECISION>.

If the user already named the decision when they invoked the skill, skip the question.

Step 2. Run discover-first deep-research via the MCP server

Call the adr_deep_research MCP tool with these arguments:

{
  "discover_first": true,
  "repo_path": ".",
  "domain": "<infer from the user's project — read README/package.json/etc. if needed>",
  "decision": "<DECISION>",
  "out_dir": ".adr-runs/<short-slug-of-decision>"
}

This will:

1. Scan the user's repo and draft a PRD (no network calls).
2. Run the full ADR pipeline against the draft (research, knowledge map, comparison matrix, synthesis, citation audit, evaluation pack).
3. Return the parsed execution-handoff.json so you can summarize the decision.

A run typically takes 3–6 minutes. Tell the user roughly how long it'll take before calling the tool so the wait doesn't feel like a hang.

Step 3. Summarize the result

The tool response includes:

• handoff.selected_topology — the chosen architecture family
• handoff.required_invariants — non-negotiable constraints
• handoff.forbidden_topologies — what NOT to do
• handoff.critique_summary.recommend_human_review — if true, the kernel is telling you the decision is borderline
• handoff.comparison_matrix_summary — candidate count, empty cells
• handoff.citation_audit_summary — how many citations verified

Show the user a 3–5 line summary:

Selected: <topology>
Required: <2 most important invariants>
Avoid:    <forbidden topologies>
<if recommend_human_review: "⚠ recommend_human_review=true — see ADR.md for the borderline.">

Then offer to:

• Open ADR.md for the full human-readable decision record
• Walk through the comparison matrix
• Implement using execution-handoff.json as the contract