# Specs Kit Spec Check > Resolves [NEEDS CLARIFICATION] markers generated during brainstorming, ingests open findings from an adversarial review, and performs a structured quality scan to identify underspecified areas. Integrates responses directly into the specification. Use after specs.brainstorm before specs.spec-to-tasks, and again to close the findings of an adversarial review. - Skill: `giuseppe-trisciuoglio/specs-kit-spec-check` (Agent Skill) - Install (CLI): `npx skillmds@latest add giuseppe-trisciuoglio/specs-kit-spec-check` - Raw SKILL.md: https://api.skillmd.com/api/skills/giuseppe-trisciuoglio/specs-kit-spec-check/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: giuseppe-trisciuoglio (https://skillmd.com/u/giuseppe-trisciuoglio) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/giuseppe-trisciuoglio/specs-kit-spec-check --- # Spec Check — Clarification & Quality Assessment Resolves `[NEEDS CLARIFICATION]` markers from brainstorming and performs a structured ambiguity scan to harden the specification before task generation. ## Overview This command has two functions: | Function | When it runs | Description | |----------|-------------|-------------| | **Close review findings** | When an adversarial review report exists with open findings | Turn every open BLOCKER/MAJOR finding into a clarification question, then record its resolution back in the report | | **Resolve [NEEDS CLARIFICATION]** | Always, after review findings | Process markers generated by `specs.brainstorm` — up to 3 questions with priority | | **Structured Ambiguity Scan** | If space remains (max 5 questions total) | Scan the spec for underspecified areas using a taxonomy of categories | The three sources feed **one** queue and share the same cap of 5 questions. Review findings sit above markers because they are defects someone already substantiated, not suspicions. ### When [NEEDS CLARIFICATION] markers exist The markers are the **primary source** of clarification questions. Each marker becomes a pre-built question. The scan runs only if fewer than 5 questions are needed to resolve all markers. ### When no [NEEDS CLARIFICATION] markers exist The command falls back to a **full structured scan** across all quality categories, identical to the v3.0 behavior. ### Workflow Position ``` brainstorm → spec-check (this) → technical-plan → spec-to-tasks → adversarial-review → task-implementation → task-review → sync ↑ │ Resolve [NEEDS CLARIFICATION] │ BLOCKED / findings on the spec generated by brainstorm │ └──────────────────────────────────────────────────────────┘ second pass: close the review findings ``` The skill runs at two different moments and behaves the same way in both: on the first pass the queue is fed by brainstorming markers, on the second by the findings the panel raised. Nothing about the invocation changes — the presence of an adversarial review report with open findings is what makes the second pass a second pass. ### Dimensions of Quality The command evaluates four main dimensions: 1. **Completeness and Clarity** - Vague expressions ("robust", "intuitive", "fast") - Terms not defined in glossary - Internal contradictions - Missing or incomplete sections 2. **Requirements Traceability** - User request → specification alignment - Requirements → tasks coverage (if tasks exist) - Clear origin for each requirement 3. **Acceptance Criteria** - Presence of testable criteria - Measurability of criteria - Coverage of key functionalities - **Agent-executability**: every criterion is satisfiable by an agent working in the repository (writing a file, running a command, asserting a test). A criterion that needs an account, a credential, a signature, a purchase, physical access or a human decision cannot be closed by the loop: it belongs to the operator preconditions of the tasks document, and the same rule applies to any generated task that carries it 4. **Edge Cases Coverage** - Edge cases identified - Error handling documented - Explicit constraints and limitations 5. **Architecture Alignment** (if `docs/specs/architecture.md` exists) - Specification requirements consistent with defined technology stack - No implicit technical assumptions that contradict the architecture - Integration points compatible with infrastructure choices - Data requirements aligned with data architecture 6. **Ontology Consistency** (if `docs/specs/ontology.md` exists) - Domain terms in the specification match ontology definitions - No ambiguous synonyms (terms used interchangeably without definition) - Bounded contexts are respected (same term not used with different meanings) - New domain concepts flagged for ontology addition ## Usage ```bash # Basic usage - review a spec folder /skill:specs-kit-spec-check docs/specs/001-hotel-search-aggregation/ # Review a specific spec file /skill:specs-kit-spec-check docs/specs/001-hotel-search-aggregation/2026-03-07--hotel-search.md # Review from current directory (auto-detect) /skill:specs-kit-spec-check ``` ## Arguments | Argument | Required | Description | |----------|----------|-------------| | `spec-path` | No | Path to spec folder or file (default: auto-detect from CWD) | ## Current Context If `--spec` is omitted, infer the spec folder from the current working directory (the nearest folder containing spec-like markdown files). If no spec folder can be determined, stop and inform the user. ## Core Principles - **Review findings come first**: an open BLOCKER or MAJOR outranks every marker and every scan question. A defect a reviewer substantiated is not competing with a suspicion - **A closed finding is written down as closed**: the review report is the record of what the panel said *and* of what was done about it. Never resolve a finding silently - **Maximum 3 markers to resolve**: Focus on the most impactful clarifications first - **Maximum 5 questions total**: Focus on the most impactful ambiguities (markers + scan combined) - **One question at a time**: Interactive presentation with recommendation - **Immediate integration**: Responses are integrated into the specification progressively - **Recommendation based on best practices**: For each question, suggests the best option - **Non-destructive**: Preserves existing content, only adds clarifications - **Final report**: Summary of resolved, deferred, and outstanding areas - **Deferred markers handling**: Markers exceeding limit are queued for next session --- ## Integration with specs.brainstorm ### Marker Generation (in specs.brainstorm) During brainstorming, the agent marks unclear aspects with: ```markdown [NEEDS CLARIFICATION: specific question text] ``` Rules for marker generation (max 3 total): - Used only when: scope impact, multiple interpretations, no reasonable default - Prioritized by: scope > security/privacy > user experience > technical details - Not used for: reasonable defaults (data retention, auth method, error handling patterns) ### Marker Resolution (in this command) This command: 1. Extracts ALL `[NEEDS CLARIFICATION: ...]` markers from the spec 2. Converts each marker into a structured question (multi-choice or short-answer) 3. Presents them as the FIRST questions (before scan-generated questions) 4. Removes the marker from the spec after resolution 5. Integrates the answer into the appropriate section --- ## Phase 1: Discovery **Goal**: Identify the specification to review and gather context **Actions**: 1. Create todo list with all phases 2. Parse the skill arguments to extract the specification path 3. Determine the specification folder: - If a file is provided: use the parent directory - If a folder is provided: use it directly - If no argument: auto-detect from current working directory 4. Verify the folder exists 5. Identify relevant files: - `YYYY-MM-DD--feature-name.md` - Functional specification - `user-request.md` - Original user request (for traceability) - `brainstorming-notes.md` - Brainstorming notes (secondary) - `tasks/` - Existing tasks (for coverage verification) - `adversarial-review/` - Reports left by a review panel (optional). Take the **most recent** `YYYY-MM-DD--adversarial-review.md` by date in the filename: earlier reports are history, they are never re-opened - `graphify-out/graph.json` - Codebase graph (optional, project-level) 6. **Load project-level architecture and ontology documents** (if they exist): - Check for `docs/specs/architecture.md` — if found, load for architecture alignment checks - Check for `docs/specs/ontology.md` — if found, load for terminology consistency checks - These are project-level shared documents, NOT per-spec files --- ## Phase 2: Spec Loading & Marker Extraction **Goal**: Load the spec, extract [NEEDS CLARIFICATION] markers, perform structured scan **Actions**: ### 2a. Spec Loading (identica a prima) 1. Resolve and read the specification file: - `YYYY-MM-DD--feature-name.md` - Fallback: only dated spec-like markdown in folder 2. If present, also read: - `user-request.md` for traceability - Existing tasks for coverage verification - `docs/specs/architecture.md` for architecture alignment - `docs/specs/ontology.md` for terminology consistency ### 2b-bis. Adversarial Review Findings Extraction Runs **before** marker extraction, and only when Phase 1 found a report. 1. Read the most recent `adversarial-review/YYYY-MM-DD--adversarial-review.md` and collect every finding under **Convergent findings**, **Singleton findings** and **Contested areas**, keeping for each: id (`F1`, `C1`), severity, target, claim, scenario, suggested fix, and the class it was filed under. 2. **Skip findings already closed**: a finding carrying a `Status:` line other than `OPEN` was handled in an earlier session and is not asked again. 3. **Keep only what this skill can fix.** spec-check edits the specification; it does not write tasks, plans or code. Route by target: | Finding target | Handled here | Otherwise | |----------------|--------------|-----------| | The specification (requirements, AC, edge cases, terminology, data model in the spec) | yes | — | | `technical-plan.md` | no | report it as out of scope, point at `/skill:specs-kit-technical-plan` | | `tasks/TASK-*.md`, task ordering, DoD | no | report it, point at `/skill:specs-kit-spec-to-tasks` | | Contradicts a requirement the feature should not have at all | no | point at `/skill:specs-kit-brainstorm` | Findings routed elsewhere are listed in the final report as **not addressed here**, with the skill that owns them. They keep `Status: OPEN` in the review report — this skill did not close them and must not claim to. 4. **Severity filter**: BLOCKER and MAJOR always enter the queue. MINOR enters only if the quota is not already spent by higher-priority items. 5. **Contested areas** enter as questions too, phrased as the open decision rather than as a defect: the panel disagreed, so the user is the tie-breaker. 6. **Deduplicate against the markers**: a finding that restates an unresolved `[NEEDS CLARIFICATION]` marker is merged with it — one question, both sources recorded. ### 2b. [NEEDS CLARIFICATION] Extraction 1. Scan the ENTIRE spec text for the pattern: ```regex \[NEEDS CLARIFICATION:([^\]]+)\] ``` 2. For each match: - Extract the question text (captured group) - Record the context (surrounding paragraph/section) - Build a queue of clarification items: ``` [ { "source": "marker", "question": "What payment providers should be supported?", "context": "Section: Functional Requirements — Payment Processing", "suggested_answer": null # filled in Phase 3 } ] ``` 3. **DEDUPLICATION**: If multiple markers ask semantically equivalent questions, keep the most specific and merge context 4. **LIMIT**: If > 3 markers found, keep only the 3 most critical (scope > security > UX > technical) 5. **Marker Priority Scoring**: Assign priority score to each marker: - **P1 (Critical)**: Impacts feature scope or fundamental design decisions - **P2 (High)**: Affects security, privacy, or user data handling - **P3 (Medium)**: Influences user experience or workflow - **P4 (Low)**: Technical implementation details - Sort markers by priority, keep highest scoring when limiting 6. **Deferred Markers Handling**: - Markers exceeding the 3-marker limit are marked as "deferred" - They remain in the spec with `[DEFERRED: will be addressed in next spec-check session]` - Deferred markers do NOT count toward the 3-marker limit (they are effectively queued) - After user resolves 3 markers, the next spec-check session handles deferred ones ### 2c. Structured Quality Scan Perform the existing quality scan taxonomy, BUT with a constraint. Let `taken` be the number of questions already claimed by review findings (2b-bis) plus markers (2b): - `taken >= 5`: skip the scan entirely, the quota is exhausted - otherwise: the scan produces at most `5 - taken` additional questions With no findings and no markers this is the familiar full fallback of 5 scan questions. The scan taxonomy is identical to v3.0: - Completeness and Clarity - Domain and Data Model - Interaction and UX Flow - Non-Functional Quality Attributes - Integrations and Dependencies - Edge Cases and Error Handling - Constraints and Trade-offs - Terminology and Consistency - Completion Criteria (AC taxonomy, Bounded Context, agent-executability) - Architecture Alignment (if architecture.md exists) - Ontology Consistency (if ontology.md exists) For each category with Partial/Missing status, generate a candidate question IF quota allows. --- ## Phase 3: Question Prioritization **Goal**: Build the final question queue **Actions**: 1. **Initialize queue** with review-derived questions (from 2b-bis), ordered convergent BLOCKER → singleton BLOCKER → convergent MAJOR → singleton MAJOR → contested → MINOR. This is the ranking the review report already established; keep it 2. **Append marker-derived questions** (from 2b) 3. **Append scan-derived questions** (from 2c) — ordered by impact × uncertainty 4. **Apply final quota**: Cut queue to max 5 questions. Anything cut is **deferred**, not lost: a cut finding keeps `Status: OPEN` and is named in the final report, so the next session picks it up 5. **Question formatting**: - Each question must be answerable with: - Multi-choice (2-5 mutually exclusive options), OR - Short answer (max 5 words) - For **review-derived questions**: the claim is the problem statement, the scenario is the context, and the `suggested_fix` becomes the recommended option. Offer at least one alternative and always an option to reject the finding — a reviewer can be wrong, and the user is entitled to say so - For **marker-derived questions**: use the marker text as the question body - For **scan-derived questions**: formulate based on the taxonomy gap found **Output**: Ordered queue of max 5 questions, each with: - `source`: "review", "marker" or "scan" - `finding_id`: the review finding id, when source is "review" - `question`: Text of the question - `context`: Where in the spec the ambiguity was found - `type`: "multi-choice" or "short-answer" - `options`: Array of option objects (for multi-choice) or suggested answer (for short-answer) --- ## Phase 4: Sequential Questioning Loop **Goal**: Present questions one at a time and integrate responses **Actions**: 1. **For each question in the queue** (max 5): a. **Display progress**: ``` [N/5] Question N of 5 (source: review | marker | scan) ``` If source is "marker", add note: `Resolving [NEEDS CLARIFICATION] from brainstorming` If source is "review", add note: `Closing () from the adversarial review` a-bis. **For review-derived questions**: - State the claim, then the scenario, then who raised it. The scenario is what makes the finding arguable — a question that hides it asks the user to trust the panel - Recommend the `suggested_fix`, unless it contradicts something already decided in the spec, in which case say so and recommend the alternative - Always include an option along the lines of *"the finding does not hold: "*. Choosing it closes the finding as `REJECTED`, with the user's reason recorded b. **For marker-derived questions**: - Use the original marker text as the question body - The context from the marker (surrounding section) informs the recommendation - Options should reflect the most reasonable interpretations given the context c. **For scan-derived questions**: (same as v3.0) - Analyze all options, determine recommendation - Present with ask_user_question tool d. **After user response**: - If "yes" / "recommended" / "suggested": use the recommendation - If custom: validate fits constraint (multi-choice option or <=5 words) - If ambiguous: disambiguate (same question, not a new one) - Record answer and advance e. **Immediate integration** (after each response): - Create `## Clarifications` section if missing (after overview) - Add `### Session YYYY-MM-DD` subsection - Append: `- Q: → A: `, prefixed with the finding id when the source is "review" (`- F1 (BLOCKER) Q: … → A: …`) - **If source is "marker"**: REMOVE the `[NEEDS CLARIFICATION: ...]` marker from the spec text - **If source is "review"**: update the finding's entry in the review report (Phase 5-bis) - Apply clarification to appropriate section (see Phase 6 mapping) - Save the file 2. **Stop conditions**: - All questions answered - User signals completion ("done", "proceed") - Reached 5 questions 3. **If user skips a marker question**: - Do NOT remove the marker from the spec - Note in the report: "NEEDS CLARIFICATION #N: skipped by user" - The marker remains for a future spec-check session 4. **If user skips a review question**: - Do NOT touch the specification - The finding keeps `Status: OPEN` in the review report, with a `Skipped: YYYY-MM-DD` note - A skipped BLOCKER means the review gate stays BLOCKED — say so at the end --- ## Phase 5: [NEEDS CLARIFICATION] Cleanup **Goal**: Ensure no orphaned markers remain in the specification **Actions**: 1. **Final scan** of the spec for any remaining `[NEEDS CLARIFICATION: ...]` markers 2. **For each remaining marker**: - If it was resolved during Phase 4 but the text wasn't fully removed: remove it now - If it was skipped by the user: LEAVE IT (with a note in the report) - If it was never presented (quota exceeded): LEAVE IT with flag "deferred to next session" 3. **Validation**: - No `[NEEDS CLARIFICATION` string should remain unless explicitly deferred - Clarifications section has one entry per resolved question 4. **Report**: - Resolved: N markers - Skipped: N markers (remain in spec for future resolution) - Deferred: N markers (quota exceeded) --- ## Phase 5-bis: Review Report Status Update **Goal**: Record in the review report what happened to each finding, so the report reads as the full story — what the panel said, and what was done about it. Skipped entirely when no adversarial review report was found. **Actions**: 1. Edit the report **in place**. The findings, their scenarios and the panel health table are evidence and are never rewritten: the only additions are a `Status:` line and, when resolved, a `Resolution:` line under each finding. ```markdown ### F1 — BLOCKER — spec §Functional Requirements Raised by: , **Claim**: ... **Scenario**: ... **Suggested fix**: ... Status: RESOLVED 2026-08-16 (spec-check) Resolution: added FR-7 and an [IMP] acceptance criterion covering the partial-write case ``` 2. **Status vocabulary** — one per finding, never more: | Status | Meaning | |--------|---------| | `RESOLVED (spec-check)` | the specification was changed; `Resolution:` says how | | `REJECTED (spec-check)` | the user judged the finding wrong; `Resolution:` carries their reason | | `OPEN` | untouched: skipped, cut by the quota, or owned by another skill | An `OPEN` finding owned by another skill gets an `Owner:` line naming that skill, so the next session does not queue it again as a spec question. 3. **Update the Verdict block** at the top of the report: recount the open findings by severity and append a line recording the pass, without erasing the original verdict. ```markdown ## Verdict **BLOCKED** — 2 blocker, 5 major, 3 minor Follow-up 2026-08-16 (spec-check): 2 blocker resolved, 3 major resolved, 1 major rejected, 1 major open (owned by spec-to-tasks), 3 minor open. ``` 4. Write atomically and verify the file after the write. If the report cannot be written, warn: the clarifications are already in the spec, but the finding tracking is lost and the next session will re-ask. --- ## Phase 6: Clarification Integration **Goal**: Integrate each clarification into the appropriate specification section **Mapping clarification → section**: | Ambiguity Type | Target Section | |----------------|----------------| | Functional ambiguity | Add/update Functional Requirements | | Role/actor distinction | Update User Stories or Actors | | Data entity form | Update Data Model | | Non-functional constraint | Add/modify Non-Functional Requirements | | Edge case/negative flow | Add to Edge Cases / Error Handling | | Inconsistent terminology | Normalize term, add "(formerly X)" | | Placeholder/TODO | Resolve or quantify | | Architecture misalignment | Flag for `docs/specs/architecture.md` update or ADR | | Undefined domain term | Add term to `docs/specs/ontology.md` glossary | | Missing AC taxonomy | Apply [IMP]/[SEF]/[EXT] tags to all acceptance criteria | | Missing Bounded Context Impact | Add Section 6: Bounded Context Impact Statement | | < 60% [IMP] criteria | Return to brainstorming for more prescriptive criteria | **Integration rules**: - Preserve existing formatting - Don't reorder unrelated sections - Maintain heading hierarchy - If clarification invalidates a previous statement: replace, don't duplicate - Keep each clarification minimal and testable - A review finding is closed only when the spec change makes its **scenario** impossible. Adding a sentence that mentions the topic is not a fix: re-read the scenario against the edited section and, if it still plays out, the finding is not resolved --- ## Phase 7: Validation **Goal**: Validate integration after each write **Checks**: - [ ] Clarifications session contains exactly one bullet per response - [ ] Total questions ≤ 5 - [ ] No vague placeholders remaining from responses - [ ] No remaining contradictions - [ ] Valid Markdown structure - [ ] Consistent terms across sections - [ ] Every review finding presented to the user carries a `Status:` line in the report - [ ] No finding is marked RESOLVED without a `Resolution:` line and a matching spec edit - [ ] The report's follow-up counts match the statuses actually written under the findings --- ## Phase 8: Report Generation **Goal**: Generate final completion report **Actions**: 1. Generate summary with: - Number of questions asked and answered - Path of updated specification - Sections touched - Coverage summary table 2. **Review Findings Summary** (only when a review report was found): | Finding | Severity | Status | Outcome | |---------|----------|--------|---------| | F1 | BLOCKER | Resolved | FR-7 added, partial-write case covered | | F3 | MAJOR | Rejected | user: the retry is handled upstream | | F5 | MAJOR | Open | owned by `/skill:specs-kit-spec-to-tasks` | | F8 | MINOR | Open | deferred, quota exceeded | 3. **Marker Resolution Summary**: | # | Original Marker | Status | Answer | |---|----------------|--------|--------| | 1 | "What payment providers?" | Resolved | Stripe + PayPal | | 2 | "Guest checkout allowed?" | Skipped | — (remains in spec) | | 3 | "Currency support?" | Deferred | — (quota exceeded) | 4. **Coverage summary table**: | Category | Status | Notes | |----------|--------|-------| | Adversarial review findings | Resolved/Partial/Outstanding/N/A | N resolved, N rejected, N open | | [NEEDS CLARIFICATION] Markers | Resolved/Partial/Outstanding | N resolved, N skipped, N deferred | | Completeness and Clarity | Resolved/Clear/Deferred/Outstanding | ... | | Requirements Traceability | Resolved/Clear/Deferred/Outstanding | ... | | Acceptance Criteria | Resolved/Clear/Deferred/Outstanding | ... | | Edge Cases Coverage | Resolved/Clear/Deferred/Outstanding | ... | | Architecture Alignment | Resolved/Clear/Deferred/Outstanding/N/A | ... | | Ontology Consistency | Resolved/Clear/Deferred/Outstanding/N/A | ... | | **AC Taxonomy ([IMP]/[SEF]/[EXT])** | Resolved/Clear/Deferred/Outstanding | ... | | **Bounded Context Impact** | Resolved/Clear/Deferred/Outstanding/N/A | ... | 5. **Status definitions**: - **Resolved**: Was Partial/Missing, has been addressed - **Clear**: Already sufficient at start - **Deferred**: Exceeded question quota or better for planning - **Outstanding**: Still Partial/Missing but low impact 6. Recommend next steps. **Recommend, never run**: re-running the panel spends metered models, and that is the operator's decision. - Review findings were closed → suggest re-running `/skill:specs-kit-adversarial-review` to confirm the blockers fell. The spec changed since the panel read it, so the previous verdict no longer describes it - Findings remain open and owned by another skill → name that skill, per finding - A BLOCKER was skipped or deferred → say plainly that the review gate is still BLOCKED and that implementation should not start - No review report, Outstanding/Deferred markers: consider running `/skill:specs-kit-spec-check` again after planning - No review report, all Clear: proceed to `/skill:specs-kit-spec-to-tasks` ``` [specs-kit] Spec updated: 2 blocker and 3 major findings closed, 1 major rejected. [specs-kit] 1 major still open, owned by /skill:specs-kit-spec-to-tasks (F5, task ordering). [specs-kit] The spec changed since the panel reviewed it — re-run /skill:specs-kit-adversarial-review --spec=docs/specs/003-checkout/ to confirm. ``` --- ## Error Handling ### Specification not found ``` Error: Specification not found at [path] Verify that the path contains a resolvable spec file (`YYYY-MM-DD--feature-name.md`) ``` ### No ambiguities detected ``` No critical ambiguities detected worth formal clarification. The specification is complete and clear. Proceed with: /skill:specs-kit-spec-to-tasks [spec-folder] ``` ### Review report present but every finding already closed ``` [specs-kit] The adversarial review report has no open findings: all N were closed on . Continuing with markers and the quality scan. ``` ### Review report unparseable ``` [specs-kit] Warning: adversarial-review/ does not follow the expected finding layout. No finding could be extracted; continuing with markers and the quality scan only. Fix the report or re-run /skill:specs-kit-adversarial-review. ``` ### Review report status could not be written ``` [specs-kit] Warning: unable to update : [error] The clarifications are in the specification, but the findings were not marked as closed. The next spec-check session will ask about them again. ``` ### File write failed ``` Warning: Unable to write to [file]: [error] The clarification has been recorded in memory but not persisted. ``` --- ## Examples ### Example 1: Spec with [NEEDS CLARIFICATION] markers ```bash /skill:specs-kit-spec-check docs/specs/003-checkout/ ``` **Interactive flow**: ``` Found 2 [NEEDS CLARIFICATION] markers: 1. "What payment providers should be supported at launch?" 2. "Should guest checkout be allowed?" [1/5] Resolving NEEDS CLARIFICATION #1 (source: marker) → User selects: "Stripe + PayPal" → Marker removed from spec → Integrated into Functional Requirements [2/5] Resolving NEEDS CLARIFICATION #2 (source: marker) → User selects: "Yes, with email capture" → Marker removed from spec → Integrated into User Stories [3/5] Scan: Edge Cases Coverage (source: scan) → "How should concurrent checkouts for the same inventory item be handled?" → ... All markers resolved. 1 scan question asked. Spec updated. Next: /skill:specs-kit-spec-to-tasks docs/specs/003-checkout/ ``` ### Example 2: Closing the findings of an adversarial review ```bash /skill:specs-kit-spec-check docs/specs/003-checkout/ ``` **Interactive flow**: ``` Found adversarial review 2026-08-15--adversarial-review.md — verdict BLOCKED, 2 blocker, 5 major, 3 minor. 7 findings target the specification, 3 target the task set. [1/5] Closing F1 (BLOCKER) from the adversarial review Claim: the spec never says what happens when the payment provider times out Scenario: provider does not answer within 30s → the order is left without a terminal state, and no requirement says which one it takes Raised by: , → User selects the suggested fix: "order goes to PAYMENT_PENDING, reconciled by job" → Integrated into Functional Requirements + Edge Cases → Report: F1 Status RESOLVED 2026-08-16 (spec-check) [2/5] Closing F3 (MAJOR) from the adversarial review → User selects: "the finding does not hold: retries are handled by the gateway" → Spec untouched → Report: F3 Status REJECTED 2026-08-16 (spec-check) ... [specs-kit] 2 blocker and 2 major closed, 1 major rejected. [specs-kit] F5, F6, F9 target tasks/ — run /skill:specs-kit-spec-to-tasks for those. [specs-kit] Re-run /skill:specs-kit-adversarial-review to confirm the blockers fell. ``` ### Example 3: Nessun marker, scan completo (fallback) ```bash /skill:specs-kit-spec-check docs/specs/004-analytics/ ``` **Output**: ``` No [NEEDS CLARIFICATION] markers found. Running full structured scan... [1/5] Completeness: How is "real-time" defined? (Recommended: <5s user, <30s background) → ... ``` ### Example 4: Already complete spec ```bash /skill:specs-kit-spec-check docs/specs/001-hotel-search-aggregation/ ``` **Output**: ``` Analyzing spec: docs/specs/001-hotel-search-aggregation/2026-03-07--hotel-search-specs.md Quality Scan Results: - Completeness and Clarity: Clear - Requirements Traceability: Clear - Acceptance Criteria: Clear - Edge Cases Coverage: Clear No critical ambiguities detected worth formal clarification. The specification is well-formed and ready for task generation. Next step: /skill:specs-kit-spec-to-tasks docs/specs/001-hotel-search-aggregation/ ``` --- ## Integration with Other Commands ### After specs.brainstorm The primary workflow. Run spec-check after brainstorming to resolve any [NEEDS CLARIFICATION] markers: ```bash # Step 1: Generate spec from idea (may produce [NEEDS CLARIFICATION] markers) /skill:specs-kit-brainstorm "Implement checkout flow with payment processing" # Step 2: Resolve markers and scan for ambiguities /skill:specs-kit-spec-check docs/specs/005-checkout/ # Step 3: Generate tasks /skill:specs-kit-spec-to-tasks docs/specs/005-checkout/ ``` ### After specs-kit-adversarial-review When the panel returns BLOCKED, the findings that target the specification come back here. Each pass closes what it can and records the result in the review report; the loop ends when no open finding targets the spec: ```bash # The panel finds defects and blocks the workflow /skill:specs-kit-adversarial-review --spec=docs/specs/003-checkout/ # Close the findings that target the specification /skill:specs-kit-spec-check docs/specs/003-checkout/ # Findings that target the task set are fixed where they live /skill:specs-kit-spec-to-tasks docs/specs/003-checkout/ # Confirm the blockers fell — the spec the panel read no longer exists /skill:specs-kit-adversarial-review --spec=docs/specs/003-checkout/ ``` The re-review is never launched automatically: a panel is metered, and only the operator decides when it is worth paying for another round. ### Before specs.spec-to-tasks Always run spec-check before task generation to ensure specification completeness: ```bash /skill:specs-kit-spec-check docs/specs/006-reviews/ /skill:specs-kit-spec-to-tasks docs/specs/006-reviews/ ``` --- ## Todo Management During execution, maintain the todo list: ``` [ ] Phase 1: Discovery [ ] Phase 2: Spec Loading, Review Findings & Marker Extraction [ ] Phase 3: Question Prioritization [ ] Phase 4: Sequential Questioning (0/5 questions) [ ] Phase 5: [NEEDS CLARIFICATION] Cleanup [ ] Phase 5-bis: Review Report Status Update (skip if no report) [ ] Phase 6: Clarification Integration [ ] Phase 7: Validation [ ] Phase 8: Report Generation ``` Update status progressively. --- ## Notes - This command is **idempotent**: can be run multiple times - Clarification sessions are tracked with dates - Recommendations are based on industry-standard best practices - The command doesn't modify the general structure of the specification, only adds clarifications - Review findings are read from the **most recent** report only. Older reports are history: a finding that was closed there stays closed, and the panel's later opinion is the one that counts - The skill never edits tasks, technical plans or code, not even when a finding points straight at them. It names the skill that owns the fix and leaves the finding open - For heavier structural changes, use `/skill:specs-kit-brainstorm` to regenerate