# Ywc Spec Validate

> (ywc) Use when a specification has been written and before task decomposition, and the user wants to validate spec completeness, consistency, feasibility, or readiness for implementation. Triggers: "사양 검토", "spec review", "사양 리뷰", "review specification", "스펙 점검", "check the spec", "is this spec complete", "仕様レビュー". Do not use for code-level review (use ywc-impl-review), product/business review (u…

- **Type:** Skill
- **Install:** `agentstack add skill-yongwoon-ywc-agent-toolkit-ywc-spec-validate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yongwoon](https://agentstack.voostack.com/s/yongwoon)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yongwoon](https://github.com/yongwoon)
- **Source:** https://github.com/yongwoon/ywc-agent-toolkit/tree/main/claude-code/skills/ywc-spec-validate

## Install

```sh
agentstack add skill-yongwoon-ywc-agent-toolkit-ywc-spec-validate
```

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

## About

# ywc-spec-validate

**Announce at start:** "I'm using the ywc-spec-validate skill to validate specification completeness, consistency, and feasibility."

Spec Reviewer Agent Skill for specification quality validation.

## Rationalization Defense

When tempted to skip a step, check this table first:

| Excuse | Reality |
|---|---|
| "Spec is mostly clear, no need to assess Feasibility" | Feasibility and Code Compatibility require project context. Always read CLAUDE.md, package.json, and existing code first. |
| "Spec gaps are obvious, just list them and finish" | Each gap must specify which dimension (completeness / consistency / feasibility / compatibility) and propose a concrete clarifying question. |
| "User wrote the spec, do not push back too hard" | Honest review prevents implementation rework. Soften tone, never soften findings. |
| "Spec uses internal jargon, infer the intent" | If a term is undefined, that is a completeness gap. Flag it. |
| "Architecture decision is implicit, do not flag it" | Implicit ≠ specified. Surface implicit assumptions for explicit confirmation. |
| "Spec follows best practices, so complexity is fine" | The 4 base dimensions catch what is *missing* or *conflicting*, never what is *excessive*. Abstraction, configurability, or generality the stated scope does not yet require is over-engineering — surface it as a Simplicity Warning. Would a senior engineer call this spec overbuilt? |
| "The spec contradicts CLAUDE.md, follow the spec" | Surface the conflict. Do not silently let the spec override project rules. |
| "4-dimension review is fast enough sequentially" | Phase 1 fan-out cuts latency on large specs; each Sonnet subagent handles one dimension, reducing per-call context and preventing cross-dimension finding contamination. |
| "Spec passed and tasks were generated from it, so they must agree" | task-generator can silently drop or reinterpret a requirement. When `--tasks` is set, build the Requirement Coverage table (Step 4c) — an UNCOVERED FR ships an incomplete feature while every spec-internal claim still validates cleanly. Drift between artifacts is invisible to spec-only review. |
| "Every spec deserves the full 2 advisor calls" | Right-size the *advisor/council* spend (not the cheap Sonnet fan-out): a single-section follow-up does not need the same Opus budget as a 15-AC multi-module spec. Spending advisor calls on a trivial spec wastes tokens; under-spending on a cross-cutting one misses real trade-offs. Apply the Complexity-Aware Budget Defaults before Phase 1. |
| "spec has no code yet, so concurrency is an implementation-phase problem" | Missing concurrency/transaction/idempotency requirements for a duplicate-sensitive write are a Completeness Critical — caught at the spec stage. |

**Violating the letter of these rules is violating the spirit.** A spec review that finds nothing is not a review.

## Arguments

| Parameter | Format | Example | Description |
|-----------|--------|---------|-------------|
| `--spec` | `--spec ` | `--spec docs/outline/02-api.md` | Specification file path (required) |
| `--mode` | `--mode standard\|socratic` | `--mode socratic` | Output style. `standard` (default) returns the finding report and gate verdict; `socratic` returns learning questions instead. See [references/socratic-mode.md](references/socratic-mode.md). |
| `--focus` | `--focus ` | `--focus architecture` | Optional focus hint. When Council Escalation triggers, the generic 4 voices are replaced with domain expert profiles for the chosen area. Valid: `requirements`, `architecture`, `testing`, `compliance`. See [references/expert-profiles.md](references/expert-profiles.md). |
| `--format` | `--format markdown\|html` | `--format html` | Output format. Default `markdown`. With `html`, writes a self-contained HTML report to `claudedocs/`. See [html-output.md](../references/html-output.md). Orthogonal to `--mode` |
| `--advisor-budget` | `--advisor-budget ` | `--advisor-budget 0` | Opus advisor escalation budget for this invocation. Default: current behavior (≤2). `0` disables Phase 2 escalation entirely — ambiguous advisor candidates are reported as normal Suggestions (with a "would have escalated but budget=0" note) instead of being escalated. Used by orchestrators (e.g. `ywc-spec-ready`) to cap cumulative advisor cost across iterations. |
| `--tasks` | `--tasks ` | `--tasks tasks/` | Optional. When set, runs the **Cross-Artifact Consistency (Analyze)** pass (Step 4c) after Phase 1: verifies the spec and the generated task directory have not drifted apart — every requirement covered by a task, no orphan task, dependency order respects spec phases. Omit for the default pre-decomposition review (tasks do not exist yet). |

## Execution Steps

1. **Collect Project Context** — Read the following before touching the spec file. The Feasibility and Code Compatibility dimensions cannot be assessed without this context:
   - `CLAUDE.md` (or the nearest parent `CLAUDE.md`) — language/framework constraints, commit conventions, any explicit out-of-scope rules
   - `package.json` / `pyproject.toml` / `go.mod` — runtime, major dependencies, and their versions
   - Top-level directory structure — identify where DB schemas, API routes, and type definitions live (e.g., `src/`, `app/`, `prisma/`, `migrations/`)
   - `docs/ubiquitous-language.md` (if it exists) — canonical domain terms and their "Synonyms to Avoid"; any spec term matching a Synonyms entry is a Consistency finding
   - Extract and keep: runtime, primary framework, DB type, ORM, existing API pattern (REST / GraphQL / RPC)

   If CLAUDE.md is absent and package.json is absent, note "project context unavailable" and flag all Feasibility findings as lower-confidence.

2. **Read Specification File** — Confirm the `--spec` path exists before reading. If the file does not exist, stop immediately with `BLOCKED` status and report the missing path.

3. **Check Code Compatibility** — Use Grep/Glob to search for related DB schemas, API routes, and type definitions to detect conflicts with the spec. Scope the search to the directories identified in Step 1.

3.5. **Precedent-Completeness Re-grounding (MANDATORY omission check — distinct from the conflict check in Step 3).** Step 3 / Code Compatibility detect where a spec *claim* conflicts with code. They structurally cannot detect an *omission*: an existing integration site the spec never names makes no claim, so nothing conflicts — yet a dropped integration site silently breaks the feature on the un-modeled runtime path while every written claim still validates cleanly. (This is the failure class that survives repeated spec-validation; re-reading spec text can never reveal a site the text never names.)

   For **every** existing pattern the spec mirrors / follows / 踏襲 / extends (a **named precedent X**), you MUST build a **Precedent Site Coverage table** before writing the report — do not reason about it in prose, build the table:

   1. Grep X's own identifier(s)/marker(s) across the actual code: `grep -rn "\|" ` (exclude test files). Integration patterns (snippet/script injection, hooks, interceptors, lifecycle handlers) routinely span a **generation** step, a **preview/transform** step, **and** a **publish/render-time** step — enumerate all of them; the publish/render-time site is the one a memory-driven spec most often drops.
   2. Emit one row **per site X integrates at**:

      | Precedent site (`file:line` + what runs there) | Spec coverage: Replicated / Deferred-with-reason / **OMITTED** |

   3. Every grep hit MUST appear as a row. Decide each row's coverage by searching the spec for *that specific site* — never by trusting the spec's own prose summary that it "follows X".
   4. **Every row marked OMITTED is its own Completeness Critical.** Do not fold multiple omitted sites into one finding, and **do not let a louder conflict elsewhere (e.g. a stale-anchor or deprecated-path finding) substitute for explicitly naming the omitted site** — an omission and a conflict are different defects and both must be reported. Each OMITTED Critical names the omitted site's `file:line` and the runtime path on which the feature fails.

   Include the coverage table in the report, and feed each OMITTED row into the Completeness dimension of Phase 1 as a separate Critical.

4. **Phase 1 — Parallel Dimension Review** — Use the Task tool to spawn 4 Sonnet subagents in parallel, one per review dimension. Pass each subagent the project context from Step 1 and the spec text from Step 2:

   | Subagent | Model | Dimension | Focus |
   |---|---|---|---|
   | Completeness | sonnet | Completeness | Missing required items, edge cases, pagination. For a **duplicate-sensitive write flow** (stock/balance/order/payment/provisioning/quota) also check whether the spec specifies: (a) concurrent-request behavior, (b) the transaction/consistency boundary spanning multiple DB writes, (c) handling of duplicate client retry / double-click, (d) the failure response/status when stock/balance/quota is exhausted or a lock/version mismatch occurs. Missing any → a Completeness finding: **Critical** when the gap can cause double charge / oversell / lost ledger / duplicate provisioning, otherwise **Warning** |
   | Consistency | sonnet | Consistency | Terminology mismatches; Synonyms-to-Avoid violations |
   | Feasibility | sonnet | Feasibility + Simplicity | Implementable with current stack and dependencies; also flag over-engineering — abstraction, configurability, or generality the stated scope does not yet require (surface as Warning) |
   | Code Compatibility | sonnet | Code Compatibility | Conflicts with existing schema, API routes, type definitions |

   Each subagent returns:
   - **Confirmed findings** — dimension label, severity (Critical / Warning / Suggestion), file:line, description, improvement
   - **Advisor candidates** — findings where two reasonable interpretations exist (include the specific choice and its consequence, ≤100 lines per candidate)

   **Step 4b — Aggregate**: Combine and deduplicate findings by `{file}:{line}`. Cap advisor candidates at `advisor_budget` (default: 2), prioritizing Critical over Warning. Log any dropped candidates in the report.

   The 4-dimension analysis runs the same way regardless of `--mode`; the mode only changes how findings are presented in step 5.

4c. **Cross-Artifact Consistency (Analyze) — only when `--tasks ` is set.** Steps 1–4 validate the spec in isolation. When a task directory already exists (re-validation after `ywc-task-generator`, or inside a convergence loop), verify the spec and tasks have not drifted apart — a defect class that spec-internal review structurally cannot see (an uncovered requirement makes no claim, so nothing conflicts, yet the feature ships incomplete). Build two tables before writing the report:

   **Requirement Coverage** — one row per spec Functional Requirement / Acceptance Criterion. Grep the task directory for each FR/AC:

   | Spec FR/AC (`file:line`) | Covering task(s) (`tasks/`) | Replicated / Deferred-with-reason / **UNCOVERED** |

   Every **UNCOVERED** row is its own Completeness Critical (a requirement no task implements).

   **Task Provenance** — one row per task. Trace each task back to the spec:

   | Task (`tasks/`) | Spec basis (`file:line` FR/AC or named precedent) / **ORPHAN** |

   Every **ORPHAN** row (a task with no spec basis) is a Consistency Warning (unspecified scope). Then confirm the task dependency graph respects the spec's declared phase/sequence ordering — a task depending on a later-phase task is a Consistency finding.

   Feed UNCOVERED rows into the Completeness dimension and ORPHAN / dependency-order rows into the Consistency dimension as separate findings (do not fold multiple into one). Include both tables in the report.

5. **Output Report — Branch on `--mode`**
   - `standard` (default): emit the severity-classified finding report in the format below.
   - `socratic`: emit a learning-question list per [references/socratic-mode.md](references/socratic-mode.md). Findings still drive question selection — they are just reshaped from "fix X" into "what would happen if X?". Completion Status is `SOCRATIC` and the gate score is informational only.

## Review Dimensions

| Dimension | Review Focus |
|-----------|-------------|
| Completeness | Missing required items (error handling, edge cases, pagination, etc.) |
| Consistency | Terminology, format, or data structure mismatches across documents; spec terms appearing in the "Synonyms to Avoid" column of `docs/ubiquitous-language.md` |
| Feasibility | Whether the spec can be implemented with the current stack |
| Code Compatibility | Conflicts with existing DB schema, API route patterns |
| Simplicity | Whether the spec specifies abstraction, configurability, or generality the stated scope does not yet require (over-engineering). Assessed within the Feasibility pass — surface speculative scope as a Warning, not a separate subagent. |

## Output Format

```text
## Spec Review Result: {filename}

### Summary
- Critical: N, Warning: M, Suggestion: K
- Phase 2 advisor calls used: X of N ({single-advisor|council|none})   (N = applied budget; default 2, or the `--advisor-budget` value)

### Precedent Site Coverage
| Precedent site (`file:line` + what runs there) | Spec coverage: Replicated / Deferred-with-reason / OMITTED |
|---|---|
| ... | ... |

### Critical Issues
1. [{file}:{line}] [P1|P2] Description — Suggested improvement
   (if P2) Advisor rationale: {one-line rationale}

### Warning Issues
1. [{file}:{line}] [P1|P2] Description — Suggested improvement

### Suggestions
1. [{file}:{line}] Description — Suggested improvement

### Completion Status
(One of: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT)
```

**Completion Status rules:**

| Status | When to use |
|--------|------------|
| `DONE` | Review complete, no Critical findings |
| `DONE_WITH_CONCERNS` | Review complete but Critical issues were found — the spec needs revision before task decomposition |
| `BLOCKED` | Review cannot proceed — spec file missing, or a Phase 2 advisor returned an inconclusive verdict |
| `NEEDS_CONTEXT` | `--spec` argument is missing or the file is empty/unreadable |
| `SOCRATIC` | `--mode socratic` was used; output is a learning-question list, not a gate verdict. Downstream skills (especially `ywc-task-generator`) must not consume this status as a handoff signal. |

**Re-plan handoff on `DONE_WITH_CONCERNS`** — after printing the report body, append the following one-liner so the user (or an interactive orchestrator) can resolve findings via `ywc-plan` Re-plan Mode instead of rewriting the spec from scratch:

```
To address the Critical findings above without losing validated sections, run:
/ywc-plan --update-spec  --failure-context ""
```

This routes findings into the `## Iteration N Amendments` append flow described in `ywc-plan` Step 4c, preserving validated portions of the spec. Print this line only on `DONE_WITH_CONCERNS` — `DONE`, `BLOCKED`, `NEEDS_CONTEXT`, and `SOCRATIC` do not benefit from Re-plan Mode. For programmatic consumers (e.g., `ywc-agentic`), the Programmatic Consumer Policy below already invokes the equivalent flow; this surface is for interactive users who would otherwise re-write from scratch.

> **HTML mode (`--format html`)** — emits the same findings as a self-contained HTML report: severity color coding, tab navigation, and a `Copy as Markdown` button. Structure and conventions follow [html-output.md](../references/html-output.md). The Markdown surface is preserved inside the file, so downstream integration is unaffected.

## Advisor Escalation Policy

This skill runs Phase 1 as 4 parallel Sonnet subagents (one per dimension) and aggregates their findings. For a small number of **genuinely ambiguous** findings from Phase 1, the orchestrator escalates to an Opus advisor using the Task tool with `model: opus`. This follows **

…

## Source & license

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

- **Author:** [yongwoon](https://github.com/yongwoon)
- **Source:** [yongwoon/ywc-agent-toolkit](https://github.com/yongwoon/ywc-agent-toolkit)
- **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-yongwoon-ywc-agent-toolkit-ywc-spec-validate
- Seller: https://agentstack.voostack.com/s/yongwoon
- 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%.