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 < medium < high < xhigh < max, so xhigh and max are already above high) AND you are Sonnet or Opus. If effort is low or medium (i.e. 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:

{
  "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:

## 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

Architecture Alignment Status

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)