---
name: zoto-judge-spec
description: Independent assessment of a repository or Spec System engineering specs. Reviews quality, feasibility, completeness, risk, and structure. After producing a spec assessment, offers to apply recommended fixes directly to the spec files. Use to audit a codebase or to assess and improve a spec before running zoto-execute-spec.
---

# Spec System Judge Spec

Independent assessment workflow for the repository or individual engineering specs managed by the Spec System. Provides a structured review with scores, findings, and actionable recommendations. For spec assessments, offers to apply fixes directly to the spec files after producing the report. The judge should ideally run in a **fresh agent context** to avoid bias from prior sessions.

**Paths**: Resolve `{specsDir}` from `.zoto/spec-system/config.yml` in the repository root (default `specs`). All report paths below are relative to the repository root unless noted.

## When to Use

- **No target specified**: Assess the entire repository — write report to `{specsDir}/assessment-repo-[yyyymmdd].md`
- **Spec path specified**: Assess a specific spec — write report to that spec's directory as `assessment-[feature-name]-[yyyymmdd].md`

## Assessment Dimensions

The judge evaluates specs (or the repo as a whole) across six dimensions, each scored 1–5:

| Dimension | Weight | What It Measures |
|-----------|--------|------------------|
| **Completeness** | 25% | All requirements covered, no gaps in deliverables, definition of done is thorough |
| **Feasibility** | 20% | Subtasks are achievable, scope is realistic, no impossible demands |
| **Structure** | 20% | Dependencies are correct, phases are logical, no circular dependencies |
| **Specificity** | 15% | Subtasks have clear objectives; deliverables are concrete and verifiable |
| **Risk Awareness** | 10% | Edge cases considered, potential blockers identified, rollback possible |
| **Convention Compliance** | 10% | Aligns with **this repository's** established patterns (layout, tooling, naming, tests, docs) |

### Scoring

| Score | Label | Meaning |
|-------|-------|---------|
| 5 | Excellent | No issues found |
| 4 | Good | Minor improvements possible |
| 3 | Adequate | Some gaps but executable |
| 2 | Needs Work | Significant issues — revise before executing |
| 1 | Deficient | Major problems — spec should be reworked |

**Overall verdict** is the weighted average:

- **4.0+**: Approve — ready for execution (e.g. via the `zoto-execute-spec` skill)
- **3.0–3.9**: Conditional — address findings before executing
- **< 3.0**: Reject — spec needs rework via `/z-spec-create`

## Workflow: Repository Assessment (no target)

### Step 1: Explore Codebase

Spawn an `explore` subagent for a thorough survey:

- Directory structure (source, tests, scripts, configuration, documentation)
- Wiring and integration points (CI, hooks, editor/agent config if present)
- Test and quality tooling — which areas are covered and which are not
- Documentation state (README, contributing guides, architecture notes)

### Step 2: Perform Quality Checks (judge directly)

The assessing agent performs **read-only** checks suitable for the stack and repo — do **not** assume a dedicated audit subagent exists in the consuming project. Tailor checks to what the repository actually contains, for example:

- CI/CD workflow files: syntax, obvious misconfiguration, missing jobs for critical paths
- Test configuration and coverage gaps (by file area, not necessarily line percentages)
- Lint or formatter configuration presence and consistency with stated standards
- Dependency and security hygiene as visible from manifests (outdated pins, known risky patterns in config)
- Build or packaging scripts: error handling, idempotence where relevant
- Documentation drift (README vs actual commands, missing setup steps)

Document what was reviewed and any limitations (e.g. cannot run full CI locally).

### Step 3: Evaluate Dimensions (repo-adapted)

Apply the six dimensions to the repository as a whole:

