Skip to content

notque/vexjoy-agent / skills/analysis/assessment

assessment

Verified

Assessment: read-only inspection, codebase overview, value analysis, health checks, ADR consultation, decision analysis, multi-perspective critique.

FileKindSize
SKILL.mdskill md14.5 KB
references/adr-consultation/agent-prompts.mdmarkdown4.4 KB
references/adr-consultation/consultation-patterns.mdmarkdown10.3 KB
references/adr-consultation/consultation-preferred-patterns.mdmarkdown8.9 KB
references/adr-consultation/error-handling.mdmarkdown9.0 KB
references/codebase-overview/examples-and-errors.mdmarkdown7.0 KB
references/codebase-overview/exploration-strategies.mdmarkdown5.5 KB
references/codebase-overview/report-template.mdmarkdown4.8 KB
references/codebase-overview/statistical-analysis-examples.mdmarkdown13.1 KB
references/codebase-overview/statistical-metrics-catalog.mdmarkdown7.8 KB
references/codebase-overview/statistical-phase-details.mdmarkdown6.0 KB
references/codebase-overview/statistical-three-lenses.mdmarkdown9.1 KB
references/decision-helper/decision-archetypes.mdmarkdown7.4 KB
references/decision-helper/decision-preferred-patterns.mdmarkdown8.0 KB
references/multi-persona-critique/examples-and-errors.mdmarkdown6.6 KB
references/multi-persona-critique/personas.mdmarkdown12.4 KB
references/multi-persona-critique/roast-report-template.mdmarkdown4.8 KB
references/multi-persona-critique/roast.mdmarkdown12.3 KB
references/multi-persona-critique/synthesis-template.mdmarkdown7.0 KB
references/repo-value-analysis/phase7-implement-template.mdmarkdown6.8 KB
references/service-health-check/auth-endpoint-patterns.mdmarkdown7.6 KB
references/service-health-check/cve-source-check.mdmarkdown5.8 KB
references/service-health-check/endpoint-config-preferred-patterns.mdmarkdown6.7 KB
references/service-health-check/endpoint-validator.mdmarkdown8.9 KB
references/service-health-check/examples/current-sources.example.txtmarkdown218 B
references/service-health-check/examples/inventory.example.jsonconfig368 B
references/service-health-check/security-headers.mdmarkdown6.2 KB
references/service-health-check/tech-source-registry.jsonconfig8.6 KB
scripts/cartographer.pyscript19.0 KB
scripts/cartographer_omni.pyscript103.7 KB
scripts/cartographer_ultimate.pyscript15.9 KB
scripts/check-cve-sources.pyexecutablescript13.4 KB
scripts/tests/test_check_cve_sources.pyscript1.8 KB

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
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall