consensus

Files (9)

• README.md
• SKILL.md
• evals.json · evals/
• archive.patch · evals/files/
• database-context.md · evals/files/
• migration-plan.md · evals/files/
• protocol.md · references/
• consensus.sh · scripts/
• test.sh · tests/

SKILL.md (first lines)

# Consensus

Use the bundled script to collect independent opening positions from Claude and
Codex, then let them discuss. It writes a compact decision and a temporary
deliberation record. Agreement is not evidence; the discussion should expose
different framings, test critical claims, and identify uncertainty.

## Prerequisites

Authenticated `claude` and `codex` CLIs, `jq`, and `mktemp`. The script checks
them before starting.

## Brief

Write a neutral Markdown brief with:

- the question;
- relevant material and prior decisions;
- constraints and known assumptions;
- options considered;
- success criteria and non-goals;
- evidence the participants can inspect.

For code review, name the branch, commit range, or diff instead of pasting it.
Do not favor an answer. The first two calls are independent: neither model sees
the other's framing until both positions exist.

## Evidence

A **critical claim or assumption** is one that could change the recommendation
if false. Classify each as:

- `verified`: supported by inspection, supplied material, authoritative
  documentation, data, calculation, or experiment;
- `assumption`: unverified but accepted for this decision;
- `unknown`: important and unresolved.

Name the source or method. Appropriate evidence depends on the domain and may
include code, research, financial data, user research, measurement, or formal
reasoning. Agreement between models is never evidence.

## Run

From the project root:

```sh
bash <skill-directory>/scripts/consensus.sh [options] brief.md
```

| Option | Default | Meaning |
|---|---|---|
| `--first claude\|codex` | `claude` | First independent opener and first rebuttal |
| `--max-turns N` | `10` | Total turns, including both openings; minimum 2 |
| `--out DIR` | Temporary directory | Parent output directory |
| `--name SLUG` | Brief filename | Run name |
| `--claude-model M` | CLI default | Claude model |
| `--codex-model M` | Codex config | Codex model |
| `--judge` | Off | Fresh Claude decides an unresolved run |
| `--judge-model M` | CLI default | Judge model |

Omit `--out` unless the user requests persistent output. Do not put logs in a
repository merely because it has a decisions directory. Leave model flags unset
unless requested.

## Result

Read `DECISION.md` first. It contains the decision, evidence status, blockers,
optional improvements, consequences, and one next action:

- `proceed`
- `targeted_revision`
- `reassess_approach`

Use `log.md`, `turns/`, and `cli-logs/` only to diagnose the run. Do not carry
the debate into later project context.

- Exit 0: report the compact decision and evidence status.
- Exit 2: report both final summaries and unresolved points; ask the user to
  decide unless `--judge` was enabled.
- Exit 3: inspect `cli-logs/` and report the protocol or CLI failure.

## Hindsight

If the accepted result uses `reassess_approach` or accepts that a critical
assumption failed, stop before local remediation. Invoke `hindsight` with the
original goal, current approach, new evidence, invalidated assumptions, and
compact decision. Exclude the deliberation log. A disputed invalidation remains
a blocker or impasse.

## Reruns

Do not rerun substantially the same question without material new evidence;
state what changed in the new brief. If another review falsifies the same class
of assumption, use hindsight instead of another remediation debate.

The script writes `DECISION.md`, `brief.md`, `log.md`, `protocol.md`, `turns/`,
`sessions.json`, and `cli-logs/` under a temporary numbered run directory.

From code-alexander/skills, MIT.

More from code-alexander/skills