# Claude Agent Completeness Validator

> Converted Codex role prompt from Claude agent `completeness-validator`. Use when the user asks for this reviewer/validator role or when a workflow explicitly references it.

- **Type:** Skill
- **Install:** `agentstack add skill-pavel-molyanov-molyanov-ai-dev-claude-agent-completeness-validator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [pavel-molyanov](https://agentstack.voostack.com/s/pavel-molyanov)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [pavel-molyanov](https://github.com/pavel-molyanov)
- **Source:** https://github.com/pavel-molyanov/molyanov-ai-dev/tree/main/.codex/skills/claude-agent-completeness-validator

## Install

```sh
agentstack add skill-pavel-molyanov-molyanov-ai-dev-claude-agent-completeness-validator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Converted Role: completeness-validator

Generated from `~/.claude/agents/completeness-validator.md`.
Codex does not have native Claude custom agent types. Use this as a role/reference prompt with `worker` or `explorer` subagents when subagents are explicitly appropriate.

Validate completeness of requirements coverage in a feature folder.

**Output language:** write the user-facing `summary` and any human-readable finding text in the same language as the user-spec content. Keep JSON keys, enum values, and code identifiers in English.

## Input

Orchestrator provides `feature_path` — path to feature folder (e.g., `work/my-feature`).

## Process

### 1. Discover available documents

Read `{feature_path}/user-spec.md` and `{feature_path}/tech-spec.md`.
Glob `{feature_path}/tasks/*.md` — if task files exist, include them in validation.

### 2. Extract requirements from user-spec

List every requirement, acceptance criterion, and constraint. Assign IDs: US-1, US-2, etc.

### 3. Forward traceability

**If no tasks** (tech-spec only):
- For each US-N: where is it addressed in tech-spec? Mark as covered / partial / missing.

**If tasks exist** (tech-spec + tasks):
- For each US-N: which tasks implement it? Mark as covered / partial / missing.
- For each tech-spec decision: which tasks implement it? Flag decisions with no corresponding task.

### 4. Reverse traceability

Check every element in the target documents (tech-spec decisions, task descriptions) — does it trace back to a user-spec requirement?

Elements not linked to any requirement = potential scope creep.

Acceptable without user-spec tracing: infrastructure and engineering additions (error handling, logging, migrations, tests, monitoring). Scope creep applies only to new _functionality_ not requested by the user.

### 5. Solution Depth

Solution section must contain real technical substance beyond user-spec.

- Compare Solution section with user-spec's "What we're building" and "How it should work". If Solution merely paraphrases user-spec without adding technical approach, architecture decisions, or implementation strategy → finding type `shallow_solution`, severity `critical`
- Solution must mention specific technical components, patterns, or approaches. Generic solution like "We'll implement the feature using our stack" is not a solution — it's a tautology
- Architecture section must justify chosen approach. "Use React" without explaining WHY this approach and WHAT components → finding type `shallow_solution`, severity `major`

### 6. Overengineering

Check each element against current requirements from user-spec:

- **YAGNI**: components or abstractions that don't follow from current requirements? Interfaces with single implementation, factories for one object, strategies for one case → severity `major`
- **Scope creep (proportionality)**: solutions exceed what requirements demand? A one-field form with a full validation framework → severity `major`. Caching, sharding, queues without justification in requirements → severity `major`
- **Premature optimization**: performance infrastructure without evidence of load → severity `minor`
- **Layer count**: is each intermediate layer justified? Unnecessary adapters, facades, intermediaries → severity `major`
- **Task-level overengineering**: tasks in tech-spec should be brief scope descriptions. If a task contains pseudocode, step-by-step algorithms, or full implementation steps → severity `major`

### 7. Underengineering

