check-specs-alignment
Verify alignment between code and specs. Usage /groundwork:check-specs-alignment
etr · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add etr/groundwork --skill check-specs-alignmentAbout this skill
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, 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:
- Monorepo check: Does
.groundwork.ymlexist 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 empty → Invoke
- If no → Continue (single-project repo).
- If yes → Is
- 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).
- 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.mdfiles)
- Single file:
-
Architecture - Architecture decisions
- Single file:
{{specs_dir}}/architecture.md - Directory:
{{specs_dir}}/architecture/(aggregate all.mdfiles)
- Single file:
-
Tasks - Task list (if exists)
- Single file:
{{specs_dir}}/tasks.md - Directory:
{{specs_dir}}/tasks/(aggregate all.mdfiles)
- Single file:
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:
-
Search codebase for implementation evidence using the requirement's keywords and expected behavior
-
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
-
Detect undocumented features - Code functionality that doesn't trace to any PRD requirement
Step 3: Check Architecture Alignment
For each architecture decision (DR-NNN):
-
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
-
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 |
|----------
Read the complete source ↗