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:

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

# 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

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:

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

   \[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 <id> (<severity>) 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: <question> → A: <answer>, 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.

   ### F1 — BLOCKER — spec §Functional Requirements
   Raised by: <model A>, <model C>
   **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 <date> (spec-check)	the specification was changed; Resolution: says how
   REJECTED <date> (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.

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

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 <date>.
Continuing with markers and the quality scan.

Review report unparseable

[specs-kit] Warning: adversarial-review/<file> 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 <report>: [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

/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

/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: <model A>, <model C>
  → 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)

/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

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

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

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

/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