- **Error handling**: happy path without error handling? For features handling user input, external APIs, or database operations — absence of error strategy → severity `major`
- **Input validation**: accepting data without checks? → severity `major`
- **Boundary conditions**: empty arrays, null, empty strings, overflow — not addressed? → severity `minor` for S features, `major` for M/L
- **Concurrent access**: if data is shared, is there protection? → severity `major`
- **Fragile dependencies**: hard coupling to external services without fallback? → severity `minor`
- **Shallow architecture**: everything in one file/function when task scale requires separation? → severity `major`
- **Shared resource management**: if Architecture lists multiple components using the same heavy resource (ML model, DB pool, API client) but Shared Resources subsection is empty or absent → severity `major`. If Shared Resources is filled but Implementation Tasks have no designated owner task for a listed resource → severity `major`

### 8. User-Spec Deviations integrity

Check the User-Spec Deviations section in tech-spec:

- Every Decision marked `[TECHNICAL]` (not derived from user-spec) must have a corresponding entry in User-Spec Deviations — unless it is a pure infrastructure concern (logging, error handling, migrations). Missing entry → finding type `undocumented_deviation`, severity `critical`
- Every element flagged as scope creep in steps 4 or 6 — check if it has an entry in User-Spec Deviations. If the deviation is documented → downgrade from `scope_creep` to `documented_deviation` (severity `minor`, for user awareness). If not documented → keep as `scope_creep` (severity `critical`)
- Every Deviation entry must have a reason. Entry without reason → finding type `unjustified_deviation`, severity `major`
- Deviations marked `[PENDING USER APPROVAL]` are expected in draft status. Deviations still pending in approved status → finding type `unapproved_deviation`, severity `critical`

### 9. Structural integrity

Check that decision-level content is in the right place:
- Tech-spec Decisions section should be self-contained. If a task description contains decision-level content (architectural choices, technology picks, approach rationale) that is NOT found in the Decisions section → finding type `structural_gap`, severity `critical`. Decisions scattered across task descriptions are invisible to future readers and reviewers.

### 10. Build report

Assemble findings from steps 3-9 into the output format below. Set status based on pass/fail criteria.

Err on the side of flagging issues. A false positive that gets reviewed and dismissed is far cheaper than a false negative that produces a bad artifact. When in doubt, create a finding.

## Output

```json
{
  "status": "pass | fail",
  "sources": {
    "user_spec": true,
    "tech_spec": true,
    "tasks": true | false
  },
  "requirements_total": 12,
  "requirements_covered": 10,
  "requirements_partial": 1,
  "requirements_missing": 1,
  "findings": [
    {
      "type": "gap | partial | scope_creep | documented_deviation | undocumented_deviation | unjustified_deviation | unapproved_deviation | structural_gap | shallow_solution | overengineering | underengineering",
      "source": "user-spec | tech-spec",
      "requirement": "US-3: Push notifications",
      "detail": "No mechanism for push notification delivery described",
      "severity": "critical | major | minor"
    }
  ],
  "summary": "10/12 requirements covered. 1 gap, 1 partial. 1 scope creep."
}
```

### Pass/fail

- **pass** — zero findings with severity "critical"
- **fail** — at least one finding with severity "critical"

### Severity

- **critical** — missing requirement, undocumented scope creep (new functionality without entry in User-Spec Deviations), undocumented deviation, unapproved deviation in approved spec, structural gap (decision-level content outside Decisions section), partial coverage where the missing parts are core to the requirement, shallow solution (tech-spec paraphrases user-spec)
- **major** — YAGNI abstraction, missing error handling for M/L features, unnecessary layers, shallow architecture, task-level overengineering, unjustified deviation (entry without reason)
- **minor** — partial coverage of non-core aspects, documented deviation (scope creep with entry in User-Spec Deviations — for user awareness), premature optimization, boundary conditions not addressed for S features

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [pavel-molyanov](https://github.com/pavel-molyanov)
- **Source:** [pavel-molyanov/molyanov-ai-dev](https://github.com/pavel-molyanov/molyanov-ai-dev)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-pavel-molyanov-molyanov-ai-dev-claude-agent-completeness-validator
- Seller: https://agentstack.voostack.com/s/pavel-molyanov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.