Project Alignment Validation Skill

Comprehensive patterns for validating alignment between features, code, and PROJECT.md. Focuses on semantic validation (intent and goals) rather than literal pattern matching.

When This Skill Activates

Validating feature alignment with PROJECT.md
Assessing gaps between current state and goals
Resolving conflicts between documentation and implementation
Checking GOALS, SCOPE, CONSTRAINTS, ARCHITECTURE compliance
Keywords: "alignment", "PROJECT.md", "validation", "GOALS", "SCOPE", "semantic", "gap"

Core Validation Approach

Semantic Validation Philosophy

Semantic validation focuses on understanding the intent and purpose behind requirements, not just literal text matching.

Key Principles:

Intent over Syntax: Validate that features serve project goals, not just match keywords
Context-Aware: Consider project phase, constraints, and strategic direction
Progressive Assessment: Start with high-level goals, drill down to details
Graceful Gaps: Identify gaps without blocking progress; prioritize by impact

Contrast with Literal Validation:

❌ Literal: "Feature must contain keyword 'authentication'"
✅ Semantic: "Feature must support project's user management goals"

PROJECT.md Structure

Four Core Sections

Every PROJECT.md should define:

GOALS: Strategic objectives and desired outcomes
SCOPE: What's in scope (and explicitly out of scope)
CONSTRAINTS: Technical, resource, and policy limitations
ARCHITECTURE: High-level design principles and patterns

Validation Checklist

For each feature, validate against all four sections:

## Alignment Checklist

### GOALS Alignment
- [ ] Feature serves at least one project goal
- [ ] Feature doesn't conflict with any goals
- [ ] Feature priority matches goal priority
- [ ] Success metrics align with goal metrics

### SCOPE Alignment
- [ ] Feature is explicitly in scope
- [ ] Feature doesn't overlap with out-of-scope items
- [ ] Feature respects scope boundaries
- [ ] Feature dependencies are in scope

### CONSTRAINTS Alignment
- [ ] Feature respects technical constraints
- [ ] Feature works within resource constraints
- [ ] Feature complies with policy constraints
- [ ] Feature considers timeline constraints

### ARCHITECTURE Alignment
- [ ] Feature follows architectural patterns
- [ ] Feature integrates with existing components
- [ ] Feature respects design principles
- [ ] Feature maintains architectural consistency

See: docs/alignment-checklist.md for detailed checklist with examples

Gap Assessment Methodology

Identify Gaps

Gaps occur when current state doesn't match desired state defined in PROJECT.md.

Types of Gaps:

Feature Gaps: Missing functionality needed to achieve goals
Documentation Gaps: PROJECT.md doesn't reflect actual implementation
Constraint Gaps: Implementation violates stated constraints
Architectural Gaps: Code doesn't follow design principles

Prioritize Gaps

Not all gaps are equal. Prioritize by:

Impact Assessment:

Critical: Blocks primary goals, violates hard constraints
High: Significantly delays goals, creates technical debt
Medium: Slows progress, reduces quality
Low: Minor inconvenience, cosmetic issues

Effort Estimation:

Quick Win: High impact, low effort (prioritize)
Strategic: High impact, high effort (plan carefully)
Tactical: Medium impact, medium effort (schedule)
Defer: Low impact, high effort (defer or drop)

Document Gaps

Use standardized gap assessment template:

## Gap Assessment

### Gap Summary
- **Type**: [Feature/Documentation/Constraint/Architectural]
- **Impact**: [Critical/High/Medium/Low]
- **Effort**: [Quick Win/Strategic/Tactical/Defer]

### Current State
[Describe what exists today]

### Desired State
[Describe what PROJECT.md defines]

### Gap Details
[Explain the specific differences]

### Recommended Action
[Propose concrete steps to close gap]

### Dependencies
[List any prerequisites or blockers]

See: docs/gap-assessment-methodology.md for complete methodology

Conflict Resolution Patterns

Detect Conflicts

Conflicts arise when:

Feature serves one goal but violates another
Feature is in scope but violates constraints
Implementation follows architecture but misses goals
Documentation and code tell different stories

Resolution Strategies

Strategy 1: Update PROJECT.md (Documentation is wrong)

Current state is correct, PROJECT.md is outdated
Update PROJECT.md to reflect actual strategic direction
Validate changes with stakeholders

Strategy 2: Modify Feature (Implementation is wrong)

PROJECT.md is correct, feature needs adjustment
Refactor feature to align with goals/scope/constraints
May require re-planning or re-architecting

Strategy 3: Negotiate Compromise (Both partially correct)

Find middle ground that serves goals within constraints
May require adjusting both PROJECT.md and implementation
Document trade-offs and rationale

Strategy 4: Escalate Decision (Requires stakeholder input)

Conflict involves strategic direction or priorities
Present options with trade-offs to decision makers
Document decision and update PROJECT.md

See: docs/conflict-resolution-patterns.md for detailed resolution workflows

Progressive Disclosure

This skill provides layered documentation:

Always Available (Frontmatter)

Skill name and description
Keywords for auto-activation
Quick reference to core concepts

Available in Full Content

Detailed alignment checklist
Semantic validation approach
Gap assessment methodology
Conflict resolution patterns
Templates for reports and assessments
Real-world examples and scenarios

Load Full Content When Needed

Creating alignment reports
Assessing project health
Resolving complex conflicts
Onboarding new projects
Validating strategic changes

Documentation Resources

Comprehensive Guides

docs/alignment-checklist.md - Standard validation steps for GOALS/SCOPE/CONSTRAINTS/ARCHITECTURE
docs/semantic-validation-approach.md - Semantic vs literal validation philosophy
docs/gap-assessment-methodology.md - Identify, prioritize, and document gaps
docs/conflict-resolution-patterns.md - Strategies for resolving alignment conflicts

Templates

templates/alignment-report-template.md - Standard structure for alignment reports
templates/gap-assessment-template.md - Gap documentation template
templates/conflict-resolution-template.md - Conflict resolution workflow

Examples

examples/alignment-scenarios.md - Common scenarios and recommended fixes
examples/misalignment-examples.md - Real-world misalignment cases
examples/project-md-structure-example.md - Well-structured PROJECT.md

Integration Points

Agents

alignment-validator: Use checklist for quick validation
alignment-analyzer: Use gap assessment for detailed analysis
project-progress-tracker: Use GOALS validation for progress tracking

Hooks

validate_project_alignment.py: Use checklist for pre-commit validation
auto_update_project_progress.py: Use GOALS tracking patterns
enforce_pipeline_complete.py: Use alignment patterns for feature validation

Libraries

alignment_assessor.py: Use gap assessment methodology
project_md_updater.py: Use conflict resolution patterns
brownfield_retrofit.py: Use alignment checklist for retrofit analysis

Best Practices

Validate Early: Check alignment before implementation, not after
Document Decisions: Record why features align or don't align
Update Iteratively: PROJECT.md should evolve with project understanding
Prioritize Gaps: Not all gaps are critical; focus on high-impact items
Semantic First: Understand intent before applying validation rules
Graceful Degradation: Alignment issues are warnings, not blockers (unless critical)

Success Criteria

Feature validation is successful when:

✓ Feature clearly serves at least one project goal
✓ Feature is explicitly in scope (or scope updated to include it)
✓ Feature respects all constraints (or constraints documented as trade-offs)
✓ Feature follows architectural patterns (or deviations justified)
✓ Gaps are identified, prioritized, and tracked
✓ Conflicts are resolved with documented rationale

Last Updated: 2025-11-16 Version: 1.0.0 Related Skills: semantic-validation, file-organization, research-patterns, project-management

project-alignment-validation