gz adr evaluate¶
Evaluate ADR and OBPI quality using deterministic scoring across 8 ADR dimensions and 5 OBPI dimensions. Produces an EVALUATION_SCORECARD.md in the ADR directory with a GO / CONDITIONAL GO / NO GO verdict.
Usage¶
What It Evaluates¶
ADR Quality (8 weighted dimensions)¶
| # | Dimension | Weight |
|---|---|---|
| 1 | Problem Clarity | 15% |
| 2 | Decision Justification | 15% |
| 3 | Feature Checklist Completeness | 15% |
| 4 | OBPI Decomposition Quality | 15% |
| 5 | Lane Assignment Correctness | 10% |
| 6 | Scope Discipline | 10% |
| 7 | Evidence Requirements | 10% |
| 8 | Architectural Alignment | 10% |
OBPI Quality (5 dimensions per brief)¶
| Dimension | Question |
|---|---|
| Independence | Can this OBPI be completed without waiting for others? |
| Testability | Can completion be verified with commands? |
| Value | What concrete capability would be lost if removed? |
| Size | Is this a 1-3 day work unit? |
| Clarity | Could a different agent implement this without ambiguity? |
Scaffold Detection¶
Briefs containing template placeholders (src/module/, First constraint, etc.) are flagged and scored low on the value dimension. This catches auto-generated stubs that were never authored.
Verdict Thresholds¶
| ADR Weighted Total | Verdict |
|---|---|
| >= 3.0 | GO — Ready for proposal/defense review |
| 2.5 - 3.0 | CONDITIONAL GO — Address weaknesses, then re-evaluate |
| < 2.5 | NO GO — Structural revision required |
OBPI threshold: Average >= 3.0 per OBPI. Any dimension scoring 1 must be revised.
When to Use¶
- After drafting a new ADR and its OBPIs — quality gate before proposal
- Before moving a Draft ADR to Proposed / human defense review
- When benchmarking the quality of an existing ADR package
- After populating OBPI briefs — verify scaffold is cleared
Examples¶
# Evaluate a specific ADR
uv run gz adr evaluate ADR-0.3.0
# Machine-readable output
uv run gz adr evaluate ADR-0.3.0 --json
# Skip writing the scorecard file
uv run gz adr evaluate ADR-0.3.0 --no-scorecard
Options¶
| Option | Description |
|---|---|
adr_id |
ADR identifier (e.g., ADR-0.3.0) |
--json |
Emit machine-readable output |
--no-scorecard |
Skip writing EVALUATION_SCORECARD.md to the ADR directory |
Output¶
Writes EVALUATION_SCORECARD.md in the ADR package directory containing:
- All ADR dimension scores with weighted totals
- All OBPI dimension scores with averages
- Overall verdict (GO / CONDITIONAL GO / NO GO)
- Action items for any deficiencies
Pipeline Enforcement¶
When a scorecard exists with a NO GO verdict, gz obpi pipeline Stage 1 treats it as a blocker and aborts. This makes the evaluation a blocking gate for pipeline execution — run gz adr evaluate before starting OBPI work, and address NO GO action items before invoking the pipeline.
GO and CONDITIONAL GO verdicts do not block. Missing scorecards do not block (evaluation is optional until run).
Related Commands¶
| Command | Relationship |
|---|---|
gz adr audit-check |
Post-implementation evidence verification (downstream) |
gz obpi validate |
Single-brief or batch authored/completion readiness check |
gz obpi validate --adr |
Batch-validate all briefs under an ADR |
gz adr report |
Status view without scoring |