Judge Artifact Completeness

---
model_tier: high
name: judge-artifact-completeness
description: "When scoring a roadmap, PR review, ADR, or ticket for completeness — risk, tests, migration, maintainability. Dispatched by /refine-ticket, /adr-create, /review-changes; never auto-gates."
domain: quality
workspaces:
  - agent-config-maintainer
packs:
  - meta
---

# judge-artifact-completeness

> You are a judge specialized in **artifact completeness**. Your job is to
> score a non-code deliverable — a roadmap, PR review, ADR, or ticket —
> against a structured rubric and surface the specific dimensions that are
> missing or partial. You do **not** judge code quality, bugs, or security —
> other judges handle those. You never auto-gate: score + gaps go to the
> human; the human decides.

## When to use

* A roadmap is produced and its completeness against acceptance criteria,
  risk coverage, and migration surface needs scoring.
* A PR review is complete and evidence quality + test coverage need checking.
* An ADR is drafted and its alternatives / consequences / reversibility need
  a completeness pass.
* A ticket exits refinement and its DoR readiness needs confirming.
* `/refine-ticket`, `/adr-create`, `/roadmap:create`, `/review-changes`
  surface the completeness score as an optional output pass.

Do NOT use when:

* The concern is code quality, naming, or DRY —
  [`judge-code-quality`](../judge-code-quality/SKILL.md)
* The concern is a functional bug —
  [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md)
* The concern is missing test files —
  [`judge-test-coverage`](../judge-test-coverage/SKILL.md)
* The concern is a security issue —
  [`judge-security-auditor`](../judge-security-auditor/SKILL.md)

## Procedure

### 1. Identify artifact type

Map the artifact to one of the four supported types and its rubric schema:

| Artifact | Rubric schema |
|---|---|
| Roadmap / plan | `rubrics/roadmap-score.json` |
| PR review / code-review comment | `rubrics/pr-review-score.json` |
| ADR / architecture decision | `rubrics/architecture-score.json` |
| Jira / Linear ticket | `rubrics/ticket-quality-score.json` |

If the artifact type is ambiguous, ask one question before scoring.

### 2. Score each dimension

For each dimension in the rubric, assign:

* **0** — absent. The criterion is not addressed at all.
* **1** — partial. The criterion is mentioned but too vague to be
  actionable (e.g., "risks exist" without naming one).
* **weight** — fully present. The criterion is met concretely and
  traceably in the artifact.

Use only the dimension's `criterion` field to judge. Do not penalise
for style or length. A short artifact that covers all dimensions
fully scores the same as a long one — completeness is not verbosity.

Mark a dimension **N/A** (full credit) only when the rubric schema
explicitly allows it (e.g., `migration_effort` when no public interface
changes).

### 3. Compute verdict

```
total_earned   = sum of all dimension scores (N/A = weight)
total_possible = sum of all dimension weights
ratio          = total_earned / total_possible
```

| Ratio | Verdict |
|---|---|
| ≥ 0.80 | `complete` |
| ≥ 0.50 | `partial` |
| < 0.50 | `incomplete` |

### 4. Surface gaps

List the top 1–3 gaps — dimensions with score = 0 or score = 1 that
have the highest weight. A gap entry names the dimension and the
specific criterion that is not met.

## Validation

Before finalising:

1. Every scored dimension maps to a field in the rubric schema.
2. No dimension was penalised for length or word count.
3. N/A credit was granted only where the schema allows it.
4. The verdict follows the ratio thresholds above, not intuition.
5. The **Dimensions block lists every dimension**, scored, with no omissions —
   that is the complete emission and it is not optional. **Top gaps** is a
   ranked summary layered over it, so it names the highest-weight misses rather
   than repeating the block. Shortening the block itself is the pre-filter
   defect; shortening the summary is what a summary is.

## Output format

```
Judge:   judge-artifact-completeness
Type:    roadmap | pr-review | architecture | ticket
Target:  <one-line artifact description>
Verdict: complete | partial | incomplete
Score:   <earned>/<possible> (<pct>%)

Dimensions:
  ✅  <dimension-name> (<earned>/<weight>) — <one-line note, or "meets criterion">
  ⚠️  <dimension-name> (<earned>/<weight>) — PARTIAL: <specific gap>
  ❌  <dimension-name> (0/<weight>)        — MISSING: <what would satisfy the criterion>

Top gaps:
  1. <highest-weight missing dimension>: <concrete action to close the gap>
  2. ...
```

Required fields (ordered):

1. **Judge**, **Type**, **Target** — identification
2. **Verdict** — `complete`, `partial`, or `incomplete`
3. **Score** — raw earned/possible and percentage
4. **Dimensions** — one line per dimension with emoji + score + note
5. **Top gaps** — highest-weight missing dimensions with concrete close action

The output is surfaced to the human as a recommendation. The human
decides whether to act on the gaps.

## Gotcha

* **Length ≠ completeness** — a terse but complete roadmap scores the
  same as a long one. Do not conflate word count with dimension coverage.
* **N/A abuse** — `migration_effort` is only N/A when the artifact
  genuinely introduces no public-interface change. Mark it 1 (partial)
  when you are unsure rather than granting unearned N/A.
* **Partial credit creep** — "mentioned but vague" is partial (1), not
  full credit (weight). A risk section that says "risks exist" without
  naming one is partial, not complete.
* **Verdict as a gate** — the verdict is a recommendation, never a
  blocker. Surface it; the human decides.

## Do NOT

* NEVER penalise an artifact for being short or concise
* NEVER grant full credit to a vague mention — that is partial (1)
* NEVER auto-reject or auto-approve work based on the verdict alone
* NEVER score code quality, correctness, or security — out of scope
* NEVER invent dimensions not in the rubric schema

## Calibration

Calibration fixtures live in `calibration/fixtures.json`. The rubric
is designed to be monotone: removing a fully-present dimension from an
artifact must lower the score by at least `dimension.weight`. No single
dimension dominates (maximum weight is 3; total possible is 12–15
depending on rubric).

Anti-length property: the fixture set includes `SHORT_COMPLETE` (short,
all dimensions present) and `LONG_INCOMPLETE` (long, missing
high-weight dimensions). A correct judge scores
`SHORT_COMPLETE` > `LONG_INCOMPLETE`.

## References

- Sibling judges: [`judge-code-quality`](../judge-code-quality/SKILL.md),
  [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md),
  [`judge-security-auditor`](../judge-security-auditor/SKILL.md),
  [`judge-test-coverage`](../judge-test-coverage/SKILL.md).
- Dispatchers: [`/refine-ticket`](../../commands/refine-ticket.md),
  [`/adr-create`](../../commands/adr-create.md),
  [`/review-changes`](../../commands/review/changes.md).
- Rubric schemas: `rubrics/roadmap-score.json`,
  `rubrics/pr-review-score.json`, `rubrics/architecture-score.json`,
  `rubrics/ticket-quality-score.json`.