/adr-consultation

name: adr-consultation
description: "Multi-agent consultation for architecture decisions."
user-invocable: false
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash
  - Task
routing:
  triggers:
    - "consult on ADR"
    - "challenge this design"
    - "review before implementing"
    - "multi-agent consultation"
    - "architecture consultation"
    - "should we proceed"
    - "adr consultation"
  pairs_with:
    - feature-lifecycle
  complexity: Medium
  category: meta

ADR Consultation Skill

Multi-agent architecture consultation that dispatches 3 specialized reviewers in parallel against an ADR and synthesizes their findings into a PROCEED or BLOCKED verdict. This is the gate between feature-lifecycle plan and implement phases for Medium+ decisions because challenging architecture decisions before implementation prevents costly post-implementation rework.

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | Phase 2 DISPATCH: consultation agent prompt templates | `agent-prompts.md` | Loads detailed guidance from `agent-prompts.md`. | | orchestration corrections: dispatch, artifact, and verdict aggregation fixes | `consultation-preferred-patterns.md` | Loads detailed guidance from `consultation-preferred-patterns.md`. | | core consultation patterns and Phase 3 artifact templates | `consultation-patterns.md` | Loads detailed guidance from `consultation-patterns.md`. | | errors, error handling | `error-handling.md` | Loads detailed guidance from `error-handling.md`. |

Instructions

Phase 1: DISCOVER

**Goal**: Identify the ADR and prepare the consultation directory.

**Step 1: Locate the ADR**

Check for ADR path in this order: 1. User-provided path (e.g., `adr/intent-based-routing.md`) 2. Active session context from adr-system hook (`.adr-session.json`) 3. Ask the user which ADR to consult on

Do not guess which ADR to consult on because an incorrect guess wastes a full consultation cycle. Reject absolute, traversing, or prose-derived paths. Register the exact repository-relative path through `adr-query.py`, compute its hash, then require the shared resolver/containment/registration check to pass:

python3 scripts/adr-query.py register --adr 'adr/{adr-name}.md'
python3 scripts/adr-query.py hash --adr 'adr/{adr-name}.md'
python3 scripts/adr-query.py validate-registration \
  --repo-root . \
  --adr 'adr/{adr-name}.md' \
  --hash 'sha256:{digest}'

Keep that exact path and hash as consultation provenance. Stop if the resolver rejects the path, the content hash changes, or `.adr-session.json` names a different registration.

Even if this ADR was discussed informally, run the formal consultation because undocumented discussion produces no persistent artifacts and cannot be referenced by future sessions.

**Step 2: Check for prior consultation**

Before dispatching, scan `adr/{adr-name}/` for existing agent files because silently overwriting prior consultation work destroys the audit trail. Reuse a prior synthesis only when its `ADR Path` and `ADR Hash` match the validated provenance; otherwise it is stale and cannot satisfy a feature gate.

ls adr/{adr-name}/ 2>/dev/null

If existing files are found, report them and their timestamps. Ask the user whether to overwrite (re-run consultation) or use existing results.

**Step 3: Read the ADR**

Read the full ADR content. Extract: the decision being made, key components/changes proposed, any stated risks or consequences, and the ADR name (filename without `.md`) for the consultation directory.

**Step 4: Create consultation directory**

mkdir -p adr/{adr-name}

**Gate**: ADR content has been read, canonical path/hash registration has been validated, the consultation directory has been created, and the ADR name has been confirmed. Dispatch agents only after this gate passes.

---

Phase 2: DISPATCH

**Goal**: Launch all consultation agents in a single message for true parallel execution.

All three Task calls MUST appear in ONE response because sequential dispatch triples wall-clock time with no cross-perspective benefit. The value of this skill is simultaneous independent judgment.

Dispatch all 3 agents even if the ADR "seems simple" because partial consultation gives false confidence. Let agents report "no concerns" if genuinely clean.

Even when there is time pressure, do not skip consultation because blocking concerns discovered post-implementation cost dramatically more to fix.

**Standard mode (3 agents)**: Always dispatch all three. See `references/agent-prompts.md` for the full prompt template for each agent.

**Complex mode (5 agents)**: For Complex decisions (new subsystem, major API change), add `reviewer-system` and a second domain expert. Enable with "complex consultation" or "full consultation". See `references/agent-prompts.md` § Complex Mode.

Each agent receives: 1. The full ADR content as context 2. Its specific lens and analysis focus 3. Explicit output path: `adr/{adr-name}/{agent-name}.md` 4. The structured output format from `references/agent-prompts.md`

**Gate**: All Task calls dispatched in a single message. Proceed to Phase 3 only when all agents have returned and written their files to `adr/{adr-name}/`.

---

Phase 3: SYNTHESIZE

**Goal**: Read all agent responses from the consultation directory and produce a synthesis.

**Step 1: Read all agent responses from files**

Read the response files from disk, not from Task return context, because files persist across sessions while context does not -- synthesis from context is not reproducible.

cat adr/{adr-name}/reviewer-perspectives-contrarian.md
cat adr/{adr-name}/reviewer-perspectives-user-advocate.md
cat adr/{adr-name}/reviewer-perspectives-meta-process.md

**Step 2: Extract all concerns**

Track every concern raised by any agent in `adr/{adr-name}/concerns.md`. See `references/consultation-patterns.md` § Phase 3 Artifact Templates for the concerns.md format.