ywc-spec-validate

name: ywc-spec-validate version: 1.0.0 description: (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 (use ywc-product-review), or when no specification document exists yet. category: spec phase: planning requires: [] advisor_budget: 2

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:

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

Arguments

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 "<precedentFn>\|<precedentMarker>" <src> (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
   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 <dir> 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/<id>) | 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/<id>) | 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. 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

Output Format

## 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:

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 <spec-path> --failure-context "<one-paragraph summary of the Critical findings>"

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. 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 Pattern B from advisor-pattern.md — parallel executors in Phase 1, frontier judgment applied only where it actually matters in Phase 2.

Budget: up to 2 Opus advisor calls per invocation by default. Unused budget is good. Spec review is smaller in scope than impl-review, so the cap is tighter.

Complexity-Aware Budget Defaults — right-size the advisor/council spend to the spec's scope before Phase 1 (an explicit --advisor-budget always overrides this default):

The Sonnet 4-dimension fan-out (Phase 1) always runs regardless of scope — it is cheap and catches omissions. Only the Opus Phase 2 / Council spend is right-sized here, so the "Right Job, Right Tool" saving never comes at the cost of missed findings.

--advisor-budget <n> override: when set, <n> is the hard ceiling on Phase 2 Opus calls for this invocation (default 2). The report header's Phase 2 advisor calls used: X of N line reflects the applied budget as N so an orchestrator can track cumulative spend across iterations. When --advisor-budget 0, Phase 2 escalation is disabled entirely: each finding that would have escalated is instead reported as a normal Suggestion carrying a one-line would have escalated but budget=0 rationale — it is never silently dropped. This lets a loop driver (e.g. ywc-spec-ready) run cheap deterministic passes and spend advisor budget only when it chooses to.

Escalation conditions — each must satisfy all three properties from advisor-pattern.md §5 (objective trigger, irreversibility, ambiguity):

1. Feasibility uncertainty — The spec appears feasible but hinges on an assumption about an undocumented library feature, version-specific behavior, or performance characteristic. A wrong assumption would make the spec unimplementable or force mid-implementation scope cuts.
2. Code Compatibility conflict with plausible-either-way resolution — The spec conflicts with existing code (schema, API contract, or type definition), and both "spec adapts to code" and "code refactors to spec" have plausible precedent in the project. The advisor picks which side moves.
3. Completeness borderline — The spec omits a feature that could be intentional (out of scope, deferred to another spec) or an oversight. The wrong verdict delays implementation (if flagged as gap when actually out of scope) or generates incorrect downstream tasks (if dismissed when actually a gap).
4. Cross-document consistency conflict — The spec conflicts with another spec or architecture document in the project, and resolving the conflict requires domain judgment about which document is the current source of truth.

Context payload rules (critical for cost discipline):

• Forward only the decision: the specific spec clause, the conflicting code or spec excerpt, and the constraint (≤100 lines total).
• Do NOT forward: the full spec, the full target code, or the CLAUDE.md contents.
• The advisor returns a short verdict (≤200 words) containing the recommended resolution and a one-line rationale.

Non-goals — do not escalate for these:

• Terminology nitpicks or formatting inconsistencies (these are Phase 1 Warnings, not advisor material).
• Generic "the spec could be clearer" observations without a specific failure mode.
• Stylistic preferences about how requirements are expressed.
• Missing sections that are clearly an author oversight (just report it as a Warning).

Report escalations in the output: mark Phase 2 findings with [P2] prefix and include the advisor's one-line rationale. This preserves auditability of which findings involved frontier judgment.

Council Escalation (High-Stakes Trade-offs)

When a finding involves a genuine architectural trade-off — where two reasonable positions exist and the wrong choice has significant implementation cost — the single Opus advisor may be replaced by a 4-voice Council review. Use council escalation when all three conditions hold:

1. The trade-off has long-term architectural consequences (e.g., sync vs. async boundary, data ownership model, API versioning strategy).
2. The single-advisor verdict would likely depend on unstated assumptions about team preferences or future requirements.
3. The finding is Critical or Warning severity — not a Suggestion.

Council voices (spawn one Opus subagent per voice, passing only the specific trade-off excerpt — not the full spec):

Anti-anchoring rule: Each voice receives only the trade-off description — not the other voices' verdicts. Collect all four independently before synthesizing.

Council output format (append to the relevant finding in the report):

[COUNCIL] {trade-off description}
- Architect: {verdict, ≤2 sentences}
- Skeptic: {verdict, ≤2 sentences}
- Pragmatist: {verdict, ≤2 sentences}
- Critic: {verdict, ≤2 sentences}
Consensus: {agreed recommendation, or "No consensus — strongest dissent: <voice>: <reason>"}

Profile Override (Focus-Specific Voices)

When --focus <area> is set on the invocation and Council Escalation triggers, replace the 4 generic voices above with 3–4 domain expert profiles from references/expert-profiles.md. The Anti-anchoring rule, output format, and budget rule all apply unchanged — only the voice labels and heuristics change.

Use generic Council (no --focus) when the trade-off spans two or more areas, or when the spec covers multiple domains and no single focus dominates. Mixing generic voices and focus profiles within a single Council session breaks anti-anchoring — pick one mode per session.

Council escalation consumes the full 2-advisor budget. Do not use council and single-advisor escalation in the same invocation.

Confidence Gate

This skill applies the Confidence Gate before declaring the spec ready for task-generator.

Required dimensions (must each score ≥ 70):

• Scope clarity — A spec with undefined scope cannot be decomposed into tasks. If scope is fuzzy, the gate forces STOP.
• Root cause identified — The user need behind the spec must be named. Surface-level requirements without a stated user need produce tasks that solve the wrong problem.

Band-to-status mapping for this skill (conforms to confidence-gate.md §5 — PROCEED splits on Critical findings so DONE_WITH_CONCERNS stays reachable):

The gate score must appear in the report header alongside the Critical/Warning/Suggestion finding counts. A required dimension scoring below 50 forces STOP regardless of aggregate.

Integration

• Primary upstream — ywc-spec-writer: validates docs/specification/ section files (01-overview.md … 07-glossary.md). All 4 review dimensions (completeness, consistency, feasibility, code compatibility) apply fully.
• Secondary upstream — ywc-plan: can validate feature plan documents in docs/ywc-plans/. Completeness and consistency dimensions apply; feasibility and code compatibility apply partially because plan documents are less implementation-specific.
• Cross-artifact (Analyze) — ywc-task-generator output (tasks/): once tasks exist, pass the directory via --tasks <dir> (alongside --spec) to run the Cross-Artifact Consistency pass (Step 4c) — confirms every spec requirement is covered by a task and no task is orphaned. Passing a task directory as --spec is still a misuse; --tasks is the correct channel.
• Downstream: ywc-task-generator — hand off only when completion status is DONE. DONE_WITH_CONCERNS requires spec revision first.

Programmatic Consumer Policy

When consumed by an orchestrator that cannot prompt for human input (e.g., ywc-agentic):

Looped consumer: the table's max 1 retry is the default for non-loop consumers (e.g. ywc-agentic Step 3 historically). When multi-iteration convergence is required, the dedicated ywc-spec-ready skill drives the DONE_WITH_CONCERNS → ywc-plan --update-spec → re-validate cycle repeatedly under its own --max-iterations cap and stall guards, and passes the remaining advisor budget via --advisor-budget. Use ywc-spec-ready instead of hand-rolling more than one retry.