| name | analyze |
| description | Cross-artifact consistency check between spec documents and tech decomposition. Use when asked to 'analyze consistency', 'check alignment', 'verify spec matches plan', 'traceability check', 'spec drift', 'are my docs aligned', or after /ct completes to verify the tech decomposition covers all requirements. Also invoked automatically as GATE 4 in /ct. NOT for code review (use /sr), NOT for code analysis (use /code-analysis), NOT for debugging (use /dbg). |
| argument-hint | ["task-directory"] |
| allowed-tools | Read, Grep, Glob, AskUserQuestion |
Analyze: Cross-Artifact Consistency Check
Announcement: Begin with: "I'm using the analyze skill for cross-artifact consistency checking."
Purpose
Verify that the tech decomposition OUTPUT of /ct is fully aligned with the spec INPUT (discovery/JTBD/PRD docs). Catches drift between what was specified and what was planned — BEFORE implementation begins.
This skill is read-only. It reads and reports — no file writes, no agents, no code changes.
Step 1: Locate Artifacts
Find the task directory and its documents:
- If argument provided: match against
tasks/task-*[argument]*/
- If no argument: list recent task directories, ask user to select
Required artifacts (at least one spec + one plan):
| Type | Files to look for |
|---|
| Spec (input) | discovery-*.md, JTBD-*.md in task directory; PRD-*.md in docs/product-docs/PRD/; JTBD-*.md in docs/product-docs/JTBD/ |
| Plan (output) | tech-decomposition-*.md (or phase-*/tech-decomposition-*.md if split) |
If spec docs are missing: Report "No spec documents found — cannot verify alignment. This task was created without /nf or /product documentation." Verdict: SKIPPED.
If tech decomposition is missing: Report "No tech decomposition found — run /ct first." Verdict: SKIPPED.
Step 2: Extract Requirements
Read all spec documents and extract a numbered list of requirements:
- From discovery docs: walk every top-level heading. Extract requirements from
How It Works, In Scope, Key Requirements, Constraints (and their older equivalents: Functional/Non-Functional Requirements, UI/UX Specifications, acceptance scenarios). For any heading you are unsure about, include it in a [UNCERTAIN-SOURCE] note rather than skipping.
- From JTBD docs: Core Needs, Desired Outcomes
- From PRD docs: Functional Requirements, User Stories, Acceptance Criteria
Assign each requirement an ID: REQ-001, REQ-002, etc.
Also extract: any unresolved [NEEDS CLARIFICATION: ...] markers — these are immediate blockers.
Step 3: Extract Test Cases
Read the tech decomposition's Test Plan section. Extract all test cases with their Given/When/Then definitions.
Assign each test case an ID: TEST-001, TEST-002, etc.
Step 4: Extract Implementation Steps
Read the tech decomposition's Implementation Steps section. Extract all steps and sub-steps.
Note any existing [REQ-XXX] traceability tags already present on steps.
Step 5: Build Traceability Matrix
Map the three dimensions:
Requirement (REQ-XXX) → Test Case (TEST-XXX) → Implementation Step (Step X.X)
For each requirement, determine:
- Does at least one test case verify this requirement?
- Does at least one implementation step fulfill this requirement?
For each implementation step, determine:
- Does it trace back to a requirement, either by explicit
[REQ-XXX] tag or by covering one or more sub-clauses of a requirement? If it only covers part of a requirement, flag the uncovered portion as a separate [UNCOVERED] finding for that sub-clause.
- Does it have an associated test?
Step 6: Flag Gaps (coverage pass)
Report every gap you find, including low-signal ones. Do not suppress findings based on severity at this stage — a separate verification step will filter. Annotate each finding with a tag and a severity guess:
| Tag | Meaning | Default severity |
|---|
[UNCOVERED] | Requirement has no test case | Major |
[UNTESTED] | Implementation step has no associated test | Minor |
[SCOPE CREEP] | Implementation step maps to no requirement | Major |
[CONFLICT] | Requirement contradicts a tech decision or another requirement | Critical |
[UNRESOLVED] | [NEEDS CLARIFICATION] marker not yet resolved | Critical |
Step 6a: Verdict (filter pass)
Apply severity gating only when computing the final verdict, not when collecting findings.
Step 7: Report & Verdict
Present the report to the user:
## Consistency Analysis: [Task Name]
### Traceability Matrix
| REQ | Description | Test | Step | Status |
|-----|-------------|------|------|--------|
| REQ-001 | [brief] | TEST-001 | Step 1.1 | Covered |
| REQ-002 | [brief] | — | Step 2.1 | [UNCOVERED] |
| REQ-003 | [brief] | TEST-003 | — | [UNCOVERED] |
| — | — | — | Step 3.1 | [SCOPE CREEP] |
### Findings
- [UNCOVERED] REQ-002 "User can delete session" — no test case covers this requirement
- [SCOPE CREEP] Step 3.1 "Add caching layer" — no requirement references caching
### Verdict: ALIGNED | GAPS FOUND ([N] issues)
**Critical**: [count] | **Major**: [count] | **Minor**: [count]
Verdict rules:
- ALIGNED: 0 Critical, 0 Major gaps
- GAPS FOUND: Any Critical or Major gaps exist
If GAPS FOUND: Ask user via AskUserQuestion:
- Fix gaps — go back and update the tech decomposition
- Acknowledge and proceed — gaps are intentional or will be addressed later
- Re-run /nf — spec docs need revision first
Related Skills
| Need | Use |
|---|
| Create the tech decomposition | /ct |
| Feature discovery | /nf |
| Code review (post-implementation) | /sr |
| Implementation | /si |
