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:

1. Intent over Syntax: Validate that features serve project goals, not just match keywords
2. Context-Aware: Consider project phase, constraints, and strategic direction
3. Progressive Assessment: Start with high-level goals, drill down to details
4. 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:

1. GOALS: Strategic objectives and desired outcomes
2. SCOPE: What's in scope (and explicitly out of scope)
3. CONSTRAINTS: Technical, resource, and policy limitations
4. 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:

1. Feature Gaps: Missing functionality needed to achieve goals
2. Documentation Gaps: PROJECT.md doesn't reflect actual implementation
3. Constraint Gaps: Implementation violates stated constraints
4. 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

1. Validate Early: Check alignment before implementation, not after
2. Document Decisions: Record why features align or don't align
3. Update Iteratively: PROJECT.md should evolve with project understanding
4. Prioritize Gaps: Not all gaps are critical; focus on high-impact items
5. **Se