From sdd-workflow
Check consistency between implementation code and design documents (design), detecting discrepancies
How this skill is triggered — by the user, by Claude, or both
Slash command
/sdd-workflow:check-specThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Verifies consistency between implementation code and design documents (`*_design.md`), detecting discrepancies.
examples/scope_confirmation.mdexamples/serena_symbol_analysis.mdreferences/document_dependencies.mdreferences/prerequisites_directory_paths.mdreferences/prerequisites_plugin_update.mdreferences/prerequisites_principles.mdscripts/find-design-docs.shtemplates/en/check_spec_output.mdtemplates/ja/check_spec_output.mdVerifies consistency between implementation code and design documents (*_design.md), detecting discrepancies.
Role: This command specializes in design <-> implementation consistency checking.
Document-level consistency (PRD <-> spec, spec <-> design) is handled by the spec-reviewer
agent when called with the --full option.
Read the following prerequisite references before execution:
references/prerequisites_plugin_update.md - Check for plugin updatesreferences/prerequisites_principles.md - Read AI-SDD principles documentreferences/prerequisites_directory_paths.md - Resolve directory paths using SDD_* environment variablesSee references/document_dependencies.md for the document dependency chain and direction meaning.
Output templates are located under templates/${SDD_LANG:-en}/ within this skill directory.
The SDD_LANG environment variable determines the language (default: en).
$ARGUMENTS
| Argument | Required | Description |
|---|---|---|
feature-name | - | Target feature name or path (e.g., user-auth, auth/user-login). If omitted, all design docs are targeted |
--full: In addition to consistency checking, also runs quality review by the spec-reviewer agent
/check-spec user-auth # Consistency check only (default)
/check-spec task-management --full # Consistency check + quality review
/check-spec --full # Comprehensive check for all specifications
/check-spec # Without arguments, targets all specifications (consistency check only)
When executed without arguments, display the list of target files and ask for user confirmation before starting the process.
Reference: examples/scope_confirmation.md
Replace placeholders with actual file names and counts.
Post-confirmation behavior:
Optimized Execution Flow:
Phase 1: Shell Script - Execute find-design-docs.sh to scan design documents:
bash "${CLAUDE_PLUGIN_ROOT}/skills/check-spec/scripts/find-design-docs.sh" [feature-name]
This script:
*_design.md) in flat or hierarchical structure*_spec.md)$CLAUDE_ENV_FILE:
CHECK_SPEC_DESIGN_FILES - List of design filesCHECK_SPEC_SPEC_FILES - List of spec filesCHECK_SPEC_MAPPING - JSON mapping filePhase 2: Claude - Read design docs from pre-scanned lists and perform consistency check
Target design documents (*_design.md). Both flat and hierarchical structures are supported.
For flat structure:
With argument -> Target the following file:
- ${CLAUDE_PROJECT_DIR}/${SDD_SPECIFICATION_PATH}/{argument}_design.md
Without argument -> Target all *_design.md files under ${CLAUDE_PROJECT_DIR}/${SDD_SPECIFICATION_PATH}/ (recursively)
For hierarchical structure (when argument contains /, or when specifying hierarchical path):
Argument in "{parent-feature}/{feature-name}" format -> Target the following file:
- ${CLAUDE_PROJECT_DIR}/${SDD_SPECIFICATION_PATH}/{parent-feature}/{feature-name}_design.md
Argument is "{parent-feature}" only -> Target the following files:
- ${CLAUDE_PROJECT_DIR}/${SDD_SPECIFICATION_PATH}/{parent-feature}/index_design.md (parent feature design)
- ${CLAUDE_PROJECT_DIR}/${SDD_SPECIFICATION_PATH}/{parent-feature}/*_design.md (child feature designs)
Naming convention:
_design suffix required (index_design.md, {feature-name}_design.md)Hierarchical structure input examples:
/check-spec auth/user-login # Check user-login feature under auth domain
/check-spec auth # Check entire auth domain
Extract the following information from *_design.md:
| Item | Description |
|---|---|
| Module Structure | Directory structure, file organization |
| Technology Stack | Libraries, frameworks used |
| Interface Definitions | API signatures (function names, arguments, return values), type definitions, data models |
| Functional Requirements | List of features to implement |
| Implementation Approach | Architecture patterns, design decisions |
Search for code corresponding to specification contents:
Note: This command specializes in design <-> implementation consistency checking. Document-level consistency
(PRD <-> spec, spec <-> design) and quality review (CONSTITUTION.md compliance, completeness, clarity) are handled by
the spec-reviewer agent when using the --full option.
If documents contain YAML front matter, call the front-matter-reviewer agent to validate.
Pass all target document paths (design docs and corresponding specs).
After results are returned, integrate impl-status findings into the design ↔ implementation consistency results.
| Check Target | Verification Content | Importance |
|---|---|---|
| API Signature | Do function names, arguments, return values match? | High |
| Type Definitions | Do interfaces and types match? | High |
| Module Structure | Does directory/file structure match? | Medium |
| Functional Requirements | Are functions specified in specs implemented? | High |
| Technology Stack | Are documented libraries being used? | Low |
Classify detected discrepancies as follows:
Critical (Immediate Action Required):
Warning (Action Recommended):
Info (Reference):
When the --full option is specified, the spec-reviewer agent is invoked to perform comprehensive review.
| Check Item | Description |
|---|---|
| PRD <-> spec Traceability | Verify PRD requirements are covered in spec (80% coverage threshold) |
| spec <-> design Consistency | Verify spec content is properly detailed in design |
| CONSTITUTION.md Compliance | Verify compliance with project principles |
| Completeness | Verify required sections (purpose, API, constraints, etc.) are present |
| Clarity | Detect vague descriptions ("nice to have", "appropriately", etc.) |
| SysML Compliance | Verify requirement ID format (UR/FR/NFR-xxx) and traceability are proper |
Note: Comprehensive review requires additional execution time. For quick checks during development, run without
--full, and use --full before PR creation or for periodic checks.
Use the templates/${SDD_LANG:-en}/check_spec_output.md template for output formatting.
| Timing | Recommended Action |
|---|---|
| Before Implementation Start | Verify specification existence and content |
| At Implementation Completion | Verify consistency with specifications |
| Before PR Creation | Run as final verification |
| Periodic Check | Prevent documentation obsolescence |
If Serena MCP is enabled, high-precision consistency checking through semantic code analysis is possible.
serena is configured in .mcp.json| Feature | Description |
|---|---|
find_symbol | Search implementation code for APIs/functions documented in spec |
find_referencing_symbols | Understand usage locations of specific symbols to identify impact scope |
Reference: examples/serena_symbol_analysis.md
Even without Serena, consistency checking is performed using traditional text-based search (Grep/Glob). Features are limited but work language-agnostically.
/generate-spec firstnpx claudepluginhub toshikiimagawa/ai-sdd-workflow --plugin sdd-workflowVerifies implemented code against design.md, implementation.md, and tasks.md docs. Detects missing implementations, spec deviations, extra code, doc inconsistencies, outdated docs. Use after tasks or mid-feature.
Reviews spec.md files for completeness, clarity, implementability, testability, and structure. Identifies ambiguities, gaps, and missing sections before implementation.
Reviews design artifacts (proposals, specs, designs, tasks) for internal consistency, gaps, and cross-artifact alignment before implementation.