Check Specs Alignment

Check Alignment Skill

Verifies that implementation aligns with product specs and architecture, surfacing misalignments for resolution.

Pre-flight: Model Recommendation

Your current effort level is {{effort_level}}.

Skip this step silently if effort is high, xhigh, or max (the scale is low "You're working from ` (inside **[cwd-project]**), but the selected Groundwork project is **[selected-project]** ([selected-project-path]/). What would you like to do?" > - "Switch to [cwd-project]" > - "Stay with [selected-project]" If the user switches, invoke Skill(skill="groundwork:select-project")`.

• If CWD doesn't match any project → proceed without warning (shared directory).

1. Proceed with the resolved project context. All {{specs_dir}}/ paths will resolve to the correct location.

Workflow

Step 1: Load All Context

Read the following specs (each may be a single file or directory):

• Product specs - PRD with EARS requirements
• Single file: {{specs_dir}}/product_specs.md
• Directory: {{specs_dir}}/product_specs/ (aggregate all .md files)

• Architecture - Architecture decisions
• Single file: {{specs_dir}}/architecture.md
• Directory: {{specs_dir}}/architecture/ (aggregate all .md files)

• Tasks - Task list (if exists)
• Single file: {{specs_dir}}/tasks.md
• Directory: {{specs_dir}}/tasks/ (aggregate all .md files)

Detection: Check for file first (takes precedence), then directory. When reading a directory, aggregate all .md files recursively with _index.md first, then numerically-prefixed files, then alphabetically.

Scan codebase for implementation:

• Source files in common locations (src/, lib/, app/, etc.)
• Configuration files
• Database schemas/migrations
• API definitions

If specs are missing: > "Cannot check alignment - missing specs: > - [List missing specs] > > Run the appropriate commands to create them: > - PRD: /groundwork:design-product > - Architecture: /groundwork:design-architecture > - Tasks: /groundwork:create-tasks"

Step 2: Check PRD Alignment

For each EARS requirement in the PRD:

1. Search codebase for implementation evidence using the requirement's keywords and expected behavior
2. Categorize the implementation status:

• Implemented - Code clearly implements the requirement
• Partially Implemented - Some aspects present, others missing
• Not Implemented - No evidence of implementation
• Deviated - Implementation differs from requirement

1. Detect undocumented features - Code functionality that doesn't trace to any PRD requirement

Step 3: Check Architecture Alignment

For each architecture decision (DR-NNN):

1. Verify implementation follows the decision by examining:

• Technology choices in package.json, requirements.txt, or equivalent
• Code patterns matching the documented approach
• Component structure matching architecture diagrams

1. Detect deviations:

• Different technology used than documented
• Different patterns than documented
• Missing components that should exist per architecture
• Extra components not mentioned in architecture

Step 4: Report Findings

Present the alignment report in a structured format:

## Alignment Report

### PRD Alignment

| Requirement | Status | Notes |
|-------------|--------|-------|
| PRD-XXX-REQ-001 | Implemented | Found in src/auth/login.ts |
| PRD-XXX-REQ-002 | Partial | Missing error handling for edge case |
| PRD-XXX-REQ-003 | Not Implemented | - |
| PRD-YYY-REQ-001 | Deviated | Uses polling instead of WebSocket |

**Summary:** X/Y requirements implemented, Z partial, W not implemented, V deviated

**Undocumented Features:**
- Feature X in src/foo.ts has no PRD requirement
- [Or "None detected" if clean]

### Architecture Alignment

| Decision | Status | Notes |
|----------|--------|-------|
| DR-001 | Aligned | PostgreSQL used as documented |
| DR-002 | Deviated | Using REST instead of GraphQL |
| DR-003 | Aligned | - |

**Summary:** X/Y decisions aligned, Z deviated

**Undocumented Components:**
- src/cache/ not mentioned in architecture
- [Or "None detected" if clean]

### Task Status Consistency

| Condition | Count | Tasks |
|-----------|-------|-------|
| Marked complete but code missing | N | TASK-003, TASK-007 |
| Code present but task not complete | N | TASK-005 |

Step 5: Suggest Resolution

Based on findings, provide actionable next steps:

For undocumented features: > "Run /groundwork:design-product to add requirements for undocumented feature X"

For PRD deviations: > "Either: > - Run /groundwork:source-product-specs-from-code to update the PRD to match implementation, OR > - Fix the implementation to match PRD requirement PRD-XXX-REQ-NNN"

For architecture deviations: > "Either: > - Run /groundwork:source-architecture-from-code to update architecture to match implementation, OR > - Refactor code to follow DR-NNN (currently using [actual] instead of [documented])"

For missing implementations: > "Run /groundwork:work-on-next-task to implement missing requirements, or /groundwork:work-on N to work on specific tasks"

Offer resolution options: > "Found [N] misalignments. Would you like me to: > 1. Update specs to match implementation (/groundwork:source-product-specs-from-code, /groundwork:source-architecture-from-code) > 2. List implementation changes needed to match specs > 3. Go through each misalignment individually"

Categories of Misalignment

PRD Alignment Status

| Status | Meaning | Resolution | |--------|---------|------------| | Implemented | Code matches requirement | None needed | | Partial | Some aspects implemented | Complete implementation or update PRD scope | | Not Implemented | No code for requirement | Implement via tasks or remove from PRD | | Deviated | Different from spec | Align code OR update PRD |

Architecture Alignment Status

| Status | Meaning | Resolution | |--------|---------|------------| | Aligned | Implementation follows decision | None needed | | Deviated | Different approach used | Refactor OR update architecture |

Search Patterns

When searching for implementation evidence:

Requirement Keywords

• Extract verbs: "shall create", "shall display", "shall validate"
• Extract nouns: user, order, payment, notification
• Search for related function/class names

Architecture Patterns

• Check imports/dependencies for technology choices
• Look for documented component names
• Verify directory structure matches architecture

Common Locations

src/           - Main source code
lib/           - Libraries
app/           - Application code (Next.js, Rails, etc.)
api/           - API routes
components/    - UI components
services/      - Service layer
models/        - Data models
database/      - Migrations, schemas
config/        - Configuration
tests/         - Test files (can verify expected behavior)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: etr
• Source: etr/groundwork
• License: MIT

Install and usage instructions live in the source repository linked above.