---
name: check-specs-alignment
description: Verify alignment between code and specs. Usage /groundwork:check-specs-alignment
argument-hint: "[alignment-context]"
allowed-tools: ["Read", "Glob", "Grep", "Task", "Skill"]
---

# 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` or higher AND you are Sonnet or Opus.
If effort is below `high`, you MUST show the recommendation prompt — regardless of model.
If you are not Sonnet or Opus, you MUST show the recommendation prompt - regardless of effort level.

Otherwise → use `AskUserQuestion`:

```json
{
  "questions": [{
    "question": "Do you want to switch? Drift detection and categorization across implementation and specs benefits from consistent reasoning.\n\nTo switch: cancel, run `/effort high` (and `/model sonnet` if on Haiku), then re-invoke this skill.",
    "header": "Recommended: Sonnet or Opus at high effort",
    "options": [
      { "label": "Continue" },
      { "label": "Cancel — I'll switch first" }
    ],
    "multiSelect": false
  }]
}
```

If the user selects "Cancel — I'll switch first": output the switching commands above and stop. Do not proceed with the skill.

## Step 0: Resolve Project Context

**Before loading specs, ensure project context is resolved:**

1. **Monorepo check:** Does `.groundwork.yml` exist at the repo root?
   - If yes → Is `{{project_name}}` non-empty?
     - If empty → Invoke `Skill(skill="groundwork:select-project")` to select a project, then restart this skill.
     - If set → Project is `{{project_name}}`, specs at `{{specs_dir}}/`.
   - If no → Continue (single-project repo).
2. **CWD mismatch check (monorepo only):**
   - Skip if not in monorepo mode or if the project was just selected in item 1 above.
   - If CWD is the repo root → fine, proceed.
   - Check which project's path CWD falls inside (compare against all projects in `.groundwork.yml`).
   - If CWD is inside the selected project's path → fine, proceed.
   - If CWD is inside a different project's path → warn via `AskUserQuestion`:
     > "You're working from `<cwd>` (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).
3. 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

3. **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

2. **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:

```markdown
## 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)
```