consistency-analysis

Consistency Analysis Skill

Purpose

This skill provides expertise in detecting inconsistencies, gaps, and conflicts across specification documents. It performs read-only cross-document analysis to ensure that requirements, tasks, data models, and plans are aligned and complete. The output is a structured analysis report with categorized findings and severity levels.

IMPORTANT: This skill NEVER modifies files. It is strictly a read-only analysis tool. All findings are reported for human review and resolution.

When It Activates

The skill is triggered when the conversation involves:

• Reviewing specification quality or completeness
• Checking cross-document consistency (spec vs. tasks vs. plan)
• Detecting gaps in requirement coverage or task traceability
• Identifying conflicting definitions across documents
• Performing traceability analysis between artifacts

Analysis Rule Categories

The skill evaluates documents against eight rule categories:

1. Requirement Coverage

Verify that every functional requirement (FR-XXX) and non-functional requirement (NFR-XXX) in the specification is addressed by at least one implementation task or plan item. Flag orphaned requirements with no downstream mapping.

2. Task Traceability

Ensure every task in tasks.md traces back to a specific requirement or user story in spec.md. Flag tasks with missing [Spec §X.Y] references or invalid reference targets.

3. Plan Alignment

Check that the implementation plan is consistent with the task list and specification. Detect mismatches in scope, ordering assumptions, or phase assignments between documents.

4. Data Model Consistency

Verify that entity definitions, field names, types, and relationships are consistent across the specification, data model section, and API contracts. Flag naming mismatches, type conflicts, or missing fields.

5. Contract Coverage

Ensure every API endpoint defined in the specification has corresponding tasks for implementation and testing. Flag endpoints missing from the task list or with incomplete request/response schema definitions.

6. Constitution Compliance

If a project constitution exists, verify that the specification and tasks comply with its architectural principles, technology constraints, and coding conventions.

7. Duplication Detection

Identify duplicate or near-duplicate requirements, tasks, or definitions across documents. Flag redundancies that may lead to conflicting implementations or wasted effort.

8. Ambiguity Detection

Scan for vague, unmeasurable, or subjective language in requirements (e.g., "fast," "user-friendly," "scalable"). Flag ambiguous terms that need quantification or clarification.

Severity Classification

Each finding is assigned a severity level:

Severity	Meaning	Action Required
CRITICAL	Blocking issue that prevents correct implementation	Must resolve before proceeding
HIGH	Significant gap or conflict likely to cause defects	Should resolve before implementation
MEDIUM	Inconsistency that may cause confusion or rework	Resolve during implementation
LOW	Minor style or convention issue	Resolve at convenience

Report Output Format

The analysis report is structured as follows:

# Consistency Analysis Report

## Summary
- Total findings: N
- Critical: N | High: N | Medium: N | Low: N

## Findings

### [CRITICAL] RC-001: FR-012 has no implementing task
- **Category**: Requirement Coverage
- **Location**: spec.md FR-012
- **Details**: Payment retry logic requirement has no corresponding task in tasks.md.
- **Recommendation**: Add a task in the Stories phase covering FR-012.

### [HIGH] TT-001: Task T008 references non-existent FR-099
- **Category**: Task Traceability
- **Location**: tasks.md T008
- **Details**: The [Spec FR-099] reference does not match any requirement.
- **Recommendation**: Correct the reference or add the missing requirement.

Each finding includes an ID, category, location, detailed description, and a recommended resolution.

References

For detailed analysis rules, severity definitions, and configuration options, consult:

• references/analysis-rules.md -- Full rule definitions with detection logic for each category
• references/severity-levels.md -- Severity classification criteria and escalation guidelines