- **Completeness**: Are components wired consistently? Orphaned configs or missing docs?
- **Feasibility**: Is the architecture sustainable for the stated goals?
- **Structure**: Are module boundaries and dependencies understandable?
- **Specificity**: Are responsibilities and interfaces clear where they matter?
- **Risk Awareness**: Untested paths, fragile integrations, operational gaps?
- **Convention Compliance**: Does the tree follow **this repo's** own conventions (not an external framework's unless the repo adopted it)?

### Step 4: Generate Report

Write `{specsDir}/assessment-repo-[yyyymmdd].md` with scores, findings, and recommendations.

---

## Workflow: Spec Assessment (with target)

### Step 1: Load Spec

1. Read the spec index file and all subtask files
2. Read any referenced design docs or specs (from the spec's overview or requirements)
3. Build a mental model of the full initiative

### Step 2: Explore Context

Spawn an `explore` subagent to verify:

- Referenced files and directories exist
- Existing patterns match what the spec assumes
- No obvious conflicts with current codebase state

### Step 3: Evaluate Each Dimension

For each dimension, produce:

- A score (1–5)
- Specific findings (what is strong, what is missing)
- Recommendations (actionable fixes if score < 5)

### Step 4: Validate Subtask Manifest

The Subtask Manifest in the index is the source of truth. For each row, verify:

- [ ] The listed file exists in the spec directory
- [ ] The subtask file's metadata (assigned subagent, dependencies) matches the manifest row
- [ ] The assigned subagent is appropriate for the work type (e.g. focused audit work vs. broad implementation)
- [ ] No subtask depends on a higher-numbered subtask ID
- [ ] Phase assignments are consistent with dependencies (a subtask's phase must be greater than all its dependencies' phases)

### Step 5: Check Subtask Quality

For each subtask file, verify:

- [ ] Clear, single-responsibility objective
- [ ] Deliverables checklist is concrete (not vague)
- [ ] Assigned subagent matches the work type
- [ ] Dependencies are correct (no missing or circular dependencies)
- [ ] Implementation notes give enough guidance for the executing agent
- [ ] Testing strategy is defined where applicable
- [ ] No subtask is doing too much (consider decomposition if there are many unrelated deliverables)

### Step 6: Dependency Graph Audit

- Verify the mermaid graph matches the Subtask Manifest (same edges and nodes)
- Check for missing edges (subtask B uses output of subtask A but does not declare a dependency)
- Check for unnecessary sequential constraints (work that could run in parallel but is over-serialized)
- Verify phase assignments align with dependency ordering
- Confirm subtask IDs respect dependency order (lower IDs do not depend on higher IDs)

### Step 7: Risk Analysis

Identify:

- **Blocking risks**: Single points of failure, hard external dependencies
- **Scope risks**: Subtasks that are too large or vaguely defined
- **Integration risks**: Phases where many subtasks merge and could conflict
- **Convention risks**: Deviations from **this repository's** established patterns

### Step 8: Generate Report

Write `assessment-[feature-name]-[yyyymmdd].md` into the spec's directory (under `{specsDir}/`).

### Step 9: Offer to Apply Fixes

After generating the assessment report, present a summary of the verdict and actionable findings to the user, then **offer to apply the recommended fixes** directly to the spec files.

#### What to present

```
## Assessment Complete

**Verdict**: [Approve | Conditional | Reject] ([X.X/5])

### Actionable Findings ([N] issues)

| # | Severity | Subtask | Fix |
|---|----------|---------|-----|
| 1 | HIGH | 03 | Add missing dependency on subtask 01 |
| 2 | MEDIUM | 05 | Replace vague deliverable with specific test files |
| 3 | LOW | — | Add rollback plan to spec index |

```

Then use **`askQuestion`** (if running as a command/executor) or return **`needs_user_input`** (if running as a subagent) to get structured approval:

```json
{
  "title": "Spec Assessment — Apply Fixes?",
  "questions": [{
    "id": "apply_fixes",
    "prompt": "Apply [N] recommended fixes to the spec files?",
    "options": [
      { "id": "yes", "label": "Yes — apply all fixes" },
      { "id": "no", "label": "No — keep spec as-is" }
    ]
  }]
}
```

#### If user accepts — apply fixes

Work through each actionable finding and modify the spec files directly:

1. **Dependency fixes**: Update the Subtask Manifest table in the spec index (add/remove dependency columns), update the corresponding subtask file's Metadata dependencies, update the Mermaid dependency graph, and recompute phase assignments if dependencies changed
2. **Deliverable fixes**: Update vague deliverable items in subtask files with the specific, concrete versions from the recommendation
3. **Missing content**: Add missing sections (rollback plans, testing strategies, implementation notes) to the appropriate files
4. **Subtask scope fixes**: If a subtask is flagged as too large, split it into multiple subtask files — create new files, update the manifest, and adjust the dependency graph
5. **Manifest/metadata consistency**: Fix any mismatches between the spec index manifest and subtask file metadata
6. **Graph corrections**: Fix the Mermaid dependency graph to match the corrected manifest

After applying all fixes:

1. Update the assessment report to note which fixes were applied
2. Report a summary of changes to the user:
   ```
   Applied [N] fixes:
   - [spec-index.md]: Added dependency 01→03, updated phase assignments
   - [subtask-05.md]: Replaced vague deliverable with specific test file list
   - [spec-index.md]: Added rollback plan section

   The spec is now ready for /z-spec-execute.
   ```

#### If user declines

No changes are made. The assessment report stands as-is for the user to address manually.

#### Scope of fixes

The judge may modify **spec files only** (index, subtask files, dependency graph) — never application source code, configuration, or test files. Fixes are limited to what the assessment identified; the judge does not add new requirements or expand scope.

## Report Format

### Report Location

| Mode | Output File |
|------|-------------|
| Repo assessment | `{specsDir}/assessment-repo-[yyyymmdd].md` |
| Spec assessment | `{specsDir}/[spec-directory]/assessment-[feature-name]-[yyyymmdd].md` |

### Template

```markdown
# [Repo Assessment | Spec Assessment: [Feature Name]]

**Target**: `[repository root | {specsDir}/[directory]/spec-[name]-[yyyymmdd].md]`
**Assessed**: [YYYY-MM-DD]
**Verdict**: Approve | Conditional | Reject

## Scores

| Dimension | Score | Notes |
|-----------|-------|-------|
| Completeness | X/5 | [brief note] |
| Feasibility | X/5 | [brief note] |
| Structure | X/5 | [brief note] |
| Specificity | X/5 | [brief note] |
| Risk Awareness | X/5 | [brief note] |
| Convention Compliance | X/5 | [brief note] |
| **Overall** | **X.X/5** | **[verdict]** |

## Findings

### Strengths
- [What the spec or repo does well]

### Issues
| # | Severity | Subtask | Finding | Recommendation |
|---|----------|---------|---------|----------------|
| 1 | HIGH | 03 | Missing dependency on subtask 01 | Add dependency |
| 2 | MEDIUM | 05 | Vague deliverable "update tests" | Specify which test files |
| 3 | LOW | — | No rollback plan | Add rollback notes to index |

### Dependency Graph
- [Any issues with the graph]
- [Suggestions for parallelism improvements]

### Risk Summary
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [risk] | Low/Med/High | Low/Med/High | [suggestion] |

## Recommendation

[1–3 sentences: overall assessment and what to do next]
```

## What NOT to Do

- Do not modify spec files **before** presenting the assessment — the assessment itself must be unbiased
- Do not apply fixes without explicit user approval
- Do not execute any subtasks — assessment and spec-level fixes only
- Do not modify application source code, configuration, or test files — only spec files (index, subtasks, dependency graph)
- Do not skip dimensions — score all six even if they appear fine
- Do not rubber-stamp — provide genuine critical analysis
- Do not expand scope when applying fixes — only address what the assessment identified