277 lines
8.9 KiB
Markdown
277 lines
8.9 KiB
Markdown
---
|
|
name: project-alignment-validation
|
|
version: 1.0.0
|
|
type: knowledge
|
|
description: Semantic validation patterns for PROJECT.md alignment (GOALS, SCOPE, CONSTRAINTS, ARCHITECTURE)
|
|
keywords: alignment, PROJECT.md, validation, GOALS, SCOPE, CONSTRAINTS, ARCHITECTURE, semantic, gap, conflict, resolution
|
|
auto_activate: true
|
|
allowed-tools: [Read, Grep, Glob]
|
|
---
|
|
|
|
# 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:
|
|
|
|
```markdown
|
|
## 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:
|
|
|
|
```markdown
|
|
## 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. **Semantic First**: Understand intent before applying validation rules
|
|
6. **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
|