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:

Completeness and Clarity
- Vague expressions ("robust", "intuitive", "fast")
- Terms not defined in glossary
- Internal contradictions
- Missing or incomplete sections
Requirements Traceability
- User request → specification alignment
- Requirements → tasks coverage (if tasks exist)
- Clear origin for each requirement
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
Edge Cases Coverage
- Edge cases identified
- Error handling documented
- Explicit constraints and limitations
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
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

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:

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

Extracts ALL [NEEDS CLARIFICATION: ...] markers from the spec
Converts each marker into a structured question (multi-choice or short-answer)
Presents them as the FIRST questions (before scan-generated questions)
Removes the marker from the spec after resolution
Integrates the answer into the appropriate section

Phase 1: Discovery

Goal: Identify the specification to review and gather context

Actions:

Create todo list with all phases
Parse the skill arguments to extract the specification path
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
Verify the folder exists
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)
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)

Resolve and read the specification file:
- YYYY-MM-DD--feature-name.md
- Fallback: only dated spec-like markdown in folder
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.

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.
Skip findings already closed: a finding carrying a Status: line other than OPEN was handled in an earlier session and is not asked again.

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.

Severity filter: BLOCKER and MAJOR always enter the queue. MINOR enters only if the quota is not already spent by higher-priority items.
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.
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

Scan the ENTIRE spec text for the pattern:
```
\[NEEDS CLARIFICATION:([^\]]+)\]
```

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
  }
]

DEDUPLICATION: If multiple markers ask semantically equivalent questions, keep the most specific and merge context
LIMIT: If > 3 markers found, keep only the 3 most critical (scope > security > UX > technical)
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
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:

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
Append marker-derived questions (from 2b)
Append scan-derived questions (from 2c) — ordered by impact × uncertainty
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
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:

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
Stop conditions:
- All questions answered
- User signals completion ("done", "proceed")
- Reached 5 questions
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
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:

Final scan of the spec for any remaining [NEEDS CLARIFICATION: ...] markers
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"
Validation:
- No [NEEDS CLARIFICATION string should remain unless explicitly deferred
- Clarifications section has one entry per resolved question
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:

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

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.

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.

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:

Generate summary with:
- Number of questions asked and answered
- Path of updated specification
- Sections touched
- Coverage summary table

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

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)

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

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

About this skill

Overview

When [NEEDS CLARIFICATION] markers exist

When no [NEEDS CLARIFICATION] markers exist

Workflow Position

Dimensions of Quality

Usage

Arguments

Current Context

Core Principles

Integration with specs.brainstorm

Marker Generation (in specs.brainstorm)

Marker Resolution (in this command)

Phase 1: Discovery

Phase 2: Spec Loading & Marker Extraction

2a. Spec Loading (identica a prima)

2b-bis. Adversarial Review Findings Extraction

2b. [NEEDS CLARIFICATION] Extraction

2c. Structured Quality Scan

Phase 3: Question Prioritization

Phase 4: Sequential Questioning Loop

Phase 5: [NEEDS CLARIFICATION] Cleanup

Phase 5-bis: Review Report Status Update

Phase 6: Clarification Integration

Phase 7: Validation

Phase 8: Report Generation

Error Handling

Specification not found

No ambiguities detected

Review report present but every finding already closed

Review report unparseable

Review report status could not be written

File write failed

Examples

Example 1: Spec with [NEEDS CLARIFICATION] markers

Example 2: Closing the findings of an adversarial review

Example 3: Nessun marker, scan completo (fallback)

Example 4: Already complete spec

Integration with Other Commands

After specs.brainstorm

After specs-kit-adversarial-review

Before specs.spec-to-tasks

Todo Management

Notes