notque/vexjoy-agent / skills/analysis/assessment
assessment
VerifiedAssessment: read-only inspection, codebase overview, value analysis, health checks, ADR consultation, decision analysis, multi-perspective critique.
references/adr-consultation/consultation-preferred-patterns.md
View on GitHub# ADR Consultation Patterns Guide
> **Scope**: Correct patterns for ADR consultation orchestration and synthesis. Covers dispatch, artifact management, verdict aggregation, and gate enforcement. Does NOT cover ADR authoring style or implementation quality.
> **Version range**: Standard mode (3 agents), Complex mode (5 agents)
> **Generated**: 2026-04-15
---
## Overview
ADR consultation succeeds when agents are dispatched simultaneously, artifacts are file-based, blocking concerns halt progress, and all perspectives are represented. The patterns below define the correct approach for each phase, with detection commands to find violations.
---
## Pattern Catalog
### Dispatch All Agents Simultaneously
Send all three Task calls in a single response message. Every agent assesses independently — simultaneous dispatch preserves independence and runs in one-third the wall-clock time.
```markdown
[Single message with all three Task calls]:
- Contrarian reviewer → writes adr/{name}/reviewer-perspectives-contrarian.md
- User advocate → writes adr/{name}/reviewer-perspectives-user-advocate.md
- Meta-process reviewer → writes adr/{name}/reviewer-perspectives-meta-process.md
```
**Why this matters**: Sequential dispatch triples wall-clock time and risks context contamination. If agents 2 and 3 see agent 1's findings, they lose independence — the value is simultaneous independent judgment from different perspectives.
**Detection**:
```bash
# All three files should exist simultaneously after dispatch completes
ls adr/{name}/reviewer-perspectives-contrarian.md 2>/dev/null
ls adr/{name}/reviewer-perspectives-user-advocate.md 2>/dev/null
ls adr/{name}/reviewer-perspectives-meta-process.md 2>/dev/null
```
---
### Synthesize From Files, Not Context
After all agents complete, explicitly read each `adr/{name}/reviewer-perspectives-*.md` file before writing synthesis — even if Task return context is available. File-based synthesis is auditable, resumable, and survives session drops.
Healthy state: `synthesis.md` exists alongside 3 agent files. Unhealthy state: `synthesis.md` exists with 0 agent files — synthesis came from ephemeral context only.
**Why this matters**: Task return context disappears when context is cleared or a new session starts. Synthesis built from context cannot be re-read, audited, or resumed. If the session drops mid-consultation, the entire analysis is lost.
**Detection**:
```bash
# If synthesis.md exists but agent files don't, synthesis came from context only
ls adr/{name}/synthesis.md 2>/dev/null
ls adr/{name}/reviewer-perspectives-*.md 2>/dev/null | wc -l
# Healthy: synthesis.md + 3 agent files. Unhealthy: synthesis.md + 0 agent files.
```
---
### Enforce Blocking Concerns as Hard Gates
Any `severity: blocking` concern means the verdict is BLOCKED. To reach PROCEED, address the concern in the ADR itself and re-run consultation. Never argue around a blocking concern in synthesis.
```markdown
## Verdict: BLOCKED
The contrarian reviewer identified a blocking data migration risk.
Resolution required before proceeding: [specific action needed].
```
**Why this matters**: Post-implementation discovery of a blocking issue costs dramatically more than pre-implementation: the feature is already built, tests written, and the fix requires architectural surgery. The word "theoretical" applied to a blocking concern is a rationalization signal.
**Detection**:
```bash
# Find blocking concerns that were rationalized to PROCEED
for dir in adr/*/; do
name=$(basename "$dir")
if grep -q "Severity.*blocking" "$dir/concerns.md" 2>/dev/null; then
if grep -q "## Verdict: PROCEED" "$dir/synthesis.md" 2>/dev/null; then
echo "RATIONALIZATION DETECTED: $name"
fi
fi
done
```
---
### Dispatch All Required Reviewers
Always dispatch all three agents in standard mode (contrarian, user-advocate, meta-process). An agent that finds no concerns returns PROCEED in seconds — that fast, cheap confirmation is worth having. Never skip an agent because the ADR "seems simple."
**Why this matters**: Each agent covers a different perspective class. The contrarian catches problems the user advocate misses; the meta-process lens catches coupling issues both miss. Removing an agent removes an entire class of analysis. Partial consultation gives false confidence.
**Detection**:
```bash
# Standard mode: expect exactly 3 reviewer files
count=$(ls adr/{name}/reviewer-perspectives-*.md 2>/dev/null | wc -l)
if [ "$count" -lt 3 ]; then
echo "PARTIAL CONSULTATION: only $count/3 reviewers present"
fi
```
---
### Check for Existing Artifacts Before Dispatch
When `ls adr/{name}/` shows existing files, report them with timestamps and ask whether to overwrite (re-run) or use existing results. Never silently overwrite prior consultation.
**Why this matters**: Prior consultation may have reached a BLOCKED verdict that was intentionally deferred, or may contain concerns that were addressed in the ADR revision. Silently overwriting destroys the audit trail and forces re-covering the same ground without context.
**Detection**:
```bash
# Check for existing files before dispatch
ls -lt adr/{name}/ 2>/dev/null
# If files exist with recent timestamps, this is prior work — confirm before overwriting
```
---
### Validate Pre-Dispatch Gates Before Sending Agents
Before dispatching agents, confirm three prerequisites: (1) the ADR has been read, (2) the consultation directory exists (`mkdir -p adr/{name}`), and (3) the ADR name has been confirmed with the user.
**Why this matters**: Agents need a valid directory to write output files. An agent that cannot write to `adr/{name}/` because the directory does not exist will either fail silently or write to the wrong location. The synthesis then has no files to read.
**Detection**:
```bash
ls adr/{name}/ 2>/dev/null || echo "MISSING DIRECTORY"
cat .adr-session.json 2>/dev/null || echo "NO SESSION"
wc -l < adr/{name}.md 2>/dev/null || echo "ADR NOT READ"
```
---
### Treat NEEDS_CHANGES as Requiring Resolution
When multiple agents return NEEDS_CHANGES, extract all raised concerns, classify them, and either resolve them or explicitly accept them as known limitations. Multiple NEEDS_CHANGES is not a soft PROCEED — it means two independent reviewers identified specific things that must change.
```markdown
## Agent Verdicts
| Agent | Verdict |
|-------|---------|
| contrarian | NEEDS_CHANGES |
| user-advocate | NEEDS_CHANGES |
| meta-process | PROCEED |
## Verdict: PROCEED-with-conditions
All raised concerns listed below must be resolved or accepted:
1. [Concern from contrarian]: [resolution or acceptance rationale]
2. [Concern from user-advocate]: [resolution or acceptance rationale]
```
**Why this matters**: The synthesis verdict table is a concern aggregator, not a voting system. Aggregating two NEEDS_CHANGES to PROCEED discards both sets of concerns. Each NEEDS_CHANGES verdict represents specific, actionable feedback that was independently identified.
**Detection**:
```bash
# Count verdict types across all agent files in a consultation
grep -h "## Verdict:" adr/{name}/reviewer-perspectives-*.md 2>/dev/null | sort | uniq -c
```
---
## Error-Fix Mappings
| Symptom | Root Cause | Fix |
|---------|-----------|-----|
| Agent completes but no file in `adr/{name}/` | Path in agent prompt had typo or `adr/{name}/` not pre-created | Check prompt path; run `mkdir -p adr/{name}`; re-run failed agent |
| `synthesis.md` says PROCEED, `concerns.md` has `blocking` | Concerns read but not enforced | Override synthesis to BLOCKED; address concern in ADR; re-run |
| Only 1-2 agent files present after dispatch | Sequential dispatch or agent failure | Check whether dispatch was single-message; re-run missing agents |
| Consultation re-run silently overwrites prior results | Pre-dispatch check skipped | Always `ls adr/{name}/` before dispatching; report existing files |
| Synthesis references concerns not in concerns.md | Synthesizer added concerns during synthesis instead of extracting from agent files | Re-extract from agent files systematically; update concerns.md |
---
## Detection Commands Reference
```bash
# Check for sequential dispatch (files should appear simultaneously)
ls -lt adr/{name}/reviewer-perspectives-*.md 2>/dev/null
# Verify complete consultation (expect 3 files in standard mode)
ls adr/{name}/reviewer-perspectives-*.md 2>/dev/null | wc -l
# Detect rationalized blocking concerns
grep -l "Severity.*blocking" adr/*/concerns.md 2>/dev/null | while read f; do
dir=$(dirname "$f")
grep -l "Verdict: PROCEED" "$dir/synthesis.md" 2>/dev/null && echo "CHECK: $dir"
done
# Count verdict types across all agent files in a consultation
grep -h "## Verdict:" adr/{name}/reviewer-perspectives-*.md 2>/dev/null | sort | uniq -c
# Verify permanent artifacts after cleanup
ls adr/{name}/synthesis.md adr/{name}/concerns.md 2>/dev/null
```
---
## See Also
- `consultation-patterns.md` — Correct patterns for dispatch, synthesis, and verdict aggregation
- `skills/review/review/SKILL.md` (Parallel mode) — Fan-out/fan-in pattern this skill adapts
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |