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