Analyze specification files for contradictions, inconsistencies, and ambiguities
/plugin marketplace add teliha/dev-workflows/plugin install dev-workflows@dev-workflowsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
README.mdThis skill automatically activates when:
specs/ directoryFind all specification files:
# Default location
find specs/ -name "*.md" -type f
# Also check common locations
find docs/ -name "*spec*.md" -type f
find requirements/ -name "*.md" -type f
CRITICAL: Read ALL specification files completely before analysis.
PARALLELIZATION OPPORTUNITY: When there are multiple spec files, read them in parallel using multiple subagents:
Use the Task tool with multiple parallel invocations:
Task 1: Read and extract from specs/auth.md
Task 2: Read and extract from specs/api.md
Task 3: Read and extract from specs/data-model.md
...
Each subagent extracts:
- Key statements and requirements
- Defined terms and concepts
- Cross-references to other specs
- Numerical values and thresholds
Example parallel invocation:
Launch 3+ subagents simultaneously, each with:
- subagent_type: "general-purpose"
- prompt: "Read [spec_file] and extract: 1) All requirements 2) Defined terms 3) Numerical values 4) Cross-references. Return structured JSON."
For each file:
Analyze for the following issue types:
Statements that directly conflict with each other.
Examples:
# File: specs/auth.md
"Users must re-authenticate every 24 hours"
# File: specs/security.md
"Session tokens never expire for premium users"
Check for:
Similar features described differently across specs.
Examples:
# File: specs/api.md
"API responses use camelCase"
# File: specs/data-model.md
"All fields use snake_case"
Check for:
Unclear or vague requirements that could be interpreted multiple ways.
Examples:
"The system should respond quickly" # How quickly?
"Large files are handled differently" # What size is "large"?
"Users have appropriate access" # What determines "appropriate"?
Check for:
Critical details that should be specified but aren't.
Examples:
Check for:
Specs that may not match current implementation.
Examples:
Check for:
When analyzing specs for contradictions, run multiple analysis tasks in parallel:
Use the Task tool with parallel subagents:
Task 1 (Numerical Analysis):
- Extract all numbers, limits, thresholds
- Compare across specs for conflicts
Task 2 (Terminology Analysis):
- Extract all defined terms
- Check for inconsistent usage
Task 3 (Flow Analysis):
- Extract all state machines and flows
- Check for missing transitions or conflicts
Task 4 (Cross-Reference Analysis):
- Extract all references between specs
- Verify all referenced items exist
This parallelization can reduce analysis time by 3-4x for large spec sets.
Generate a comprehensive report:
# Specification Analysis Report
**Generated**: [YYYY-MM-DD HH:MM]
**Files Analyzed**: [count]
**Issues Found**: [count]
---
## Summary
| Category | Count | Severity |
|----------|-------|----------|
| Direct Contradictions | X | Critical |
| Inconsistencies | X | High |
| Ambiguities | X | Medium |
| Missing Information | X | Medium |
| Outdated Information | X | Low |
---
## Direct Contradictions
### [CRITICAL] Contradiction #1: [Title]
**Files**:
- `specs/file1.md` (line X)
- `specs/file2.md` (line Y)
**Statement 1**:
> [Quote from file 1]
**Statement 2**:
> [Quote from file 2]
**Impact**:
[What could go wrong if not resolved]
**Clarifying Questions**:
1. Which statement is correct?
2. Under what conditions does each apply?
---
## Inconsistencies
### [HIGH] Inconsistency #1: [Title]
**Files**:
- `specs/file1.md`
- `specs/file2.md`
**Description**:
[Detailed explanation]
**Suggested Resolution**:
[How to make consistent]
---
## Ambiguities
### [MEDIUM] Ambiguity #1: [Title]
**File**: `specs/file.md` (line X)
**Statement**:
> [Ambiguous quote]
**Possible Interpretations**:
1. [Interpretation A]
2. [Interpretation B]
**Clarifying Questions**:
1. [Question to resolve ambiguity]
---
## Missing Information
### [MEDIUM] Missing #1: [Title]
**File**: `specs/file.md`
**Context**:
[What the spec describes]
**Missing**:
[What information is needed]
**Impact**:
[Why this matters]
---
## Outdated Information
### [LOW] Outdated #1: [Title]
**File**: `specs/file.md` (line X)
**Issue**:
[What appears outdated]
**Evidence**:
[Why we think it's outdated]
---
## Recommendations
### High Priority
1. [Action item]
2. [Action item]
### Medium Priority
1. [Action item]
### Low Priority
1. [Action item]
---
## Questions for Team
These questions should be answered to resolve ambiguities:
1. [Question 1]
2. [Question 2]
3. [Question 3]
name: Spec Check
on:
pull_request:
paths:
- 'specs/**/*.md'
- 'docs/**/*.md'
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: anthropics/claude-code-action@v1
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
prompt: /check-spec-contradictions
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.