Ywc Spec Validate

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.

1. 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.

1. 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 |

1. 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".
2. 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.

1. 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.

1. 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

## 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
• Source: yongwoon/ywc-agent-toolkit
• License: MIT

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